@autometa/playwright-loader 1.0.0-rc.0

package/README.md

@@ -0,0 +1,97 @@
+# @autometa/playwright-loader
+
+Node.js module loader hooks for transforming `.feature` files into Playwright test suites.
+
+## Overview
+
+This package provides the infrastructure to run Gherkin feature files directly with Playwright by leveraging Node.js customization hooks to transform `.feature` imports on-the-fly.
+
+## Installation
+
+```bash
+pnpm add @autometa/playwright-loader @playwright/test
+```
+
+## Usage
+
+### Option 1: Import in playwright.config.ts
+
+```typescript
+import '@autometa/playwright-loader/register';
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testMatch: '**/*.feature',
+});
+```
+
+### Option 2: Use with NODE_OPTIONS
+
+```bash
+NODE_OPTIONS="--import @autometa/playwright-loader/register" npx playwright test
+```
+
+### Option 3: Use with autometa CLI
+
+```typescript
+// autometa.config.ts
+import { defineConfig } from '@autometa/app';
+
+export default defineConfig({
+  runner: 'playwright',
+  roots: {
+    features: ['features'],
+    steps: ['steps'],
+  },
+});
+```
+
+Then run:
+
+```bash
+pnpm autometa run
+```
+
+## How It Works
+
+1. **Node.js Module Hooks**: The loader uses Node.js's `module.register()` API to intercept `.feature` file imports.
+
+2. **Resolve Hook**: When a `.feature` file is imported, the resolve hook marks it with a custom format.
+
+3. **Load Hook**: The load hook transforms the `.feature` content into a Playwright test module:
+   - Parses the Gherkin content
+   - Loads step definitions from `autometa.config.ts`
+   - Generates `test.describe()` and `test()` blocks
+
+4. **Playwright Integration**: The generated code uses Playwright's fixtures (`page`, `context`, etc.) and assertions.
+
+## Requirements
+
+- Node.js 18.19+ or 20.6+ (for module customization hooks)
+- Playwright 1.40+
+- TypeScript (recommended)
+
+## Architecture
+
+```
+.feature file import
+        │
+        ▼
+┌───────────────────┐
+│   resolve hook    │ ← Intercepts .feature specifiers
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│    load hook      │ ← Transforms to Playwright test code
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│  Playwright test  │ ← Native execution with fixtures
+└───────────────────┘
+```
+
+## License
+
+MIT

package/dist/bridge-generator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bridge Code Generator for Playwright.
+ *
+ * Generates JavaScript/TypeScript code that transforms a Gherkin feature file
+ * into a Playwright test suite using `test.describe` and `test()`.
+ *
+ * This is heavily based on the vitest-plugins transform but adapted for
+ * Playwright's test runner and Node.js module loader hooks.
+ */
+import type { Config } from "@autometa/config";
+export interface BridgeGeneratorOptions {
+    /** The absolute path to the .feature file */
+    featurePath: string;
+    /** The raw content of the .feature file */
+    featureContent: string;
+    /** The resolved autometa config (optional, will be loaded if not provided) */
+    config?: Config;
+    /** The path to the autometa config file */
+    configPath?: string;
+    /** The project root directory */
+    projectRoot?: string;
+}
+/**
+ * Generate Playwright bridge code for a .feature file.
+ *
+ * The generated code:
+ * 1. Imports Playwright's test runner and Autometa executors
+ * 2. Uses glob imports to load step definition modules
+ * 3. Parses the feature file at runtime
+ * 4. Coordinates the runner and executes tests
+ *
+ * @param featurePath - Absolute path to the .feature file
+ * @param featureContent - Raw content of the .feature file
+ * @param runtimeProjectRoot - The project root where packages should be resolved from (usually process.cwd())
+ * @returns Generated ESM module code
+ */
+export declare function generateBridgeCode(featurePath: string, featureContent: string, runtimeProjectRoot?: string): string;
+/**
+ * Escape a string for use in generated code.
+ */
+export declare function escapeString(str: string): string;