Smoke Tests with Playwright

Smoke tests are wide and shallow. They touch many parts of the app but go only one layer deep. A full test suite might check that a form rejects a malformed email, validates the password length, and shows the right error color. A smoke test just checks that the login page loads and a valid login lands you on the dashboard.

They run fast and run often. A good smoke suite finishes in under a minute, which is the whole point. You want to run it after every meaningful change, so it has to be cheap enough that you never have to think twice about starting it.

One command installs everything. Run the init command in your project folder. It adds Playwright, downloads the browsers it drives, and scaffolds a config file plus an example test. You answer a couple of prompts and you are done.

# run inside your project folder
npm init playwright@latest

# it asks a few questions — accept the defaults:
# TypeScript? yes. tests folder? e2e. GitHub Actions? yes.

The folders it creates. You get a tests/ or e2e/ folder for your test files, a playwright.config.ts for settings, and an example spec. The config is where you set your base URL and which browsers to run, but the defaults are fine for now.

Run the suite. Use the test command to run headless (no visible browser, fast) or add a flag to watch it happen in a real window.

# run all tests, no visible browser
npx playwright test

# watch it drive a real browser
npx playwright test --headed

# open the interactive UI mode — best for learning
npx playwright test --ui

Three parts, every time. A test navigates to a page, performs an action, then asserts something is true. Here is the smallest useful test you can write.

import { test, expect } from '@playwright/test';

test('homepage loads', async ({ page }) => {
  // 1. navigate
  await page.goto('/');

  // 2. assert — no action needed for a load check
  await expect(page).toHaveTitle(/My App/);
});

The page object is your hands. It represents one browser tab. You call methods on it to click, type, and navigate, exactly like a user would. The async and await keywords just mean "wait for this step to finish before the next one." The browser is slower than code, so you wait for it.

Assertions are the whole point. The expect() function is where the test passes or fails. Without an assertion, you have a script that does things but never checks them. A test with no expect can never fail, which makes it worthless.

A locator is a way to point at an element. Playwright gives you several strategies. The ones worth using match how a real person identifies things on screen: by the words they see and the role of the element. The ones to avoid depend on internal structure that changes with every restyle.

// BEST — find by what the user sees and the role
page.getByRole('button', { name: 'Sign in' });
page.getByLabel('Email');
page.getByText('Welcome back');

// GOOD — a test id you add on purpose
page.getByTestId('submit-order');

// AVOID — brittle, breaks on any restyle
page.locator('.btn-primary > div:nth-child(2)');

Prefer role and text. A button labeled "Sign in" is "Sign in" whether it is blue or green, in the header or the footer. When you locate by visible text and role, your tests describe intent, and they survive cosmetic change. As a bonus, this nudges you toward accessible markup, because the same roles screen readers use are the ones your tests rely on.

Add a test id when text is ambiguous. If a page has three "Edit" buttons, give the one you mean a data-testid attribute in your markup and target it with getByTestId. A data-testid is a deliberate contract between your code and your tests.

One file, a few tests, grouped together. Put your smoke tests in a clearly named file like smoke.spec.ts. Group them with test.describe so the suite reads as a unit. Each test covers one flow from start to its visible proof.

import { test, expect } from '@playwright/test';

test.describe('smoke', () => {

  test('homepage loads', async ({ page }) => {
    await page.goto('/');
    await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
  });

  test('user can sign in', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('test@example.com');
    await page.getByLabel('Password').fill('correct-password');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page.getByText('Welcome')).toBeVisible();
  });

  test('main nav reaches the dashboard', async ({ page }) => {
    await page.goto('/');
    await page.getByRole('link', { name: 'Dashboard' }).click();
    await expect(page).toHaveURL(/dashboard/);
  });

});

Notice what these tests don't do. They don't check error messages, validation rules, or styling. They confirm the page loads, login works, and navigation lands you where it should. That restraint is what keeps the suite fast and the failures meaningful.

A failing smoke test means stop. When one of these goes red, something a user would notice is broken. Fix it before you ship.

The most common cause of flakiness is timing. Your test clicks a button, then checks for a result that the app needs a moment to render. Playwright handles this for you. Its assertions and actions auto-wait. When you call expect(...).toBeVisible(), it keeps retrying for a few seconds until the element appears or the timeout hits.

Never use a fixed-time pause. The classic mistake is adding a hard wait like waitForTimeout(3000). It makes tests slow on fast machines and still flaky on slow ones. Let Playwright wait on the actual condition instead.

// BAD — guessing at a duration, flaky and slow
await page.waitForTimeout(3000);
await expect(page.getByText('Done')).toBeVisible();

// GOOD — wait on the real thing, auto-retried
await expect(page.getByText('Done')).toBeVisible();

Keep tests independent. Each test should set up its own state and not depend on another test running first. If your sign-in test has to run before your dashboard test, a single failure cascades. Use beforeEach to put the page in a known state before every test.

When something fails, look at the trace. Playwright can record a full trace of a failed run: every action, a screenshot at each step, and the network activity. Open it and you see exactly where reality diverged from your expectation. This turns "why did it fail" from a guessing game into a replay.

# re-run failures with a trace, then open the report
npx playwright test --trace on
npx playwright show-report

Continuous integration runs your tests for you. If you accepted the GitHub Actions option during install, Playwright already wrote a workflow file at .github/workflows/playwright.yml. On every push and pull request, GitHub spins up a fresh machine, installs your app, runs the suite, and reports pass or fail right on the commit.

name: Playwright Tests
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test

Keep secrets out of your code. Your test login needs a password, but that password must never live in a committed file. Store it as a repository secret in your CI settings and read it from an environment variable in the test. The values stay encrypted and out of your git history.

// read from the environment, never hardcode
await page.getByLabel('Password')
  .fill(process.env.TEST_PASSWORD!);

Make the check required. In your repository's branch protection settings, mark the Playwright job as a required status check. Now a pull request cannot merge while the smoke suite is red. The seatbelt buckles itself, every time, whether or not anyone remembers.

The process:

1. Name the three to five flows that would embarrass you if they broke, and the visible proof of success for each.
2. Install Playwright and get the example test passing locally.
3. Write one test per flow using role, label, and text locators — navigate, act, assert, nothing more.
4. Break each flow in the app and confirm the matching test catches it.
5. Remove every fixed-time wait and run the suite five times to prove it is stable.
6. Wire it into CI on every push, with the test password stored as a secret.
7. Push a deliberate break and confirm the suite blocks the merge, then fix it green.