Getting Started
| Key | Value |
|---|---|
| Status | Active |
| Owner | QA Automation |
| Updated | 2026-03-26 |
| Scope | Local setup, first test runs, and first-day orientation |
This page is for someone joining the repo and trying to get productive without reading half the codebase first. The goal is simple: get the project installed, run a safe first test, and understand what the system produces when it runs.
What You Are Setting Up
PW-Tests is a Playwright-based quality platform for six CNC websites. A local setup gives you:
- smoke and suite-level test runs
- structured logs in
test-results/ - screenshots and traces for failures
- local access to the same scripts CI uses for Slack, reports, monitoring, and observability checks
You do not need every external integration configured on day one. Local testing works without Slack, Grafana, or OpenSearch.
Prerequisites
| Requirement | What To Have |
|---|---|
| Node.js | A recent Node 18+ environment |
| npm | Standard npm install support |
| Git | Any recent Git client |
| Playwright browsers | Installed locally after npm install |
Optional but useful:
| Optional Service | Why It Helps |
|---|---|
| Slack credentials | Lets you test Slack posting paths |
| Grafana service account | Lets you validate dashboards and OpenSearch proxy access |
| OpenSearch credentials | Lets you inspect live telemetry, retention setup, and observability quality |
First-Time Setup
| Step | Action | Why It Matters |
|---|---|---|
| 1 | Clone the repo and enter the workspace | Standard local setup |
| 2 | Run npm install | Installs dependencies and local scripts |
| 3 | Run npx playwright install | Installs Chromium, WebKit, and Firefox support |
| 4 | Copy .env.example to .env if needed | Gives you a place for local overrides and credentials |
| 5 | Start with one safe suite, not everything | You get a fast signal before going deeper |
Recommended First Runs
Start small. The best first run is one that tells you the environment works.
| Command | When To Use It | Expected Outcome |
|---|---|---|
SITE=auto npm run test:smoke | First local validation | Fast pass/fail on one site |
npm run test:smoke | First all-site check | Quick health pass across all configured sites |
npm run test:pdt | When you want deployment-style coverage | Broader functional confidence |
npm run test:e2e | When you want journey coverage | Slower, deeper, more failure context |
npm run test:mobile:smoke | When working on mobile-safe changes | PR-friendly mobile tier |
npm run test:content | When working on content-rendering or registry coverage | Registry-driven module validation |
What A Healthy First Run Looks Like
On a healthy local setup, you should see:
- Playwright start cleanly
- the target site open and handle consent
- per-test pass/fail output
- artifacts created only when needed
test-results/populated with logs and suite output
If the first run fails, that is still useful. The repo is built to leave evidence behind.
Where To Look After A Run
| Path | What You Will Find |
|---|---|
test-results/logs/ | Structured JSONL logs for AI and debugging workflows |
test-results/artifacts/ | Failure screenshots, traces, and per-test artifacts |
test-results/results.json | Machine-readable merged result file used by notifiers |
test-results/history/ | Run history used by recurrence and trend logic |
tests/visual.spec.ts-snapshots/ | Visual baselines when the visual suite is in play |
What To Configure Early
You can be productive with almost no configuration, but these settings usually come next:
| Setting Area | Why Teams Usually Add It Early |
|---|---|
SITE | Helpful for default single-site work |
| Slack credentials | Lets you test run alerts and reporting locally |
| Grafana token | Needed for dashboard deploy, validation, and some OpenSearch proxy flows |
| OpenSearch URL and token | Needed for telemetry verification and retention setup |
See Configuration Guide for the full environment map.
A Good First-Day Workflow
| Goal | Recommended Path |
|---|---|
| Learn the repo | Read Architecture Overview after your first passing smoke run |
| Understand suite purpose | Read Test Types |
| Find commands quickly | Use CLI Reference |
| Understand failures | Read Failure Categories and Troubleshooting |
| Work with alerts and dashboards | Read Integrations and Reporting |
Common “What Should I Run?” Answers
| Situation | Best Starting Command |
|---|---|
| “I just pulled main and want a fast confidence check.” | npm run test:smoke |
| “I’m working on deploy-critical behavior.” | npm run test:pdt |
| “I changed a full user path.” | npm run test:e2e or npm run test:user-flows |
| “I changed responsive or touch behavior.” | npm run test:mobile:smoke |
| “I changed content modules or registry entries.” | npm run test:content |
| “I’m investigating flaky production failures.” | npm run os:failed, then the relevant suite |
Use this when you want the full local operator setup, not just a passing test run.
| Item | Why It Helps |
|---|---|
Set up .env | Keeps local overrides explicit |
| Verify Slack posting | Makes notifier debugging much easier |
| Verify Grafana proxy access | Needed for OpenSearch and dashboard work |
Run npm run observability:verify:health | Confirms the monitoring stack can be reached |
| Run one content test and one mobile test | Gives you a feel for the two most specialized suites |
Read .confluence/WRITING_RULES.md | Important if you touch Confluence-source docs |
What New Contributors Usually Miss
- this repo has many npm scripts, but most work starts with a small handful
- the visual suite is baseline-dependent and behaves differently from text-first suites
- content tests are not generic page checks; they are registry-driven and handler-based
- Slack messages are part of the product surface, not an afterthought
- the Confluence-source docs in
docs/wiki/anddocs/confluence/are maintained as publishable source, not just internal notes
Next Stops
After this page, the best next reads are: