DIAGNOSTICS AND DELIVERY · LESSON 21 OF 24

Debugging, traces, UI mode and code generation

Use evidence to explain failures and improve generated tests.

trace viewer
test.step
UI mode
codegen

Your runnable checkpoint

Extract into a new practice folder. Each download contains tests, configuration, the complete local practice app and an offline lesson. Use Node.js 22 or 24. Each checkpoint is independent.

Download lesson source ↓

Install dependencies and browser binaries using the commands below. The test runner starts the practice server on port 4174. Tests target localhost, never the production EduPoly site.

1. Understand the concepts

A useful failure report explains what action occurred, which condition failed and what the browser showed. Named test steps organize a longer scenario into readable evidence without changing its behavior.

The supplied configuration retains traces on failure and screenshots on failure. Open npm run report to inspect the HTML report. You can also open a trace ZIP with npx playwright show-trace followed by the file path. Traces can include page and network data; share only sanitized test artifacts.

Use npm run test:ui for interactive exploration or npm test -- --debug to inspect a test. A debugging session can behave differently because timing is slower, so return to a normal headless run after fixing the cause.

Codegen can record a starting point: in one terminal run npm run serve, then in another run npx playwright codegen http://127.0.0.1:4174. Review generated locators, add meaningful assertions and remove accidental actions. Stop the manual server before running the configured suite.

2. Build and run

These are complete test files and configuration. The download also includes app/ and server.mjs; preserve their paths. Stop any manually started practice server before running the suite.

Terminal

npm install
npx playwright install chromium
npm run check
npm test

tests/lesson.spec.ts

import { test, expect } from '@playwright/test';
test('describe a workflow with steps', async ({ page }) => {
  await test.step('open the task form', async () => { await page.goto('/'); });
  await test.step('create a task', async () => {
    await page.getByLabel('Task title', { exact: true }).fill('Debuggable task');
    await page.getByRole('button', { name: 'Add task', exact: true }).click();
  });
  await test.step('verify the result', async () => {
    await expect(page.getByTestId('task-row')).toContainText('Debuggable task');
  });
});

playwright.config.ts

import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 1 : 0,
  workers: process.env.CI ? 2 : undefined,
  timeout: 30000,
  expect: { timeout: 5000 },
  reporter: [['list'], ['html', { open: 'never' }]],
  use: { baseURL: 'http://127.0.0.1:4174', trace: 'retain-on-failure', screenshot: 'only-on-failure' },
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
  webServer: { command: 'node server.mjs', url: 'http://127.0.0.1:4174', reuseExistingServer: false, timeout: 15000 }
});

package.json

{
  "name": "edupoly-playwright-debugging-traces-and-codegen",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "test": "playwright test",
    "test:headed": "playwright test --headed",
    "test:ui": "playwright test --ui",
    "check": "tsc --noEmit",
    "report": "playwright show-report",
    "serve": "node server.mjs"
  },
  "devDependencies": {
    "@playwright/test": "1.56.1",
    "typescript": "5.9.3",
    "@types/node": "22.20.5"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": [
      "node"
    ],
    "noEmit": true
  },
  "include": [
    "tests/**/*.ts",
    "pages/**/*.ts",
    "playwright.config.ts"
  ]
}

.gitignore

node_modules/
playwright-report/
test-results/
playwright/.auth/
.env

3. Trace the code and check the result

test.step groups actions under a meaningful label.
The test still uses the same reliable locators and assertions.
Artifacts are generated by configuration rather than custom screenshot code in every assertion.

Verify your result

The test passes with three named steps.
After an intentional failure, the report includes retained evidence.

4. Practice independently

Temporarily expect the wrong task title and inspect the trace.

Show the explanation

Run the failing test, open the report, inspect its steps and DOM snapshots, then restore the correct assertion. Use the evidence to identify the mismatch rather than adding a delay.

When something goes wrong

If a browser executable is missing, run npx playwright install chromium in the project folder. If port 4174 is occupied, stop your manual practice server. Read assertion call logs for mismatched locators or expectations. Use npm run report to inspect failures; do not add fixed sleeps or broad resets to hide them.