FOUNDATIONS · LESSON 1 OF 24

Install Playwright and run your first test

Run a real browser test against your own local practice app.

Node.js
Playwright Test
TypeScript
browser binaries

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 Test launches browsers, performs user actions and checks outcomes. A test runner discovers spec files and manages isolation, reporting and retries. This course uses TypeScript, but you only need functions, objects, imports and async/await to start.

Use Node.js 22 or 24 and npm. Check node --version and npm --version. Download this checkpoint, extract it and open a terminal in its package.json folder. npm install installs the test runner; npx playwright install chromium downloads its matching browser. These are separate steps.

The downloads pin Playwright 1.56.1 and TypeScript 5.9.3 as a reproducible course baseline, not the latest releases. Installers and supported operating systems change: check the linked official installation guide before choosing a newer version. On Apple Silicon use native ARM64 Node.js.

Run npm run check, then npm test. The configuration starts the supplied app on 127.0.0.1:4174, waits until it is reachable and stops it after the tests. Do not start a second server on that port while running the suite. Tests never target the public EduPoly site.

Each ZIP contains its own tests, configuration and practice app. Extract checkpoints into separate folders. Keep the package-lock.json created during installation; later use npm ci. The complete-course ZIP also contains a combined suite with every lesson.

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('the practice app loads', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle('EduPoly Playwright Lab');
  await expect(page.getByRole('heading', { name: 'Playwright Lab', exact: true })).toBeVisible();
});

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-setup-and-first-test",
  "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 registers a named scenario and receives the page fixture.
await waits for navigation and assertions to complete.
baseURL resolves / to the local practice server.

Verify your result

npm run check succeeds.
npm test reports one passing Chromium test.
npm run test:headed opens the test browser.

4. Practice independently

Change the expected heading to an incorrect value, observe the failure, then restore it.

Show the explanation

The assertion retries until its timeout and reports the expected and actual values. Restore Playwright Lab and rerun. A passing navigation alone would not prove the right page loaded.

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.