@swedevtools/livedoc-vitest 0.2.0

package/dist/playwright/index.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+var vitest = require('vitest');
+var livedocVitest = require('@swedevtools/livedoc-vitest');
+
+// _src/app/playwright/index.ts
+var playwrightModule;
+var playwrightLoaded = false;
+async function ensurePlaywright() {
+  if (playwrightLoaded) return playwrightModule;
+  try {
+    const moduleName = "playwright";
+    playwrightModule = await import(
+      /* @vite-ignore */
+      moduleName
+    );
+    playwrightLoaded = true;
+    return playwrightModule;
+  } catch {
+    throw new Error(
+      "@swedevtools/livedoc-vitest/playwright requires 'playwright' as a peer dependency.\nInstall it with:\n\n  pnpm add -D playwright\n  npx playwright install chromium\n"
+    );
+  }
+}
+var _screenshotIndex = 0;
+function slugify(text) {
+  return text.toLowerCase().replace(/['"`]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+async function screenshot(page, ctx, options) {
+  const fullPage = options?.fullPage ?? true;
+  const buffer = await page.screenshot({ fullPage });
+  const base64 = buffer.toString("base64");
+  const name = options?.name ?? `${slugify(ctx.step.title)}-${++_screenshotIndex}`;
+  ctx.step.attachScreenshot(base64, name);
+}
+function useBrowser(options) {
+  const baseUrl = options?.baseUrl ?? "http://localhost:3000";
+  const browserName = options?.browser ?? "chromium";
+  const freshContext = options?.freshContextPerScenario ?? false;
+  let _browser;
+  let _context;
+  let _page;
+  vitest.beforeAll(async () => {
+    const pw = await ensurePlaywright();
+    const launcher = pw[browserName];
+    _browser = await launcher.launch(options?.launch ?? { headless: true });
+    if (!freshContext) {
+      _context = await _browser.newContext(options?.context ?? {});
+      _page = await _context.newPage();
+    }
+    _screenshotIndex = 0;
+  });
+  if (freshContext) {
+    livedocVitest.onScenarioStart(async () => {
+      _context = await _browser.newContext(options?.context ?? {});
+      _page = await _context.newPage();
+    });
+    livedocVitest.onScenarioEnd(async () => {
+      await _context?.close().catch(() => {
+      });
+      _page = void 0;
+      _context = void 0;
+    });
+  }
+  vitest.afterAll(async () => {
+    try {
+      await _browser?.close();
+    } catch {
+    } finally {
+      _page = void 0;
+      _context = void 0;
+      _browser = void 0;
+    }
+  });
+  return {
+    page: () => {
+      if (!_page) {
+        throw new Error(
+          "Playwright page is not initialized. Ensure useBrowser() is called at module scope and page() is called inside a step."
+        );
+      }
+      return _page;
+    },
+    context: () => {
+      if (!_context) {
+        throw new Error("Playwright context is not initialized.");
+      }
+      return _context;
+    },
+    browser: () => {
+      if (!_browser) {
+        throw new Error("Playwright browser is not initialized.");
+      }
+      return _browser;
+    },
+    baseUrl
+  };
+}
+var usePlaywright = useBrowser;
+
+exports.screenshot = screenshot;
+exports.useBrowser = useBrowser;
+exports.usePlaywright = usePlaywright;

package/dist/playwright/index.d.cts

@@ -0,0 +1,129 @@
+import { StepContext } from '@swedevtools/livedoc-vitest';
+
+/**
+ * @swedevtools/livedoc-vitest/playwright
+ *
+ * Playwright integration for LiveDoc — browser lifecycle management
+ * and screenshot helpers for BDD feature specs.
+ *
+ * @example
+ * ```typescript
+ * import { feature, scenario, given, when, then } from '@swedevtools/livedoc-vitest';
+ * import { useBrowser, screenshot } from '@swedevtools/livedoc-vitest/playwright';
+ *
+ * const { page, baseUrl } = useBrowser({ baseUrl: 'http://localhost:5174' });
+ *
+ * feature('Checkout Flow', () => {
+ *     scenario('User adds item to cart', () => {
+ *         given("user views the product page", async (ctx) => {
+ *             await page().goto(`${baseUrl}/products/1`);
+ *             await screenshot(page(), ctx);
+ *         });
+ *     });
+ * });
+ * ```
+ */
+
+/** Minimal Page interface — the real Playwright Page has many more methods */
+interface PlaywrightPage {
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<Buffer>;
+    goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
+    close(): Promise<void>;
+    [key: string]: unknown;
+}
+/** Minimal BrowserContext interface */
+interface PlaywrightBrowserContext {
+    newPage(): Promise<PlaywrightPage>;
+    close(): Promise<void>;
+    [key: string]: unknown;
+}
+/** Minimal Browser interface */
+interface PlaywrightBrowser {
+    newContext(options?: Record<string, unknown>): Promise<PlaywrightBrowserContext>;
+    close(): Promise<void>;
+    [key: string]: unknown;
+}
+/** Browser engine to use */
+type BrowserName = "chromium" | "firefox" | "webkit";
+/** Options for useBrowser() / usePlaywright() */
+interface PlaywrightOptions {
+    /** Base URL for navigation (default: 'http://localhost:3000') */
+    baseUrl?: string;
+    /** Browser engine (default: 'chromium') */
+    browser?: BrowserName;
+    /** Options passed directly to browser.launch() */
+    launch?: Record<string, unknown>;
+    /** Options passed directly to browser.newContext() */
+    context?: Record<string, unknown>;
+    /** Create a fresh BrowserContext for each scenario (default: false) */
+    freshContextPerScenario?: boolean;
+}
+/** Return type of useBrowser() */
+interface PlaywrightFixture {
+    /** Get the current Page instance (call inside steps, not at module scope) */
+    page: () => PlaywrightPage;
+    /** Get the current BrowserContext */
+    context: () => PlaywrightBrowserContext;
+    /** Get the Browser instance */
+    browser: () => PlaywrightBrowser;
+    /** Configured base URL */
+    baseUrl: string;
+}
+/** Options for the screenshot() helper */
+interface ScreenshotOptions {
+    /** Override auto-generated screenshot name */
+    name?: string;
+    /** Capture full page scroll height (default: true) */
+    fullPage?: boolean;
+}
+/**
+ * Capture a screenshot and attach it to the current LiveDoc step.
+ *
+ * Auto-generates a descriptive filename from the step title if no name is provided.
+ *
+ * @example
+ * ```typescript
+ * // Auto-named from step title
+ * await screenshot(page(), ctx);
+ *
+ * // Custom name
+ * await screenshot(page(), ctx, { name: 'login-form' });
+ * ```
+ */
+declare function screenshot(page: PlaywrightPage, ctx: {
+    step: StepContext;
+}, options?: ScreenshotOptions): Promise<void>;
+/**
+ * Initialize Playwright browser lifecycle for a feature file.
+ *
+ * Call at **module scope** (outside `feature()` block) to get feature-level
+ * browser sharing. The browser launches once and is shared across all
+ * scenarios in the file.
+ *
+ * @example
+ * ```typescript
+ * import { useBrowser, screenshot } from '@swedevtools/livedoc-vitest/playwright';
+ *
+ * const { page, baseUrl } = useBrowser({
+ *     baseUrl: 'http://localhost:5174',
+ *     browser: 'chromium',
+ *     launch: { headless: process.env.CI === 'true' },
+ * });
+ *
+ * feature('My Feature', () => {
+ *     scenario('My Scenario', () => {
+ *         given("I open the app", async (ctx) => {
+ *             await page().goto(baseUrl);
+ *             await screenshot(page(), ctx);
+ *         });
+ *     });
+ * });
+ * ```
+ */
+declare function useBrowser(options?: PlaywrightOptions): PlaywrightFixture;
+/** Alias for useBrowser() */
+declare const usePlaywright: typeof useBrowser;
+
+export { type BrowserName, type PlaywrightBrowser, type PlaywrightBrowserContext, type PlaywrightFixture, type PlaywrightOptions, type PlaywrightPage, type ScreenshotOptions, screenshot, useBrowser, usePlaywright };

package/dist/playwright/index.d.ts

@@ -0,0 +1,129 @@
+import { StepContext } from '@swedevtools/livedoc-vitest';
+
+/**
+ * @swedevtools/livedoc-vitest/playwright
+ *
+ * Playwright integration for LiveDoc — browser lifecycle management
+ * and screenshot helpers for BDD feature specs.
+ *
+ * @example
+ * ```typescript
+ * import { feature, scenario, given, when, then } from '@swedevtools/livedoc-vitest';
+ * import { useBrowser, screenshot } from '@swedevtools/livedoc-vitest/playwright';
+ *
+ * const { page, baseUrl } = useBrowser({ baseUrl: 'http://localhost:5174' });
+ *
+ * feature('Checkout Flow', () => {
+ *     scenario('User adds item to cart', () => {
+ *         given("user views the product page", async (ctx) => {
+ *             await page().goto(`${baseUrl}/products/1`);
+ *             await screenshot(page(), ctx);
+ *         });
+ *     });
+ * });
+ * ```
+ */
+
+/** Minimal Page interface — the real Playwright Page has many more methods */
+interface PlaywrightPage {
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<Buffer>;
+    goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
+    close(): Promise<void>;
+    [key: string]: unknown;
+}
+/** Minimal BrowserContext interface */
+interface PlaywrightBrowserContext {
+    newPage(): Promise<PlaywrightPage>;
+    close(): Promise<void>;
+    [key: string]: unknown;
+}
+/** Minimal Browser interface */
+interface PlaywrightBrowser {
+    newContext(options?: Record<string, unknown>): Promise<PlaywrightBrowserContext>;
+    close(): Promise<void>;
+    [key: string]: unknown;
+}
+/** Browser engine to use */
+type BrowserName = "chromium" | "firefox" | "webkit";
+/** Options for useBrowser() / usePlaywright() */
+interface PlaywrightOptions {
+    /** Base URL for navigation (default: 'http://localhost:3000') */
+    baseUrl?: string;
+    /** Browser engine (default: 'chromium') */
+    browser?: BrowserName;
+    /** Options passed directly to browser.launch() */
+    launch?: Record<string, unknown>;
+    /** Options passed directly to browser.newContext() */
+    context?: Record<string, unknown>;
+    /** Create a fresh BrowserContext for each scenario (default: false) */
+    freshContextPerScenario?: boolean;
+}
+/** Return type of useBrowser() */
+interface PlaywrightFixture {
+    /** Get the current Page instance (call inside steps, not at module scope) */
+    page: () => PlaywrightPage;
+    /** Get the current BrowserContext */
+    context: () => PlaywrightBrowserContext;
+    /** Get the Browser instance */
+    browser: () => PlaywrightBrowser;
+    /** Configured base URL */
+    baseUrl: string;
+}
+/** Options for the screenshot() helper */
+interface ScreenshotOptions {
+    /** Override auto-generated screenshot name */
+    name?: string;
+    /** Capture full page scroll height (default: true) */
+    fullPage?: boolean;
+}
+/**
+ * Capture a screenshot and attach it to the current LiveDoc step.
+ *
+ * Auto-generates a descriptive filename from the step title if no name is provided.
+ *
+ * @example
+ * ```typescript
+ * // Auto-named from step title
+ * await screenshot(page(), ctx);
+ *
+ * // Custom name
+ * await screenshot(page(), ctx, { name: 'login-form' });
+ * ```
+ */
+declare function screenshot(page: PlaywrightPage, ctx: {
+    step: StepContext;
+}, options?: ScreenshotOptions): Promise<void>;
+/**
+ * Initialize Playwright browser lifecycle for a feature file.
+ *
+ * Call at **module scope** (outside `feature()` block) to get feature-level
+ * browser sharing. The browser launches once and is shared across all
+ * scenarios in the file.
+ *
+ * @example
+ * ```typescript
+ * import { useBrowser, screenshot } from '@swedevtools/livedoc-vitest/playwright';
+ *
+ * const { page, baseUrl } = useBrowser({
+ *     baseUrl: 'http://localhost:5174',
+ *     browser: 'chromium',
+ *     launch: { headless: process.env.CI === 'true' },
+ * });
+ *
+ * feature('My Feature', () => {
+ *     scenario('My Scenario', () => {
+ *         given("I open the app", async (ctx) => {
+ *             await page().goto(baseUrl);
+ *             await screenshot(page(), ctx);
+ *         });
+ *     });
+ * });
+ * ```
+ */
+declare function useBrowser(options?: PlaywrightOptions): PlaywrightFixture;
+/** Alias for useBrowser() */
+declare const usePlaywright: typeof useBrowser;
+
+export { type BrowserName, type PlaywrightBrowser, type PlaywrightBrowserContext, type PlaywrightFixture, type PlaywrightOptions, type PlaywrightPage, type ScreenshotOptions, screenshot, useBrowser, usePlaywright };

package/dist/playwright/index.js

@@ -0,0 +1,99 @@
+import { beforeAll, afterAll } from 'vitest';
+import { onScenarioStart, onScenarioEnd } from '@swedevtools/livedoc-vitest';
+
+// _src/app/playwright/index.ts
+var playwrightModule;
+var playwrightLoaded = false;
+async function ensurePlaywright() {
+  if (playwrightLoaded) return playwrightModule;
+  try {
+    const moduleName = "playwright";
+    playwrightModule = await import(
+      /* @vite-ignore */
+      moduleName
+    );
+    playwrightLoaded = true;
+    return playwrightModule;
+  } catch {
+    throw new Error(
+      "@swedevtools/livedoc-vitest/playwright requires 'playwright' as a peer dependency.\nInstall it with:\n\n  pnpm add -D playwright\n  npx playwright install chromium\n"
+    );
+  }
+}
+var _screenshotIndex = 0;
+function slugify(text) {
+  return text.toLowerCase().replace(/['"`]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+async function screenshot(page, ctx, options) {
+  const fullPage = options?.fullPage ?? true;
+  const buffer = await page.screenshot({ fullPage });
+  const base64 = buffer.toString("base64");
+  const name = options?.name ?? `${slugify(ctx.step.title)}-${++_screenshotIndex}`;
+  ctx.step.attachScreenshot(base64, name);
+}
+function useBrowser(options) {
+  const baseUrl = options?.baseUrl ?? "http://localhost:3000";
+  const browserName = options?.browser ?? "chromium";
+  const freshContext = options?.freshContextPerScenario ?? false;
+  let _browser;
+  let _context;
+  let _page;
+  beforeAll(async () => {
+    const pw = await ensurePlaywright();
+    const launcher = pw[browserName];
+    _browser = await launcher.launch(options?.launch ?? { headless: true });
+    if (!freshContext) {
+      _context = await _browser.newContext(options?.context ?? {});
+      _page = await _context.newPage();
+    }
+    _screenshotIndex = 0;
+  });
+  if (freshContext) {
+    onScenarioStart(async () => {
+      _context = await _browser.newContext(options?.context ?? {});
+      _page = await _context.newPage();
+    });
+    onScenarioEnd(async () => {
+      await _context?.close().catch(() => {
+      });
+      _page = void 0;
+      _context = void 0;
+    });
+  }
+  afterAll(async () => {
+    try {
+      await _browser?.close();
+    } catch {
+    } finally {
+      _page = void 0;
+      _context = void 0;
+      _browser = void 0;
+    }
+  });
+  return {
+    page: () => {
+      if (!_page) {
+        throw new Error(
+          "Playwright page is not initialized. Ensure useBrowser() is called at module scope and page() is called inside a step."
+        );
+      }
+      return _page;
+    },
+    context: () => {
+      if (!_context) {
+        throw new Error("Playwright context is not initialized.");
+      }
+      return _context;
+    },
+    browser: () => {
+      if (!_browser) {
+        throw new Error("Playwright browser is not initialized.");
+      }
+      return _browser;
+    },
+    baseUrl
+  };
+}
+var usePlaywright = useBrowser;
+
+export { screenshot, useBrowser, usePlaywright };