@definitely-fine/playwright

@definitely-fine/playwright helps Playwright tests activate definitely-fine scenarios in browser-driven flows.

It extends the core scenario builder with scenario header metadata plus helpers for creating browser contexts and pages that already send the active scenario id.

Installation

pnpm add -D @playwright/test @definitely-fine/playwright
pnpm add definitely-fine

What This Package Adds

createScenario() from this package builds on the core definitely-fine scenario builder and adds:

• headerName
• headers
• createContext(browser, options?)
• createPage(browser, options?)

flowchart LR
  subgraph P[Playwright worker process]
    P1[createScenario]
    P2[define rules and save scenario]
    P3[createContext or createPage]
  end

  subgraph B[Browser process]
    B1[request with scenario header]
  end

  subgraph A[Application server process]
    A1[@definitely-fine/nextjs or @definitely-fine/hono]
    A2[runWithRuntimeScenarioContext]
    A3[definitely-fine runtime]
  end

  subgraph S[Shared scenario storage]
    S1[(persisted scenario JSON)]
  end

  P1 --> P2 --> S1
  P2 --> P3
  P3 --> B1
  B1 --> A1 --> A2 --> A3
  A3 -- load active scenario --> S1

Example

import { test, expect } from "@playwright/test";
import { DEFINITELY_FINE_SCENARIO_HEADER } from "@definitely-fine/nextjs";
import { createScenario } from "@definitely-fine/playwright";

type DemoContract = {
  services: {
    counter: {
      incrementApi(): number;
      incrementAction(): number;
    };
  };
  functions: Record<string, never>;
  errors: Record<string, never>;
};

test("uses a scenario-backed browser context", async ({ browser }) => {
  const scenario = createScenario<DemoContract>({
    headerName: DEFINITELY_FINE_SCENARIO_HEADER,
  });

  scenario.service("counter").method("incrementApi").onCall(1).returns(10);
  await scenario.save();

  const context = await scenario.createContext(browser);

  try {
    const page = await context.newPage();

    await page.goto("/");
    await page
      .getByRole("button", { name: "Increment with API route" })
      .click();
    await expect(page.locator("#api-count")).toHaveText("10");
  } finally {
    await context.close();
    await scenario.dispose();
  }
});

Header Behavior

The helper merges the scenario header into extraHTTPHeaders when it creates a new browser context.

That means requests from pages created through that context automatically activate the saved scenario in your server-side runtime, as long as your app reads the same header.

Explicit Directory Override

The built-in JSON storage can infer its directory automatically, so this is often enough:

const scenario = createScenario({
  headerName: "x-definitely-fine-scenario-id",
});

If you need scenarios in a known local path, you can still override the directory:

const scenario = createScenario({
  directory: ".definitely-fine",
  headerName: "x-definitely-fine-scenario-id",
});

Typical Setup

1. Build a scenario in the test.
2. Save it before navigating.
3. Create a browser context or page through the scenario helper.
4. Run your browser flow.
5. Let your app's definitely-fine runtime intercept the targeted calls.

Related Packages

• definitely-fine provides the runtime and storage model.
• @definitely-fine/nextjs reads the scenario header inside Next.js route handlers and server actions.