FOUNDATIONS · LESSON 2 OF 24

Understand the runner and configuration

Choose how tests are discovered, executed and reported.

testDir
baseURL
webServer
CLI

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

playwright.config.ts describes the suite. testDir selects test files, projects choose browsers, use provides context options and webServer starts the app. Keep test settings in version control so local and CI runs use the same assumptions.

Playwright transforms TypeScript so tests can run, but that does not replace type checking. npm run check invokes tsc separately. Type errors and failed browser assertions are different failures and need different fixes.

Run npm test -- --grep "configuration" to select a title. Run npx playwright test tests/lesson.spec.ts for a file and add --project=chromium for a project. --list shows discovered tests without launching browsers.

The local server cannot be reused accidentally because reuseExistingServer is false. If port 4174 is occupied, stop the known practice server or change both baseURL and the server port consistently. Do not kill an unrelated process blindly.

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('configuration resolves the local URL', async ({ page, baseURL }) => {
  expect(baseURL).toBe('http://127.0.0.1:4174');
  await page.goto('/');
  await expect(page).toHaveURL(`${baseURL}/`);
});

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-runner-and-configuration",
  "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

baseURL is available as a fixture as well as configuration.
A plain expect is suitable for an already-known configuration string.
toHaveURL retries against the live page state.

Verify your result

npx playwright test --list finds the configuration test.
The final URL is the local server root.

4. Practice independently

Run only this test by a substring of its title.

Show the explanation

Use npm test -- --grep "configuration". The double dash forwards arguments through npm to Playwright.

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.