@definitely-fine/playwright 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 definitely-fine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @definitely-fine/playwright
+
+`@definitely-fine/playwright` helps Playwright tests activate `definitely-fine` scenarios in browser-driven flows.
+
+It extends the core scenario builder with request headers plus helpers for creating browser contexts and pages that already send the active scenario id.
+
+## Installation
+
+```bash
+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?)`
+
+```mermaid
+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
+
+```ts
+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:
+
+```ts
+const scenario = createScenario({
+  headerName: "x-definitely-fine-scenario-id",
+});
+```
+
+If you need scenarios in a known local path, you can still override the directory:
+
+```ts
+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`](../definitely-fine/README.md) provides the runtime and storage model.
+- [`@definitely-fine/nextjs`](../nextjs/README.md) reads the scenario header inside Next.js route handlers and server actions.

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+import { BrowserContextOptions } from "@playwright/test";
+
+//#region ../definitely-fine/src/types.d.ts
+/**
+* Generic callable shape used throughout definitely-fine contracts.
+* @public
+*/
+/**
+ * Generic callable shape used throughout definitely-fine contracts.
+ * @public
+ */
+type UnknownFunction = (...args: never[]) => unknown;
+/**
+ * Contract shape for a named service whose values are callable methods.
+ * @public
+ */
+type ServiceContract = Record<string, UnknownFunction>;
+/**
+ * Map of named services available to a system under test.
+ * @public
+ */
+type ServiceContracts = Record<string, ServiceContract>;
+/**
+ * Map of named top-level functions available to a system under test.
+ * @public
+ */
+type FunctionContracts = Record<string, UnknownFunction>;
+/**
+ * Map of named error factory functions available to a runtime.
+ * @public
+ */
+type ErrorFactoryContracts = Record<string, UnknownFunction>;
+/**
+ * Full contract definition for services, functions, and error factories.
+ * @public
+ */
+type SutContract = {
+  /**
+   * Named service contracts whose members are callable methods.
+   */
+  services: ServiceContracts;
+  /**
+   * Named top-level function contracts.
+   */
+  functions: FunctionContracts;
+  /**
+   * Named error factory contracts available to runtime rules.
+   */
+  errors: ErrorFactoryContracts;
+};
+/**
+ * Union of valid service names from a contract.
+ * @public
+ */
+type ContractServiceName<TContract extends SutContract> = Extract<keyof TContract["services"], string>;
+/**
+ * Union of valid function names from a contract.
+ * @public
+ */
+type ContractFunctionName<TContract extends SutContract> = Extract<keyof TContract["functions"], string>;
+/**
+ * Union of valid error factory names from a contract.
+ * @public
+ */
+type ContractErrorFactoryName<TContract extends SutContract> = Extract<keyof TContract["errors"], string>;
+/**
+ * Union of valid method names for a service in a contract.
+ * @public
+ */
+type ContractServiceMethodName<TContract extends SutContract, TServiceName extends ContractServiceName<TContract>> = Extract<keyof TContract["services"][TServiceName], string>;
+/**
+ * Function type for a named contract function.
+ * @public
+ */
+type ContractFunction<TContract extends SutContract, TFunctionName extends ContractFunctionName<TContract>> = TContract["functions"][TFunctionName];
+/**
+ * Method type for a named service method in a contract.
+ * @public
+ */
+type ContractServiceMethod<TContract extends SutContract, TServiceName extends ContractServiceName<TContract>, TMethodName extends ContractServiceMethodName<TContract, TServiceName>> = TContract["services"][TServiceName][TMethodName];
+/**
+ * Error factory type for a named contract factory.
+ * @public
+ */
+type ContractErrorFactory<TContract extends SutContract, TFactoryName extends ContractErrorFactoryName<TContract>> = TContract["errors"][TFactoryName];
+/**
+ * Resolved return value for a named contract function.
+ * @public
+ */
+type ContractFunctionReturnValue<TContract extends SutContract, TFunctionName extends ContractFunctionName<TContract>> = Awaited<ReturnType<ContractFunction<TContract, TFunctionName>>>;
+/**
+ * Resolved return value for a named contract service method.
+ * @public
+ */
+type ContractServiceMethodReturnValue<TContract extends SutContract, TServiceName extends ContractServiceName<TContract>, TMethodName extends ContractServiceMethodName<TContract, TServiceName>> = Awaited<ReturnType<ContractServiceMethod<TContract, TServiceName, TMethodName>>>;
+/**
+ * First input argument accepted by a named contract error factory.
+ * @public
+ */
+type ContractErrorFactoryInput<TContract extends SutContract, TFactoryName extends ContractErrorFactoryName<TContract>> = Parameters<ContractErrorFactory<TContract, TFactoryName>>[0];
+type ContractErrorFactoryParameters<TContract extends SutContract, TFactoryName extends ContractErrorFactoryName<TContract>> = Parameters<ContractErrorFactory<TContract, TFactoryName>>;
+/**
+ * Tuple form accepted when configuring a thrown error factory action.
+ * @public
+ */
+type ContractErrorFactoryArguments<TContract extends SutContract, TFactoryName extends ContractErrorFactoryName<TContract>> = ContractErrorFactoryParameters<TContract, TFactoryName>["length"] extends 0 ? [] : 0 extends ContractErrorFactoryParameters<TContract, TFactoryName>["length"] ? [input?: ContractErrorFactoryInput<TContract, TFactoryName>] : [input: ContractErrorFactoryInput<TContract, TFactoryName>];
+/**
+ * Serialized identifier for a wrapped function or service method target.
+ * @public
+ */
+type SerializedTarget = {
+  /**
+   * Marks the target as a service method.
+   */
+  kind: "service-method";
+  /**
+   * Service name that owns the intercepted method.
+   */
+  service: string;
+  /**
+   * Method name being intercepted on the service.
+   */
+  method: string;
+} | {
+  /**
+   * Marks the target as a top-level function.
+   */
+  kind: "function";
+  /**
+   * Function name being intercepted.
+   */
+  function: string;
+};
+/**
+ * Serialized scenario action executed when a rule matches.
+ * @public
+ */
+type SerializedAction = {
+  /**
+   * Marks the action as returning a value.
+   */
+  kind: "return";
+  /**
+   * Value returned to the caller when the rule matches.
+   */
+  value: unknown;
+} | {
+  /**
+   * Marks the action as throwing a plain error message.
+   */
+  kind: "throw-message";
+  /**
+   * Error message thrown when the rule matches.
+   */
+  message: string;
+} | {
+  /**
+   * Marks the action as invoking an error factory.
+   */
+  kind: "throw-factory";
+  /**
+   * Registered error factory name to invoke.
+   */
+  factory: string;
+  /**
+   * Optional input passed to the error factory.
+   */
+  input?: unknown;
+};
+/**
+ * Serialized interception rule for a single call target and call number.
+ * @public
+ */
+type SerializedRule = {
+  /**
+   * Target that this rule applies to.
+   */
+  target: SerializedTarget;
+  /**
+   * One-based call number that activates this rule.
+   */
+  callNumber: number;
+  /**
+   * Action executed when the target is called at the matching count.
+   */
+  action: SerializedAction;
+};
+/**
+ * Serialized scenario document persisted by storage adapters.
+ * @public
+ */
+type SerializedScenario = {
+  /**
+   * Stable identifier for the persisted scenario.
+   */
+  id: string;
+  /**
+   * Persisted schema version for the scenario document.
+   */
+  version: 1;
+  /**
+   * ISO timestamp when the scenario was created.
+   */
+  createdAt: string;
+  /**
+   * Ordered list of interception rules stored in the scenario.
+   */
+  rules: SerializedRule[];
+};
+/**
+ * Async-local context that carries the active runtime scenario id.
+ * @public
+ */
+
+/**
+ * Builder API for assigning an action to a single intercepted call.
+ * @public
+ */
+type ScenarioActionBuilder<TContract extends SutContract, TReturnValue> = {
+  returns(value: TReturnValue): ScenarioBuilder<TContract>;
+  throwsMessage(message: string): ScenarioBuilder<TContract>;
+  throwsFactory<TFactoryName extends ContractErrorFactoryName<TContract>>(factory: TFactoryName, ...args: ContractErrorFactoryArguments<TContract, TFactoryName>): ScenarioBuilder<TContract>;
+};
+/**
+ * Builder API for configuring rules for a named function.
+ * @public
+ */
+type ScenarioFunctionRuleBuilder<TContract extends SutContract, TFunctionName extends ContractFunctionName<TContract>> = {
+  onCall(callNumber: number): ScenarioActionBuilder<TContract, ContractFunctionReturnValue<TContract, TFunctionName>>;
+};
+/**
+ * Builder API for configuring rules for a named service method.
+ * @public
+ */
+type ScenarioServiceMethodRuleBuilder<TContract extends SutContract, TServiceName extends ContractServiceName<TContract>, TMethodName extends ContractServiceMethodName<TContract, TServiceName>> = {
+  onCall(callNumber: number): ScenarioActionBuilder<TContract, ContractServiceMethodReturnValue<TContract, TServiceName, TMethodName>>;
+};
+/**
+ * Builder API for selecting a method on a named service.
+ * @public
+ */
+type ScenarioServiceRuleBuilder<TContract extends SutContract, TServiceName extends ContractServiceName<TContract>> = {
+  method<TMethodName extends ContractServiceMethodName<TContract, TServiceName>>(method: TMethodName): ScenarioServiceMethodRuleBuilder<TContract, TServiceName, TMethodName>;
+};
+/**
+ * Scenario builder API used to author and persist interception rules.
+ * @public
+ */
+type ScenarioBuilder<TContract extends SutContract> = {
+  /**
+   * Phantom contract marker that preserves generic inference.
+   */
+  readonly __contract?: TContract;
+  /**
+   * Scenario id that will be used for persistence and runtime lookup.
+   */
+  readonly id: string;
+  service<TServiceName extends ContractServiceName<TContract>>(service: TServiceName): ScenarioServiceRuleBuilder<TContract, TServiceName>;
+  fn<TFunctionName extends ContractFunctionName<TContract>>(fn: TFunctionName): ScenarioFunctionRuleBuilder<TContract, TFunctionName>;
+  save(): Promise<void>;
+  dispose(): Promise<void>;
+};
+
+//#endregion
+//#region ../definitely-fine/src/services/interfaces/IScenarioStorageAdapter.d.ts
+/**
+ * Runtime API for wrapping contract functions and services.
+ * @public
+ */
+/**
+ * Storage contract for loading, saving, and deleting persisted scenarios.
+ * @public
+ */
+interface IScenarioStorageAdapter {
+  saveScenario(scenario: SerializedScenario): Promise<void>;
+  loadScenario(scenarioId: string): SerializedScenario | undefined;
+  deleteScenario(scenarioId: string): Promise<void>;
+  describeScenarioLocation?(scenarioId: string): string;
+}
+
+//#endregion
+//#region ../definitely-fine/src/index.d.ts
+//# sourceMappingURL=IScenarioStorageAdapter.d.ts.map
+
+/**
+ * Storage options for persisting scenarios.
+ *
+ * Pass an explicit `adapter` to route persistence through custom storage, or a
+ * `directory` to keep using the built-in file adapter behavior.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   JsonScenarioStorageAdapter,
+ *   createScenario,
+ *   type IScenarioStorageAdapter,
+ * } from "definitely-fine";
+ *
+ * const customAdapter: IScenarioStorageAdapter = {
+ *   async deleteScenario(_scenarioId) {},
+ *   loadScenario(_scenarioId) {
+ *     return undefined;
+ *   },
+ *   async saveScenario(_scenario) {},
+ * };
+ *
+ * createScenario({
+ *   adapter: new JsonScenarioStorageAdapter({}),
+ * });
+ *
+ * createScenario({
+ *   adapter: customAdapter,
+ * });
+ * ```
+ * @public
+ */
+type ScenarioOptions = {
+  /**
+   * Omit storage options to use the built-in JSON adapter with its inferred default directory.
+   */
+  adapter?: never;
+  /**
+   * Omit storage options to use the built-in JSON adapter with its inferred default directory.
+   */
+  directory?: never;
+} | {
+  /**
+   * Directory where the scenario should be saved.
+   */
+  directory: string;
+  /**
+   * Explicit adapters cannot be combined with a directory.
+   */
+  adapter?: never;
+} | {
+  /**
+   * Custom adapter used to persist the scenario.
+   */
+  adapter: IScenarioStorageAdapter;
+  /**
+   * Explicit adapters cannot be combined with a directory.
+   */
+  directory?: never;
+};
+
+//#endregion
+//#region src/index.d.ts
+type BrowserContextFactory<TBrowserContext> = {
+  newContext(options?: BrowserContextOptions): Promise<TBrowserContext>;
+};
+type BrowserPageFactory<TPage> = {
+  newPage(): Promise<TPage>;
+};
+/**
+ * Playwright-aware scenario builder that can create preconfigured browser contexts.
+ * @public
+ */
+type PlaywrightScenario<TContract extends SutContract> = ScenarioBuilder<TContract> & {
+  /**
+   * Header name used to activate the persisted scenario at runtime.
+   */
+  readonly headerName: string;
+  /**
+   * Request headers that activate the persisted scenario in browser-driven tests.
+   */
+  readonly headers: Record<string, string>;
+  /**
+   * Creates a new browser context with the scenario header already applied.
+   */
+  createContext<TBrowserContext>(browser: BrowserContextFactory<TBrowserContext>, options?: BrowserContextOptions): Promise<TBrowserContext>;
+  /**
+   * Creates a new page from a browser context that already includes the scenario header.
+   */
+  createPage<TPage, TBrowserContext extends BrowserPageFactory<TPage>>(browser: BrowserContextFactory<TBrowserContext>, options?: BrowserContextOptions): Promise<TPage>;
+};
+/**
+ * Options for creating a Playwright-aware definitely-fine scenario.
+ * @public
+ *
+ * @example
+ * ```ts
+ * import { createScenario } from "@definitely-fine/playwright";
+ *
+ * const scenario = createScenario({
+ *   headerName: "x-scenario-id",
+ * });
+ * ```
+ */
+type CreatePlaywrightScenarioOptions = ScenarioOptions & {
+  /**
+   * Header name used to activate the saved scenario in browser requests.
+   */
+  headerName: string;
+};
+/**
+ * Creates a definitely-fine scenario builder with helpers for Playwright browser contexts.
+ * @public
+ *
+ * @example
+ * ```ts
+ * import { test } from "@playwright/test";
+ * import { createScenario } from "@definitely-fine/playwright";
+ *
+ * test("uses a scenario-backed page", async ({ browser }) => {
+ *   const scenario = createScenario({
+ *     headerName: "x-scenario-id",
+ *   });
+ *
+ *   await scenario.save();
+ *
+ *   const page = await scenario.createPage(browser);
+ *   await page.goto("/");
+ * });
+ * ```
+ */
+declare function createScenario<TContract extends SutContract>(options: CreatePlaywrightScenarioOptions): PlaywrightScenario<TContract>;
+
+//#endregion
+export { CreatePlaywrightScenarioOptions, PlaywrightScenario, createScenario };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../definitely-fine/src/types.ts","../../definitely-fine/src/services/interfaces/IScenarioStorageAdapter.ts","../../definitely-fine/src/index.ts","../src/index.ts"],"sourcesContent":null,"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,54 @@
+import { createScenario as createScenario$1 } from "definitely-fine";
+
+//#region src/index.ts
+function mergeScenarioHeaders(extraHTTPHeaders, scenarioHeaders) {
+	const mergedHeaders = new Headers(extraHTTPHeaders);
+	for (const [name, value] of Object.entries(scenarioHeaders)) mergedHeaders.set(name, value);
+	return Object.fromEntries(mergedHeaders.entries());
+}
+function createPlaywrightScenarioHelpers(scenario, headerName) {
+	const headers = { [headerName]: scenario.id };
+	return {
+		headerName,
+		headers,
+		async createContext(browser, options = {}) {
+			return browser.newContext({
+				...options,
+				extraHTTPHeaders: mergeScenarioHeaders(options.extraHTTPHeaders, headers)
+			});
+		},
+		async createPage(browser, options = {}) {
+			const context = await this.createContext(browser, options);
+			return context.newPage();
+		}
+	};
+}
+/**
+* Creates a definitely-fine scenario builder with helpers for Playwright browser contexts.
+* @public
+*
+* @example
+* ```ts
+* import { test } from "@playwright/test";
+* import { createScenario } from "@definitely-fine/playwright";
+*
+* test("uses a scenario-backed page", async ({ browser }) => {
+*   const scenario = createScenario({
+*     headerName: "x-scenario-id",
+*   });
+*
+*   await scenario.save();
+*
+*   const page = await scenario.createPage(browser);
+*   await page.goto("/");
+* });
+* ```
+*/
+function createScenario(options) {
+	const scenario = createScenario$1(options);
+	return Object.assign(scenario, createPlaywrightScenarioHelpers(scenario, options.headerName));
+}
+
+//#endregion
+export { createScenario };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["extraHTTPHeaders: BrowserContextOptions[\"extraHTTPHeaders\"]","scenarioHeaders: Record<string, string>","scenario: ScenarioBuilder<TContract>","headerName: string","browser: BrowserContextFactory<TBrowserContext>","options: BrowserContextOptions","options: CreatePlaywrightScenarioOptions"],"sources":["../src/index.ts"],"sourcesContent":["import { createScenario as createCoreScenario } from \"definitely-fine\";\n\nimport type { BrowserContextOptions } from \"@playwright/test\";\nimport type {\n  ScenarioBuilder,\n  ScenarioOptions,\n  SutContract,\n} from \"definitely-fine\";\n\ntype BrowserContextFactory<TBrowserContext> = {\n  newContext(options?: BrowserContextOptions): Promise<TBrowserContext>;\n};\n\ntype BrowserPageFactory<TPage> = {\n  newPage(): Promise<TPage>;\n};\n\n/**\n * Playwright-aware scenario builder that can create preconfigured browser contexts.\n * @public\n */\nexport type PlaywrightScenario<TContract extends SutContract> =\n  ScenarioBuilder<TContract> & {\n    /**\n     * Header name used to activate the persisted scenario at runtime.\n     */\n    readonly headerName: string;\n    /**\n     * Request headers that activate the persisted scenario in browser-driven tests.\n     */\n    readonly headers: Record<string, string>;\n    /**\n     * Creates a new browser context with the scenario header already applied.\n     */\n    createContext<TBrowserContext>(\n      browser: BrowserContextFactory<TBrowserContext>,\n      options?: BrowserContextOptions,\n    ): Promise<TBrowserContext>;\n    /**\n     * Creates a new page from a browser context that already includes the scenario header.\n     */\n    createPage<TPage, TBrowserContext extends BrowserPageFactory<TPage>>(\n      browser: BrowserContextFactory<TBrowserContext>,\n      options?: BrowserContextOptions,\n    ): Promise<TPage>;\n  };\n\n/**\n * Options for creating a Playwright-aware definitely-fine scenario.\n * @public\n *\n * @example\n * ```ts\n * import { createScenario } from \"@definitely-fine/playwright\";\n *\n * const scenario = createScenario({\n *   headerName: \"x-scenario-id\",\n * });\n * ```\n */\nexport type CreatePlaywrightScenarioOptions = ScenarioOptions & {\n  /**\n   * Header name used to activate the saved scenario in browser requests.\n   */\n  headerName: string;\n};\n\nfunction mergeScenarioHeaders(\n  extraHTTPHeaders: BrowserContextOptions[\"extraHTTPHeaders\"],\n  scenarioHeaders: Record<string, string>,\n): Record<string, string> {\n  const mergedHeaders = new Headers(extraHTTPHeaders);\n\n  for (const [name, value] of Object.entries(scenarioHeaders)) {\n    mergedHeaders.set(name, value);\n  }\n\n  return Object.fromEntries(mergedHeaders.entries());\n}\n\nfunction createPlaywrightScenarioHelpers<TContract extends SutContract>(\n  scenario: ScenarioBuilder<TContract>,\n  headerName: string,\n) {\n  const headers = {\n    [headerName]: scenario.id,\n  };\n\n  return {\n    headerName,\n    headers,\n    async createContext<TBrowserContext>(\n      browser: BrowserContextFactory<TBrowserContext>,\n      options: BrowserContextOptions = {},\n    ): Promise<TBrowserContext> {\n      return browser.newContext({\n        ...options,\n        extraHTTPHeaders: mergeScenarioHeaders(\n          options.extraHTTPHeaders,\n          headers,\n        ),\n      });\n    },\n    async createPage<TPage, TBrowserContext extends BrowserPageFactory<TPage>>(\n      browser: BrowserContextFactory<TBrowserContext>,\n      options: BrowserContextOptions = {},\n    ): Promise<TPage> {\n      const context = await this.createContext(browser, options);\n\n      return context.newPage();\n    },\n  };\n}\n\n/**\n * Creates a definitely-fine scenario builder with helpers for Playwright browser contexts.\n * @public\n *\n * @example\n * ```ts\n * import { test } from \"@playwright/test\";\n * import { createScenario } from \"@definitely-fine/playwright\";\n *\n * test(\"uses a scenario-backed page\", async ({ browser }) => {\n *   const scenario = createScenario({\n *     headerName: \"x-scenario-id\",\n *   });\n *\n *   await scenario.save();\n *\n *   const page = await scenario.createPage(browser);\n *   await page.goto(\"/\");\n * });\n * ```\n */\nexport function createScenario<TContract extends SutContract>(\n  options: CreatePlaywrightScenarioOptions,\n): PlaywrightScenario<TContract> {\n  const scenario = createCoreScenario<TContract>(options);\n\n  return Object.assign(\n    scenario,\n    createPlaywrightScenarioHelpers(scenario, options.headerName),\n  );\n}\n"],"mappings":";;;AAmEA,SAAS,qBACPA,kBACAC,iBACwB;CACxB,MAAM,gBAAgB,IAAI,QAAQ;AAElC,MAAK,MAAM,CAAC,MAAM,MAAM,IAAI,OAAO,QAAQ,gBAAgB,CACzD,eAAc,IAAI,MAAM,MAAM;AAGhC,QAAO,OAAO,YAAY,cAAc,SAAS,CAAC;AACnD;AAED,SAAS,gCACPC,UACAC,YACA;CACA,MAAM,UAAU,GACb,aAAa,SAAS,GACxB;AAED,QAAO;EACL;EACA;EACA,MAAM,cACJC,SACAC,UAAiC,CAAE,GACT;AAC1B,UAAO,QAAQ,WAAW;IACxB,GAAG;IACH,kBAAkB,qBAChB,QAAQ,kBACR,QACD;GACF,EAAC;EACH;EACD,MAAM,WACJD,SACAC,UAAiC,CAAE,GACnB;GAChB,MAAM,UAAU,MAAM,KAAK,cAAc,SAAS,QAAQ;AAE1D,UAAO,QAAQ,SAAS;EACzB;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,eACdC,SAC+B;CAC/B,MAAM,WAAW,iBAA8B,QAAQ;AAEvD,QAAO,OAAO,OACZ,UACA,gCAAgC,UAAU,QAAQ,WAAW,CAC9D;AACF"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@definitely-fine/playwright",
+  "version": "0.1.0",
+  "description": "Playwright helpers for definitely-fine.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "definitely-fine": "0.1.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.56.1"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.56"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --publint",
+    "typecheck": "tsc --project tsconfig.json"
+  }
+}