DEV Community: kadir

Capstone: A 100-Test Suite, End to End (Playwright + TypeScript, Ch.26)

kadir — Mon, 08 Jun 2026 23:19:38 +0000

This is where everything comes together. If you started this series never having
written an automated test, look at what you can now read and build: a layered Playwright

TypeScript framework — fixtures, Page Objects, API + UI + integration tests, CI, reporting — running against a real dockerized app. The capstone makes it whole.

── Run summary ───────────────────────────────
  result:   passed
  tests:    100  (✓ 100  ✘ 0  ⤿ flaky 0  – skipped 0)
  projects: setup 1  api 66  ui 33

Code for this chapter is tagged ch-26 in the repo:
https://github.com/aktibaba/playwright-qa-course.

End-to-end journeys

An end-to-end (E2E) test exercises the whole product the way a real user would,
start to finish — and a regression suite is the set of tests you run to make sure
nothing that used to work has broken. The capstone's headline tests are exactly that,
and each one creates a fresh user so it's completely isolated:

test("a new user signs up, publishes an article, and sees it on their profile", async ({
  signUpPage, articleEditorPage, articlePage, page,
}) => {
  const username = uniqueId("author").replace(/-/g, "");
  await signUpPage.signUp({ username, email: `${username}@test.io`, password: "Password123!" });

  const title = `Capstone article ${Date.now()}`;
  await articleEditorPage.publishArticle({ title, description: "…", body: "…", tags: "capstone" });

  await articlePage.expectTitle(title);
  await page.goto(`/#/profile/${username}`);
  await expect(page.getByRole("heading", { name: title })).toBeVisible();
});

Sign up → write an article → view it → see it on the profile, all through the UI,
reusing every Page Object and fixture we built. Notice how a journey this rich is just a
dozen readable lines — that's the payoff of the architecture.

What the 100 tests cover

API (66 tests): articles CRUD, comments, favorites, follows, profiles, tags, pagination, the personalised feed, auth & sessions, validation, and authorization.
UI (33 tests): locators & assertions, login/signup/logout, the article editor, comments, settings, profile & feed, tag filtering, network mocking, visual regression, accessibility, and the end-to-end journeys.
Cross-cutting: seed-via-API/verify-in-UI, storageState login, sharded CI, a custom reporter, and unique-data isolation throughout.

The bugs the suite found

Run honestly and at scale, the suite did what good tests do — it found seven real bugs
in the application, all fixed in sut/:

createArticle crashed when tagList was omitted.
A null-author race (an un-awaited setAuthor) crashed GET /articles under load.
slug wasn't unique → duplicate slugs → favorites colliding on a primary key.
offset pagination broke the RealWorld contract (offset * limit).
WCAG-AA colour-contrast failures across the UI.
updateUser returned a 500 on every profile update (an || that's always true) and risked overwriting passwords.
An invalid token returned 500 instead of 401.

That's the real return on a framework: not just "do the tests pass," but a suite
trustworthy enough that when it goes red, you believe it — and it catches things the
UI alone never would.

Where to take it next

You don't need any of these, but each is an afternoon, not a rewrite:

More browsers/devices — add WebKit and Firefox projects, and a mobile viewport.
Visual coverage in CI — generate Linux baselines in the Playwright Docker image.
Data & trends — ship json/blob results to a dashboard; track flaky rate over time (Chapter 25).
Contract testing — check the API against the published RealWorld OpenAPI spec.
Performance budgets — fail a test when a key request gets too slow.

They're afternoons because the architecture from Part 2 was built to extend.

Thank you

That's the course — from "why a framework?" to a production-grade, 100-test, API + UI
suite that runs in CI and even improved the app it tests. Clone the
repo, check out any ch-NN tag, and
make it your own.

If this series helped you, star the repo and tell me what you built with it. Happy
testing. 🎭

Reporting: Custom Reporters & Result Visibility (Playwright + TypeScript, Ch.25)

kadir — Mon, 08 Jun 2026 22:54:44 +0000

Chapter 6 made individual failures legible (traces, the HTML report). This chapter is
about results as a whole — the signal a team reads every day: what passed, what's
flaky, what's slow — and getting it in front of people without anyone opening a report.

Code for this chapter is tagged ch-25 in the repo:
https://github.com/aktibaba/playwright-qa-course — see
reporters/summary-reporter.ts and the reporter array in playwright.config.ts.

The built-ins, recapped

A reporter turns the stream of test events into output. We already stack three
(Chapter 20): list (terminal), html (rich, browsable), and junit (XML for CI).
Others ship in the box: dot (very compact for huge suites), json
(machine-readable), github (annotations right on a pull request), and blob
(mergeable across shards). You can run any combination at once.

Write a custom reporter

When the built-ins don't say exactly what you want, you write your own by
implementing Playwright's Reporter interface.

An interface here is a set of methods Playwright will call at certain moments. You
only implement the ones you care about. The key lifecycle hooks:
onBegin (the run starts), onTestEnd (one test finished — called once per test),
and onEnd (the whole run finished).

Here's a reporter that collects every result and prints an end-of-run summary —
totals, a flaky count, and the slowest tests:

// reporters/summary-reporter.ts
import type { Reporter, TestCase, TestResult, FullResult } from "@playwright/test/reporter";

export default class SummaryReporter implements Reporter {
  private entries: { test: TestCase; result: TestResult }[] = [];

  onTestEnd(test: TestCase, result: TestResult) {
    this.entries.push({ test, result });        // remember each finished test
  }

  onEnd(result: FullResult) {                   // at the very end, summarise
    const count = (s: TestResult["status"]) =>
      this.entries.filter((e) => e.result.status === s).length;
    // "flaky" = passed, but only after a retry
    const flaky = this.entries.filter(
      (e) => e.result.status === "passed" && e.result.retry > 0,
    ).length;

    console.log(`\n  ${result.status} — ✓ ${count("passed")}  ✘ ${count("failed")}  ⤿ flaky ${flaky}`);
    // …plus slowest tests and a per-project breakdown
  }
}

// playwright.config.ts
reporter: [
  ["list"],
  ["html", { open: "never" }],
  ["junit", { outputFile: "test-results/junit.xml" }],
  ["./reporters/summary-reporter.ts"],
],

Now every run ends with a glanceable summary:

── Run summary ───────────────────────────────
  result:   passed
  tests:    100  (✓ 100  ✘ 0  ⤿ flaky 0  – skipped 0)
  projects: setup 1  api 66  ui 33
  slowest:
    741ms  home page has no serious accessibility violations
    ...

The flaky number is the one to watch over time — a test that passes only on a retry
is a bug waiting to turn the pipeline red (Chapter 19).

Put results where people look

A report nobody opens isn't reporting. Two cheap, high-value channels:

The CI run page. GitHub Actions exposes a special file via the GITHUB_STEP_SUMMARY environment variable — append Markdown to it and it renders right on the run's summary page. Our reporter writes a pass/fail table there when that variable is present, so results show up without downloading anything.
PR annotations. The built-in github reporter marks failing lines directly in the pull-request diff. Add it to the reporter array on CI.

For history and trends — flaky rate over time, durations, ownership — reach for a
dedicated tool: Allure (allure-playwright) or shipping the json/blob output to
a dashboard. Use those when "how is the suite trending?" becomes a recurring question;
the custom reporter covers the single-run story.

The principle

Reporting is a transformation of raw results into a decision: collect → summarise →
deliver to where your audience already looks. Playwright gives you the events; a few
lines of reporter turn them into the one line your team actually reads.

Next up

Everything's in place — and visible. Chapter 26 — Capstone: one comprehensive
end-to-end regression that exercises the whole product (sign up → author → comment →
favorite → follow) and ties every technique from the course together. Tag: ch-26.

Following along? Star the repo
and tell me what your end-of-run summary would highlight.

Framework Maturation & Docs (Playwright + TypeScript, Ch.24)

kadir — Mon, 08 Jun 2026 22:53:26 +0000

A framework isn't finished when it works — it's finished when someone else can
extend it without reading every file. "Maturation" is that last mile: filling
coverage gaps and writing the docs that make the project approachable.

Code for this chapter is tagged ch-24 in the repo:
https://github.com/aktibaba/playwright-qa-course — see the new
profile-and-feed / article-filters specs and docs/reference/framework.md.

Rounding out coverage

We fill the obvious gaps with flows that reuse everything we've built:

Profile — an author's article shows on their profile page.
Global feed & tag filter — toggling the feed and clicking a tag.
Editing — open the editor for an existing article and save a change.
API list filters — by author, the empty case, and the personalised feed.

A couple of these reinforced a lesson worth burning in: keep assertions deterministic
under parallelism. The danger is asserting on a specific item's position in a list
that other tests are changing at the same time:

// ❌ fragile: the unfiltered feed shows only a few newest articles, and other
//    tests are adding articles right now — yours may not be on the page.
await expect(page.getByRole("heading", { name: article.title })).toBeVisible();

// ✅ robust option A: assert the behaviour, not a specific item
await expect(globalFeed).toHaveClass(/active/);              // the toggle worked
await expect(page.locator(".preview-link").first()).toBeVisible(); // some article rendered

// ✅ robust option B: isolate, so only YOUR data matches
const author = await registerUser(api);            // a brand-new user
const article = await createArticleAs(author.token);
await page.goto(`/#/profile/${author.username}`);  // their profile has exactly one article

The new createArticleAs(token, …) helper creates an article authored by a specific
user — the building block that makes an isolated profile or author-filter test possible.

Docs that make it extendable

Finally, a framework reference — one page that maps the
layers, states the rules (the dependency direction, the determinism rules), and answers
"how do I add a test / Page Object / fixture / data factory?". With the repo's README,
a newcomer can be productive in minutes instead of digging through files.

Good docs capture the decisions the code can't explain on its own: why tests import
only from @fixtures, why no test resets the database, why you never assert on a
list position. That's what keeps a maturing framework from drifting back into chaos.

Next up

Everything is in place — and the results are visible. Chapter 25 — Reporting: a
dedicated look at turning raw results into something a team acts on, including a custom
Playwright reporter. Then Chapter 26 is the grand Capstone — a full end-to-end
regression tying every technique together. Tag: ch-25.

Following along? Star the repo
and tell me what you'd put in your framework's onboarding doc.

Stability & Maintainability at Scale (Playwright + TypeScript, Ch.23)

kadir — Mon, 08 Jun 2026 22:53:11 +0000

As a suite grows, two qualities decide whether it stays an asset or becomes a burden:

Stable — it fails only for real reasons (not random flakiness).
Maintainable — you can add the next test without copy-pasting setup everywhere.

This chapter is about the habits that keep both true, shown by adding comment and
settings flows.

Code for this chapter is tagged ch-23 in the repo:
https://github.com/aktibaba/playwright-qa-course — see src/utils/unique.ts,
src/pages/SettingsPage.ts, and the new comment-ui / settings-ui specs.

Centralize the tricky bits

Remember the flaky slug bug? It came from generating "unique" data that wasn't actually
unique across parallel workers. The lesson isn't "be more careful" — it's put the hard
thing in one place so nobody can get it wrong again:

// src/utils/unique.ts
let counter = 0;
export function uniqueId(prefix = "id"): string {
  // timestamp + counter + randomness → unique even across parallel workers
  counter += 1;
  return `${prefix}-${Date.now()}-${counter}-${Math.floor(Math.random() * 1e9)}`;
}

Now the article factory and the user factory both call uniqueId() — one proven
recipe, no chance to reintroduce the collision. (This is the DRY principle — Don't
Repeat Yourself — applied to the riskiest line.) Maintainability means the correct way
is the only way.

Wait for the right signal, not a guess

The settings screen loads the current user asynchronously, then fills the form.
Editing a field before that load finishes would submit blank values over the real
ones. The stable fix is never a fixed waitForTimeout(2000) (which is either too
short and flaky, or too long and slow) — it's waiting for the actual readiness signal:

// src/pages/SettingsPage.ts
async goto(): Promise<void> {
  await this.page.goto("/#/settings");
  await expect(this.updateButton).toBeVisible();
  await expect(this.username).not.toHaveValue(""); // wait until the form is filled in
}

not.toHaveValue("") waits until the username field is no longer empty — a concrete
sign the form finished loading. Putting that wait inside the Page Object means every
settings test gets the stability for free — the test just calls goto().

New flows, same machinery

Adding comments and settings needed no new infrastructure — they reuse the fixtures
and Page Objects we already have. A comment test reads as plain behaviour:

test.use({ storageState: ".auth/playwright.json" });

test("post a comment and see it appear", async ({ makeArticle, articlePage }) => {
  const article = await makeArticle();           // seed via API (fast)
  await articlePage.goto(article.slug);
  const body = `Nice article ${Date.now()}`;
  await articlePage.postComment(body);           // act in the UI
  await expect(articlePage.comment(body)).toBeVisible(); // verify in the UI
});

The settings test goes a step further on isolation: it registers a fresh user
through the API and logs in as them, so changing a profile never collides with other
tests using the shared seed user. New surface, but the same registerUser, loginPage,
and settingsPage building blocks. That's what "scales" means — the cost of the next
flow is small because the pieces already exist.

…and another real bug

Writing the settings flow, the UI test failed — and so did a direct API check. The app's
update endpoint returned a 500 error on every profile update:

// the original, buggy condition
if (password !== undefined || password !== "") {   // this is ALWAYS true!
  loggedUser.password = await bcryptHash(password); // hashing `undefined` → crash
}

a !== x || a !== y can never be false (a value can't equal two different things at
once), so every update tried to hash an absent password and crashed — and on a real
save it would have overwritten the user's password. One character — || → && —
fixed it. The suite didn't just check the settings screen; it proved the whole feature
was broken.

Next up

Chapter 24 — Framework maturation & docs: we tidy the project, document how to run
and extend it, and round out coverage so a newcomer can be productive in minutes. Tag:
ch-24.

Following along? Star the repo
and tell me the one helper that removed the most flakiness from your suite.

Advanced: Network Mocking, Visual & Accessibility (Playwright + TypeScript, Ch.22)

kadir — Mon, 08 Jun 2026 22:11:35 +0000

Welcome to Part 6. The framework is solid; now we add three powerful kinds of test
that go beyond "click and check the text."

Code for this chapter is tagged ch-22 in the repo:
https://github.com/aktibaba/playwright-qa-course — see src/tests/ui/:
network-mock.spec.ts, visual.spec.ts, a11y.spec.ts.

Network mocking — test the UI in isolation

Mocking the network means intercepting the app's requests and replying with a
fake response you write. page.route(pattern, handler) catches matching requests;
route.fulfill(...) answers them. That makes states which are awkward to set up for
real — an empty list, a server error, weird data — trivial and 100% predictable:

test("shows the empty state when the feed is empty", async ({ page }) => {
  // Intercept the articles request and pretend the list is empty.
  await page.route("**/api/articles?*", (route) =>
    route.fulfill({ json: { articles: [], articlesCount: 0 } }),
  );
  await page.goto("/");
  await expect(page.getByText("Articles not available.")).toBeVisible();
});

test("survives an API error without crashing", async ({ page }) => {
  // Pretend the server returned a 500 error.
  await page.route("**/api/articles?*", (route) =>
    route.fulfill({ status: 500, json: { errors: { body: ["boom"] } } }),
  );
  await page.goto("/");
  await expect(page.getByRole("link", { name: "Sign up" })).toBeVisible(); // app still works
});

(The **/api/articles?* is a glob pattern — ** matches anything, so this catches the
articles request whatever its full URL.) These tests need no database and no login — the
test owns the data. Use mocking for UI behaviour on hard-to-produce responses; keep
the real-backend integration tests from Part 4 for the contract itself. You want both.

Visual regression — catch the unintended

A visual regression test takes a screenshot and compares it pixel-by-pixel against a
saved reference image (the baseline). It catches things no text assertion would — a
broken layout, a wrong colour, a button clipped off the edge:

test("login page matches its baseline", async ({ page }) => {
  await page.goto("/#/login");
  await expect(page.getByRole("button", { name: "Login" })).toBeVisible();
  await page.evaluate(() => document.fonts.ready); // wait for web fonts to load
  await expect(page).toHaveScreenshot("login.png", { maxDiffPixelRatio: 0.02 });
});

The first run creates the baseline; later runs compare against it. Two things keep
visual tests trustworthy instead of flaky:

Let the page settle first. Waiting on document.fonts.ready avoids the most common cause of false differences — a screenshot taken while a web font is still swapping in. maxDiffPixelRatio: 0.02 tolerates tiny (2%) rendering differences.
Baselines are platform-specific. Text renders slightly differently on macOS vs Linux, so a macOS baseline won't match a Linux CI machine. We test.skip visual tests on CI and generate Linux baselines separately. Never diff a baseline made on one OS against another.

Accessibility — and real bugs we fixed

Accessibility (a11y) is whether people using assistive tech — screen readers,
keyboard-only navigation — can use the app. The WCAG standard defines rules (e.g.
text must have enough colour contrast). The @axe-core/playwright library scans a page
and reports violations; we fail the test on serious ones:

const results = await new AxeBuilder({ page })
  .withTags(["wcag2a", "wcag2aa"])        // which rule sets to check
  .exclude(".pagination")                 // skip a third-party widget (see below)
  .analyze();

const serious = results.violations.filter(
  (v) => v.impact === "serious" || v.impact === "critical",
);
expect(serious).toEqual([]);              // expect NO serious violations

The first run failed — and the violations were real:

Colour contrast. The navbar links (contrast 2.1:1), the banner subtitle, muted dates, and the green feed toggle (3.0:1) all fell short of WCAG AA's required 4.5:1. We fixed the app (sut/): darkened the brand green and the muted greys to pass.
Orphaned list items came from the third-party react-paginate widget rendering its <ul> with role="navigation". We can't fix that from our app code, so we .exclude(".pagination") with a comment and would report it upstream.

That's the realistic a11y workflow: scan, fix what's yours, triage what isn't. And
fixing contrast is a genuine improvement for real users, not just a green test.

Next up

We've widened what we can check. Chapter 23 — Stability & maintainability at
scale: the small utilities and habits that keep a large suite trustworthy as it grows.
Tag: ch-23.

Following along? Star the repo
and tell me which of the three — mocking, visual, or a11y — your suite is missing.

CI/CD with GitHub Actions & Sharding (Playwright + TypeScript, Ch.21)

kadir — Mon, 08 Jun 2026 17:55:43 +0000

A suite that only runs on your laptop protects only your laptop. We want it to run
automatically, on every change, for everyone — that's the job of CI.

CI/CD = Continuous Integration / Continuous Delivery. The CI part: a service runs
your tests every time code is pushed, so problems are caught immediately.
GitHub Actions is GitHub's built-in CI. You describe what to do in a workflow
— a YAML file in .github/workflows/. A workflow has jobs, each running on a
fresh virtual machine called a runner, and each job is a list of steps.
(YAML is just an indentation-based config format.)

Code for this chapter is tagged ch-21 in the repo:
https://github.com/aktibaba/playwright-qa-course — see
.github/workflows/ci.yml and the new comments / favorites / follow specs.

Stand up the app, then test it

The exact command we use locally brings Inkwell up on the CI runner — healthchecks and
all:

- name: Start Inkwell (system under test)
  run: docker compose -f sut/docker-compose.yml up -d --build --wait
- run: npm ci                                  # install deps from the lockfile
- run: npx playwright install --with-deps chromium   # download the browser

--wait matters: the step blocks until every service is healthy, so the tests never
start before the app is ready.

Shard across machines

Sharding splits the test list into N groups that run on N machines at the same
time, so the total wall-clock time drops roughly N×. We use a matrix (a way to run
the same job several times with different values) and the blob reporter (made to be
merged later):

strategy:
  fail-fast: false
  matrix:
    shard: [1, 2]                              # run this job twice: shard 1 and shard 2
steps:
  # ...
  - name: Run tests (sharded)
    run: npx playwright test --shard=${{ matrix.shard }}/2 --reporter=blob
  - uses: actions/upload-artifact@v4           # save this shard's results
    if: ${{ !cancelled() }}
    with:
      name: blob-report-${{ matrix.shard }}
      path: blob-report/

Each shard is its own job on its own runner with its own dockerized app —
complete isolation, no two shards sharing a database.

One nuance: project dependencies run in every shard that needs them. Our ui
project depends on setup (the saved auth session), so setup runs once per shard —
a good reason to keep dependency projects small.

Merge the shards into one report

A second job downloads every shard's blob report and merges them into a single HTML
report you can browse:

report:
  if: ${{ !cancelled() }}
  needs: [test]                                # wait for all the shard jobs
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with: { node-version: 20, cache: npm }
    - run: npm ci
    - uses: actions/download-artifact@v4
      with: { path: all-blob-reports, pattern: blob-report-*, merge-multiple: true }
    - run: npx playwright merge-reports --reporter=html ./all-blob-reports
    - uses: actions/upload-artifact@v4
      with: { name: playwright-html-report, path: playwright-report/ }

Download that artifact from the run and you get one unified report — with traces on any
failure — exactly as if it had all run on one machine.

More coverage — and real bugs in the app

This chapter also adds comments, favorites, and follows test suites, each
using fresh per-test data so counts are deterministic.

Cranking up the parallelism did what good tests do: it found real bugs in the
application. Under heavy concurrent load, requests started failing — and a trace plus
the server logs pinned down four genuine defects in Inkwell:

A null-author race. createArticle set the author with an un-awaited setAuthor(), leaving a brief moment where the new article had no author. A concurrent GET /articles hitting that row crashed. Fix: set the author atomically when creating the row.
Duplicate slugs. slug wasn't unique and the code used a racy "check then create", so two concurrent same-title creates made two articles with the same slug — which then broke favoriting. Fix: a unique constraint on slug and an atomic create.
A crash on a missing tagList, and 4. broken offset pagination (it multiplied offset * limit).

Rather than mask these with retries, we fixed the app itself (it's in sut/). And
that's the real lesson: running your suite at scale is a load test, and load tests find
concurrency bugs. With the app corrected, the suite is fully deterministic — UI and API
specs run concurrently with no special ordering needed.

Next up — Part 6: Advanced & Capstone

The framework is real and runs in CI. Chapter 22 — Advanced techniques: network
mocking to test the UI in isolation, visual snapshots, and accessibility scans — new
kinds of checks on top of everything we've built. Tag: ch-22.

Following along? Star the repo
and tell me how many shards your CI runs.

Reporters & Observability (Playwright + TypeScript, Ch.20)

kadir — Mon, 08 Jun 2026 17:55:30 +0000

A suite is only as useful as what it tells you when it fails. A red ✘ with no context
means a re-run; a red ✘ with a screenshot, a recording, and the environment it ran on
means a fix. This chapter makes failures self-explanatory.

A reporter is the part of Playwright that turns raw results into output — terminal
text, an HTML page, an XML file, whatever you need. You can run several at once.

Code for this chapter is tagged ch-20 in the repo:
https://github.com/aktibaba/playwright-qa-course — see the reporter config in
playwright.config.ts.

Stack reporters for different audiences

Reporters aren't either/or — list several, and each serves a different consumer:

// playwright.config.ts
reporter: [
  ["list"],                                             // for you, live in the terminal
  ["html", { open: "never" }],                          // a rich, browsable report
  ["junit", { outputFile: "test-results/junit.xml" }],  // an XML file CI understands
],

list — readable, streaming output while you work.
html — the investigative tool: every test, its steps, attached screenshots/traces, and the run's metadata. Open it with npm run test:report.
junit — XML that CI systems (GitHub Actions, GitLab, Jenkins) parse to annotate pull requests and track history. We wire this into CI next chapter.
blob — a special format made for merging results from parallel machines (shards); we reach for it in Chapter 21.

Failures that explain themselves

We set two options back in Chapter 6, and they pay off in every report:

use: { trace: "on-first-retry", screenshot: "only-on-failure" }

On a failure, the HTML report carries the screenshot at the moment things broke and
a full trace (DOM snapshots, network, console, a timeline you can scrub) from the
retry. You reconstruct exactly what happened without reproducing it locally — the
difference between minutes and hours on a CI-only flake.

Stamp the run with its environment

Because the config sets metadata (Chapter 18), every report records what it ran
against:

metadata: { environment: env.name, webURL: env.webURL, apiURL: env.apiURL }

"It failed" is noise; "it failed on staging, against that URL" is a lead.

Attach your own context

When a test knows something useful — like the API response that drove an assertion —
you can attach it, and it appears inline in the report:

test("...", async ({ api }, testInfo) => {
  const res = await api.get("articles");
  await testInfo.attach("articles-response", {
    body: JSON.stringify(await res.json(), null, 2),
    contentType: "application/json",
  });
});

testInfo is an extra argument Playwright passes to every test with details about the
current run; testInfo.attach(...) saves a file alongside the result. Now the data
that caused a failure travels with it.

More coverage to observe

A report is richer when there's more to observe, so this chapter also broadens the API
coverage — profiles, tags, and pagination — using a unique tag per test so the
filtered results are deterministic even under parallelism:

test("limit caps the page and the filtered count is exact", async ({ makeArticle, api }) => {
  const tag = `pg-${Date.now()}`;                  // unique → only THIS test's articles
  await makeArticle({ tagList: [tag] });
  await makeArticle({ tagList: [tag] });
  await makeArticle({ tagList: [tag] });

  const body = await (await api.get("articles", { params: { tag, limit: 2 } })).json();
  expect(body.articlesCount).toBe(3);     // exact filtered total
  expect(body.articles.length).toBe(2);   // capped by limit
});

A finding while writing these: Inkwell's offset pagination was broken —
?tag=X&limit=2&offset=2 over 3 matches returned 0 items instead of 1, because
the API multiplied offset * limit (treating offset as a page number), breaking the
RealWorld contract. Exactly the sort of bug good coverage surfaces — we fix it in the
app in Chapter 21 and the offset test goes green.

Next up

We have results CI can read. Chapter 21 — CI/CD with GitHub Actions: stand up the
dockerized app in a workflow, run the suite sharded across machines, merge the
reports, and publish the HTML report as a downloadable artifact. Tag: ch-21.

Following along? Star the repo
and tell me which reporter you live in.

Parallelism & Flake Control (Playwright + TypeScript, Ch.19)

kadir — Mon, 08 Jun 2026 17:55:12 +0000

A fast suite runs tests in parallel (many at once). But parallelism is also where
flaky tests are born.

A flaky test is one that sometimes passes and sometimes fails without the code
changing. It's the most corrosive thing in a test suite — once people stop trusting
a red result, the suite stops protecting anything.

The good news: we've already met (and fixed) the main causes earlier in this course.
This chapter names the model and turns those fixes into principles.

Code for this chapter is tagged ch-19 in the repo:
https://github.com/aktibaba/playwright-qa-course — see the test:flake script in
package.json and the parallelism config in playwright.config.ts.

How Playwright parallelizes

Workers are separate processes. Playwright starts several (CPU-based locally; we pin workers: 4 on CI) and spreads tests across them, so many run at the same time.
Isolation is automatic — for the browser. Each test gets its own browser context and page (its own cookies, storage, cache), so tests can't see each other's browser state.
fullyParallel: true spreads tests within a file across workers too, for maximum concurrency.

Here's the catch: Playwright isolates the browser for you, but it can't isolate
shared external state — one database, one backend. That's where flake lives.

Where flake actually comes from

Every flaky test we hit in this course was one of four things:

Shared mutable state. Parallel API tests each reset the database, wiping it out from under a test that was mid-read (Chapter 11). Fix: seed once in globalSetup; no test resets. Don't share mutable state — or access it in order.
Imprecise locators / assertions. getByRole("heading", { name: "inkwell" }) also matched the "Welcome to Inkwell" article heading, so it passed or failed depending on how fast the feed loaded (Chapter 3). Fix: { exact: true }. Ambiguity plus timing equals flake.
Races with the app. Navigating right after login raced the app's asynchronous redirect (Chapter 5). Fix: wait for a real signal (the login form disappearing), never assume an async action has finished.
Order / collision. Two tests creating an article with the same title clashed. Fix: unique data per test (Date.now()) and clean up what you create.

Notice none of these were "Playwright being unreliable." They were shared state,
timing, and ambiguity — the universal causes of flakiness anywhere.

The knobs (and when to reach for them)

fullyParallel + workers — turn concurrency up. Leave these on by default.
test.describe.configure({ mode: "serial" }) — force a group of tests to run one at a time, in order. A scalpel for tests that must share state — not a default.
Project dependencies — order whole phases (our ui waits for api + setup) so cross-project state can't race.
Per-test isolation — the real cure: unique data + cleanup (the makeArticle factory), so tests never contend in the first place.
retries — the last resort.

Retries hide flake; they don't fix it. They're a safety net for genuinely
non-deterministic infrastructure (a network blip on a remote run), not a substitute
for fixing a data race in your own tests. We keep retries at 0 locally precisely
so flake stays visible and gets fixed.

Hunt flake before CI does

A test that fails 1 run in 50 will eventually turn your pipeline red at the worst
moment. Surface it on purpose by running each test many times:

npm run test:flake        # playwright test --repeat-each=5

--repeat-each=5 runs every test five times. Combine it with --trace on and the
trace viewer (Chapter 6) to see exactly what diverged on the run that failed. If a test
survives --repeat-each=20 under load, it's stable; if it doesn't, you've found a real
bug to fix — not a retry to paper over it.

Next up

We can run fast and trustworthy. Chapter 20 — Reporters & observability: make
results legible — the HTML report, JUnit for CI, and attaching traces so a failure
tells you what happened without a re-run. Tag: ch-20.

Following along? Star the repo
and tell me the last flaky test you chased down — and what caused it.

Multi-Environment Configuration (Playwright + TypeScript, Ch.18)

kadir — Mon, 08 Jun 2026 17:55:00 +0000

Welcome to Part 5 — Scaling, Config & CI. In Chapter 17 we built a typed env
module. Now we wire it into playwright.config.ts so the whole run adapts to where
it's pointed — the same suite against local, CI, or staging, each with the right URLs
and the right resilience.

CI ("Continuous Integration") is a service — like GitHub Actions — that runs your
tests automatically every time someone pushes code. It's a different, often slower
machine than your laptop, so it sometimes needs different settings.

Code for this chapter is tagged ch-18 in the repo:
https://github.com/aktibaba/playwright-qa-course — see playwright.config.ts.

The config is a function of `env` and CI

Two inputs decide everything: which environment (TEST_ENV), and whether we're
running on CI. We derive the rest from them:

// playwright.config.ts
import { env } from "./src/utils/env";

const isCI = !!process.env.CI;        // true when running on CI

// Remote environments are flakier (real network), so allow a retry; local stays
// at 0 so a flaky test is visible immediately.
const retries = isCI ? 2 : env.name === "staging" ? 1 : 0;

export default defineConfig({
  forbidOnly: isCI,
  retries,
  workers: isCI ? 4 : undefined,
  timeout: env.name === "local" ? 30_000 : 60_000,
  expect: { timeout: env.name === "local" ? 5_000 : 10_000 },
  metadata: { environment: env.name, webURL: env.webURL, apiURL: env.apiURL },
  // ...
});

A couple of syntax notes for newcomers: !!process.env.CI turns the value into a plain
true/false. a ? b : c is a ternary — "if a, use b, otherwise c."

What each option does:

forbidOnly — fails the build if someone left a test.only in the code (which would silently skip every other test). Enforced only on CI, so it never blocks you while you focus on one test locally.
retries — if a test fails, run it again up to N times before calling it failed. We allow retries on remote/CI runs (real network blips happen) but keep 0 locally, so a flaky test is a signal you investigate, not noise you ignore.
workers — how many tests run in parallel. Pinned to 4 on CI (predictable shared machines), left to Playwright's CPU-based default locally.
timeout / expect.timeout — how long a test (and an assertion) may take before giving up. More headroom for slower remote environments.
metadata — extra info stamped into the report, so you can always see which environment a run was pointed at.

The per-project baseURL already came from env in earlier chapters:

projects: [
  { name: "api",   use: { baseURL: env.apiURL } },
  { name: "setup", use: { baseURL: env.webURL } },
  { name: "ui",    use: { baseURL: env.webURL, ...devices["Desktop Chrome"] } },
],

One switch flips the whole run

npm test                     # local: localhost, 0 retries, fast timeouts
TEST_ENV=staging npm test    # staging URLs, 1 retry, longer timeouts
CI=1 npm test                # CI mode: forbidOnly on, 2 retries, 4 workers

Nothing in a test, Page Object, or fixture changes — they read env, and env reads
the environment variables. All the configuration lives in just two files (env.ts and
the config). That's the whole point.

Runtime-selected vs. a project per environment

You'll sometimes see suites that define one Playwright project per environment and
run them together. That's right when a single command must hit several environments
at once (a smoke check across regions, say). For the common case — "run this suite
against that environment" — a runtime-selected config like ours is simpler: no
duplicated projects, and the environment is one obvious input. Reach for
project-per-env only when you truly need to target several at the same time.

Next up

The config now scales across environments. Chapter 19 — Parallelism & flake
control: how Playwright runs tests in parallel, where flakiness actually comes
from, and the knobs that keep a big suite both fast and trustworthy. Tag: ch-19.

Following along? Star the repo
and tell me how many environments your suite targets.

Test Data Factories & Environment Config (Playwright + TypeScript, Ch.17)

kadir — Mon, 08 Jun 2026 17:15:42 +0000

Two kinds of constant have been creeping into our tests: inline data objects (the
{ title, description, body, tagList } we keep typing) and URLs. Both deserve a
single home. This chapter gives them one — a data factory and a typed
environment module — and closes Part 4.

Code for this chapter is tagged ch-17 in the repo:
https://github.com/aktibaba/playwright-qa-course — see
src/fixtures-data/article.ts and src/utils/env.ts.

A data factory

A factory is a function that builds a valid object with sensible defaults, and lets
the caller override just the parts it cares about. It centralises "what a valid article
looks like" so no test has to remember every field:

// src/fixtures-data/article.ts
export interface ArticleInput {
  title: string;
  description: string;
  body: string;
  tagList: string[];
}

let seq = 0;

export function articleData(overrides: Partial<ArticleInput> = {}): ArticleInput {
  seq += 1;
  return {
    title: `Test Article ${Date.now()}-${seq}`,
    description: "Generated by the article factory",
    body: "Article body for automated tests.",
    tagList: [],                 // required by the API (Chapter 13)
    ...overrides,                // anything the caller passed wins
  };
}

Two TypeScript bits worth naming:

Partial<ArticleInput> means "an object that may have some of the article fields" — so a caller can override only title, or nothing at all.
...overrides is the spread operator: it copies the caller's fields on top of the defaults, so their values win. articleData({ tagList: ["x"] }) keeps every default but replaces tagList.

Our provisioning helper now just defers to the factory:

// src/utils/scenarios.ts
export async function createArticle(api, overrides: Partial<ArticleInput> = {}) {
  const res = await api.post("articles", { data: { article: articleData(overrides) } });
  // ...
}

So a test stays focused on intent — makeArticle({ tagList: ["integration"] }) — and
the unique title, the valid defaults, and the "tagList is required" rule all live in
one place. Change the article shape once and every test follows.

Why put it in src/fixtures-data/ (the @data alias) and not in a fixture? Because
this is pure data — no page, no setup/teardown. Factories are plain functions;
fixtures that use them own the lifecycle. Keeping them separate is the layering
discipline from Chapter 10.

A typed environment module

URLs are the other scattered constant. env is our single source of truth, and now
it's multi-environment. First, a definition:

Environment variables (process.env.*) are values set outside your code — by
your shell or your CI system — like TEST_ENV=staging. They let you change
behaviour without editing files.

// src/utils/env.ts
export type EnvName = "local" | "ci" | "staging";

const ENVIRONMENTS: Record<EnvName, { webURL: string; apiURL: string }> = {
  local:   { webURL: "http://localhost:3000", apiURL: "http://localhost:3001/api" },
  ci:      { webURL: "http://localhost:3000", apiURL: "http://localhost:3001/api" },
  staging: { webURL: "https://inkwell-staging.example.com", apiURL: "https://inkwell-staging.example.com/api" },
};

const name = (process.env.TEST_ENV as EnvName) || "local";  // pick a target, default local
const base = ENVIRONMENTS[name] ?? ENVIRONMENTS.local;

export const env = {
  name,
  webURL: process.env.WEB_URL ?? base.webURL,   // allow per-URL overrides
  apiURL: process.env.API_URL ?? base.apiURL,
} as const;

Now the same suite runs anywhere, by changing only an environment variable:

npm test                                # local (the default)
TEST_ENV=staging npm test               # against the staging deployment
API_URL=http://host:4000/api npm test   # a one-off URL override

The discipline that keeps this clean: only env.ts reads process.env. Tests,
Page Objects, and fixtures import env — never environment variables directly. All
configuration lives in one auditable place (the Chapter 10 layer rule, applied to
config).

Part 4, done

The integration milestone is complete: log in once with storageState, seed via the
API and verify in the UI, and now clean factories and environment config. The suite is
fast, isolated, and portable across environments.

Next up — Part 5: Scaling, Config & CI

Chapter 18 — Multi-environment configuration takes the env module we just built
and wires it into Playwright's project system, so a single config targets several
environments with the right base URLs, retries, and metadata. Tag: ch-18.

Following along? Star the repo
and tell me what your test-data factories generate most.

Seed via API, Verify in UI (Playwright + TypeScript, Ch.16)

kadir — Mon, 08 Jun 2026 17:04:27 +0000

This is the payoff of everything so far. Think about a UI test that checks "does an
article render on its page?" To get there through the UI you'd log in, open the
editor, fill four fields, and publish — every single time. That's slow, and worse:
if the editor form is flaky or gets redesigned, your viewing test breaks for a reason
that has nothing to do with viewing.

The integration pattern fixes it: set up through the API, verify through the UI.
The API is fast and stable; use it to get to the starting state, then let the browser
check only the one thing the test is actually about.

We already have the pieces — makeArticle from Chapter 14 creates an article in
milliseconds. Now we just point the browser at it.

Code for this chapter is tagged ch-16 in the repo:
https://github.com/aktibaba/playwright-qa-course — see
src/tests/ui/seed-via-api.spec.ts.

Create through the API, check in the browser

import { test, expect } from "@fixtures";

test("an article created through the API renders on its page", async ({
  makeArticle,
  page,
}) => {
  // 1. Set up the data through the API — one fast request.
  const article = await makeArticle({
    title: `Seeded via API ${Date.now()}`,
    body: "This article was created through the API and rendered by the UI.",
    tagList: ["integration"],
  });

  // 2. Point the browser straight at it.
  await page.goto(`/#/article/${article.slug}`);

  // 3. Verify what the UI actually renders.
  await expect(page.getByRole("heading", { name: article.title })).toBeVisible();
  await expect(page.getByText(article.body)).toBeVisible();
  await expect(page.getByRole("link", { name: "playwright" }).first()).toBeVisible();
});

makeArticle does an authenticated POST behind the scenes and returns the created
article (including its server-generated slug). We navigate straight to its page —
no form journey — and check what renders. And it's cleaned up automatically by the
fixture's teardown (Chapter 14).

Notice the division of labour: viewing an article is public, so this test needs
no logged-in browser. Only the creation is authenticated, and that's hidden inside
makeArticle. When a test does need to view as a logged-in user (to see authoring
buttons, say), combine this with the storageState from Chapter 15: seed via API,
load the saved session, verify in the UI.

Why this is faster and more reliable

Faster. An API POST is milliseconds; driving the editor form is seconds. Across a whole suite that's the difference between a 2-minute and a 10-minute run.
More reliable. The setup no longer goes through the UI, so a flaky editor can't break a test about viewing. Each test fails for exactly one reason — the thing it asserts.
Focused. The UI test checks one UI behaviour; the API's own correctness is covered by the Part 3 tests. No duplication.

…and the reverse

The pattern runs both ways. When the action genuinely belongs in the UI (a user
clicks "Publish") but the result is data, act in the UI and verify through the
API — checking the real source of truth is stronger than reading the page's HTML:

// act in the UI…
await articleEditorPage.publishArticle(draft);
// …then verify through the API
const res = await api.get(`articles/${slug}`);
expect((await res.json()).article.title).toBe(draft.title);

Rule of thumb: set up and verify through whichever layer is cheaper and more
authoritative; reserve the UI for the behaviour you specifically need to prove.

Next up

We've been writing test data inline. Chapter 17 — Test data & environment config
closes Part 4: data factories for inputs, and a clean multi-environment config so
the same suite runs against local, staging, or CI. Tag: ch-17.

Following along? Star the repo
and tell me how much of your UI setup you've moved to the API.

Auth Once with storageState (Playwright + TypeScript, Ch.15)

kadir — Mon, 08 Jun 2026 16:58:09 +0000

Welcome to Part 4 — Integration: making the API and UI layers work together.
This is what separates a toy suite from a real one, and we start with the highest-value
example — logging in.

The problem

Logging in through the form on every UI test is slow (load the page, type the
email, type the password, click, wait for the redirect) and repetitive. Do it on a
hundred tests and you've wasted real minutes per run.

The idea: save the session

When you log in, the browser stores proof that you're logged in — in cookies and
in localStorage (a small key/value store the page keeps in the browser). Together
these are your session.

Playwright can save that session to a file and load it back into other tests.
A test that loads it opens the app already logged in — no form needed. That saved
file is called a storage state.

Code for this chapter is tagged ch-15 in the repo:
https://github.com/aktibaba/playwright-qa-course — see src/setup/auth.setup.ts,
playwright.config.ts, and src/tests/ui/authenticated.spec.ts.

A setup project that logs in once

Playwright lets you run a setup project — a special test file that runs before
your other tests and prepares things they need. Ours logs in and saves the session.

Here's the integration twist: instead of driving the slow login form, we log in
through the API (one fast request), then write the session into the browser's
localStorage and save it:

// src/setup/auth.setup.ts
import { test as setup, expect } from "@playwright/test";
import { env } from "@utils/env";
import { SEED_USERS } from "../fixtures/data.fixture";

const authFile = ".auth/playwright.json";

setup("authenticate", async ({ page, request }) => {
  const { email, password } = SEED_USERS.playwright;

  // 1. Log in via the API (no clicking) and get the token.
  const res = await request.post(`${env.apiURL}/users/login`, {
    data: { user: { email, password } },
  });
  expect(res.ok()).toBeTruthy();
  const { user } = await res.json();

  // 2. Write the exact session shape Inkwell reads on load, into localStorage.
  const session = { headers: { Authorization: `Token ${user.token}` }, isAuth: true, loggedUser: user };
  await page.goto("/");
  await page.evaluate((v) => localStorage.setItem("loggedUser", JSON.stringify(v)), session);

  // 3. Save cookies + localStorage to a file.
  await page.context().storageState({ path: authFile });
});

A couple of new things:

page.evaluate(fn, arg) runs fn inside the browser page (where localStorage lives) and passes arg into it. That's how we set the value the app expects.
We discovered the exact localStorage shape (loggedUser) by reading Inkwell's source — Inkwell restores the session from localStorage.getItem("loggedUser") on load. Knowing one small detail of the app under test is the essence of integration testing.

Wire it up with project dependencies

We tell Playwright "run setup before ui" using dependencies:

// playwright.config.ts
projects: [
  { name: "api", testDir: "./src/tests/api", use: { baseURL: env.apiURL } },
  {
    name: "setup",
    testDir: "./src/setup",
    testMatch: /auth\.setup\.ts/,
    use: { baseURL: env.webURL },
  },
  {
    name: "ui",
    testDir: "./src/tests/ui",
    dependencies: ["api", "setup"], // setup runs first → the auth file exists
    use: { baseURL: env.webURL, ...devices["Desktop Chrome"] },
  },
],

Opt a test into the session

You choose per file whether to start logged in. Our anonymous tests (home,
locators, login) stay logged out; only this file loads the saved session, with
test.use:

// src/tests/ui/authenticated.spec.ts
import { test, expect } from "@playwright/test";

test.use({ storageState: ".auth/playwright.json" });   // load the saved session

test("starts already logged in", async ({ page }) => {
  await page.goto("/");
  await expect(page.getByRole("link", { name: "New Article" })).toBeVisible();
  await expect(page.getByRole("navigation").getByText("playwright")).toBeVisible();
  await expect(page.getByRole("link", { name: "Sign up" })).toBeHidden();
});

No LoginPage, no form, no redirect — the test opens the app and the user is already
there. Multiply that saving across a hundred tests.

The .auth/ folder is git-ignored — it holds a live token and is regenerated by the
setup project on every run, so it never goes into version control.

When to use which login

storageState (this chapter): the default for most authenticated tests — fast, shared, set up once.
Logging in through the form (LoginPage): keep it for the few tests whose subject is the login flow — you still want to prove the form itself works (the Chapter 4 test stays exactly as it was).

Next up

We used the API to set up auth. Next we generalise that to all test data.
Chapter 16 — Seed via API, verify in UI: create an article through the API in
milliseconds, then check it renders in the browser — the pattern that makes UI suites
fast and reliable. Tag: ch-16.

Following along? Star the repo
and tell me how many seconds storageState shaved off your suite.

DEV Community: kadir

Capstone: A 100-Test Suite, End to End (Playwright + TypeScript, Ch.26)

End-to-end journeys

What the 100 tests cover

The bugs the suite found

Where to take it next

Thank you

Reporting: Custom Reporters & Result Visibility (Playwright + TypeScript, Ch.25)

The built-ins, recapped

Write a custom reporter

Put results where people look

The principle

Next up

Framework Maturation & Docs (Playwright + TypeScript, Ch.24)

Rounding out coverage

Docs that make it extendable

Next up

Stability & Maintainability at Scale (Playwright + TypeScript, Ch.23)

Centralize the tricky bits

Wait for the right signal, not a guess

New flows, same machinery

…and another real bug

Next up

Advanced: Network Mocking, Visual & Accessibility (Playwright + TypeScript, Ch.22)

Network mocking — test the UI in isolation

Visual regression — catch the unintended

Accessibility — and real bugs we fixed

Next up

CI/CD with GitHub Actions & Sharding (Playwright + TypeScript, Ch.21)

Stand up the app, then test it

Shard across machines

Merge the shards into one report

More coverage — and real bugs in the app

Next up — Part 6: Advanced & Capstone

Reporters & Observability (Playwright + TypeScript, Ch.20)

Stack reporters for different audiences

Failures that explain themselves

Stamp the run with its environment

Attach your own context

More coverage to observe

Next up

Parallelism & Flake Control (Playwright + TypeScript, Ch.19)

How Playwright parallelizes

Where flake actually comes from

The knobs (and when to reach for them)

Hunt flake before CI does

Next up

Multi-Environment Configuration (Playwright + TypeScript, Ch.18)

The config is a function of env and CI

One switch flips the whole run

Runtime-selected vs. a project per environment

Next up

Test Data Factories & Environment Config (Playwright + TypeScript, Ch.17)

A data factory

A typed environment module

Part 4, done

Next up — Part 5: Scaling, Config & CI

Seed via API, Verify in UI (Playwright + TypeScript, Ch.16)

Create through the API, check in the browser

Why this is faster and more reliable

…and the reverse

Next up

Auth Once with storageState (Playwright + TypeScript, Ch.15)

The problem

The idea: save the session

A setup project that logs in once

Wire it up with project dependencies

Opt a test into the session

When to use which login

Next up

The config is a function of `env` and CI