@supernal/interface 1.0.0

package/dist/esm/src/testing/GherkinParser.js

@@ -0,0 +1,248 @@
+/**
+ * Gherkin Parser
+ *
+ * Parses Gherkin .feature files and converts them to executable test scenarios.
+ * Basic open-source version (Story system is enterprise edition).
+ */
+// Story system moved to enterprise edition
+// import { StoryBuilder, StoryDefinition, StoryRegistry } from '../background/stories.js';
+import { ToolRegistry } from '../background/registry/ToolRegistry.js';
+export class GherkinParser {
+    /**
+     * Parse a Gherkin feature file content
+     */
+    static parseFeature(content) {
+        const lines = content.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+        let feature = {
+            scenarios: []
+        };
+        let currentScenario = null;
+        let tags = [];
+        for (const line of lines) {
+            // Parse tags
+            if (line.startsWith('@')) {
+                tags = line.split(/\s+/).map(t => t.substring(1));
+                continue;
+            }
+            // Parse feature
+            if (line.startsWith('Feature:')) {
+                feature.name = line.substring(8).trim();
+                if (tags.length > 0) {
+                    feature.tags = tags;
+                    tags = [];
+                }
+                continue;
+            }
+            // Parse scenario
+            if (line.startsWith('Scenario:')) {
+                if (currentScenario) {
+                    feature.scenarios.push(currentScenario);
+                }
+                currentScenario = {
+                    name: line.substring(9).trim(),
+                    tags: tags.length > 0 ? tags : undefined,
+                    steps: []
+                };
+                tags = [];
+                continue;
+            }
+            // Parse steps
+            const stepMatch = line.match(/^(Given|When|Then|And|But)\s+(.+)$/);
+            if (stepMatch && currentScenario) {
+                const [, keyword, text] = stepMatch;
+                currentScenario.steps.push({
+                    keyword: keyword,
+                    text
+                });
+            }
+            // Description (lines after Feature: but before Scenario:)
+            if (!line.startsWith('Feature:') && !line.startsWith('Scenario:') && !stepMatch && feature.name && !currentScenario) {
+                feature.description = (feature.description || '') + line + ' ';
+            }
+        }
+        // Add last scenario
+        if (currentScenario) {
+            feature.scenarios.push(currentScenario);
+        }
+        return feature;
+    }
+    /**
+     * Resolve tool IDs from step text using natural language matching
+     */
+    static resolveSteps(steps) {
+        return steps.map(step => {
+            // Extract the command text (without Given/When/Then)
+            const commandText = step.text.toLowerCase();
+            // Try to find matching tool
+            const tools = ToolRegistry.searchTools(commandText);
+            if (tools.length > 0) {
+                // Use best match (first result)
+                const tool = tools[0];
+                // Extract parameters from step text
+                const params = this.extractParameters(step.text, tool.examples || []);
+                return {
+                    ...step,
+                    toolId: tool.toolId,
+                    params
+                };
+            }
+            return step;
+        });
+    }
+    /**
+     * Extract parameters from step text
+     */
+    static extractParameters(text, examples) {
+        const params = {};
+        // Look for quoted strings
+        const quotedMatch = text.match(/"([^"]+)"/g);
+        if (quotedMatch) {
+            params.value = quotedMatch[0].replace(/"/g, '');
+        }
+        // Look for numbers
+        const numberMatch = text.match(/\b\d+\b/);
+        if (numberMatch) {
+            params.count = parseInt(numberMatch[0]);
+        }
+        return params;
+    }
+    /**
+     * Convert Gherkin scenario to Story definition
+     *
+     * NOTE: Story system is part of @supernal/interface-enterprise
+     * This method is not available in the open source edition.
+     *
+     * For enterprise features including story system, visit:
+     * https://supernal.ai/enterprise
+     */
+    static scenarioToStory(scenario, featureName) {
+        throw new Error('Story system is part of @supernal/interface-enterprise. ' +
+            'Visit https://supernal.ai/enterprise for more information.');
+    }
+    /**
+     * Convert entire feature to stories and register them
+     *
+     * NOTE: Story system is part of @supernal/interface-enterprise
+     * This method is not available in the open source edition.
+     */
+    static featureToStories(feature) {
+        throw new Error('Story system is part of @supernal/interface-enterprise. ' +
+            'Visit https://supernal.ai/enterprise for more information.');
+    }
+    /**
+     * Generate unique story ID from feature and scenario names
+     */
+    static generateStoryId(featureName, scenarioName) {
+        const cleanFeature = featureName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+        const cleanScenario = scenarioName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+        return `${cleanFeature}-${cleanScenario}`;
+    }
+    /**
+     * Generate Gherkin steps from tools
+     * Moved from ToolPromptGenerator for consolidation
+     */
+    static generateSteps(tools) {
+        return tools
+            .map(tool => {
+            const examples = tool.examples || [tool.name.toLowerCase()];
+            return examples
+                .map((ex) => `    When I ${ex}`)
+                .join('\n');
+        })
+            .join('\n');
+    }
+    /**
+     * Generate complete Gherkin feature from tool metadata
+     * Consolidated from both ToolPromptGenerator and original generateFeature
+     */
+    static generateFeature(featureName, tools, options) {
+        let feature = '';
+        // Tags
+        if (options?.tags && options.tags.length > 0) {
+            feature += options.tags.map(t => `@${t}`).join(' ') + '\n';
+        }
+        // Feature header
+        feature += `Feature: ${featureName}\n`;
+        if (options?.description) {
+            feature += `  ${options.description}\n`;
+        }
+        feature += '\n  Scenario: AI navigation and interaction\n';
+        // Generate steps from tools
+        feature += this.generateSteps(tools);
+        return feature;
+    }
+    /**
+     * Generate Playwright test from Gherkin feature
+     */
+    static generatePlaywrightTest(feature) {
+        let test = `/**\n`;
+        test += ` * ${feature.name} - Generated from Gherkin\n`;
+        test += ` */\n\n`;
+        test += `import { test, expect } from '@playwright/test';\n`;
+        test += `import { StoryExecutor } from '@supernal-interface/core';\n\n`;
+        test += `test.describe('${feature.name}', () => {\n`;
+        for (const scenario of feature.scenarios) {
+            const storyId = this.generateStoryId(feature.name, scenario.name);
+            test += `  test('${scenario.name}', async ({ page }) => {\n`;
+            test += `    const executor = new StoryExecutor();\n`;
+            test += `    const context = { page };\n`;
+            test += `    \n`;
+            test += `    const result = await executor.executeStory('${storyId}', context);\n`;
+            test += `    \n`;
+            test += `    expect(result.success).toBe(true);\n`;
+            test += `  });\n\n`;
+        }
+        test += `});\n`;
+        return test;
+    }
+    /**
+     * Validate round-trip: Generate → Parse → Generate
+     * Ensures parsing and generation are consistent
+     */
+    static validateRoundTrip(tools, featureName = 'Test Feature') {
+        const errors = [];
+        // Generate original
+        const original = this.generateFeature(featureName, tools);
+        // Parse it
+        let parsed;
+        try {
+            parsed = this.parseFeature(original);
+        }
+        catch (error) {
+            return {
+                valid: false,
+                original,
+                parsed: { name: '', scenarios: [] },
+                regenerated: '',
+                errors: [`Parse error: ${error}`]
+            };
+        }
+        // Regenerate from parsed structure
+        const regenerated = this.generateFeature(parsed.name, tools, {
+            description: parsed.description,
+            tags: parsed.tags
+        });
+        // Compare (normalized)
+        const normalizeGherkin = (str) => str.trim().replace(/\s+/g, ' ').replace(/\n\s*/g, '\n');
+        const originalNorm = normalizeGherkin(original);
+        const regeneratedNorm = normalizeGherkin(regenerated);
+        if (originalNorm !== regeneratedNorm) {
+            errors.push('Round-trip failed: Generated text differs after parse');
+        }
+        // Validate structure
+        if (!parsed.name) {
+            errors.push('Parsed feature has no name');
+        }
+        if (parsed.scenarios.length === 0) {
+            errors.push('Parsed feature has no scenarios');
+        }
+        return {
+            valid: errors.length === 0,
+            original,
+            parsed,
+            regenerated,
+            errors
+        };
+    }
+}
+//# sourceMappingURL=GherkinParser.js.map

package/dist/esm/src/testing/GherkinParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GherkinParser.js","sourceRoot":"","sources":["../../../../src/testing/GherkinParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2CAA2C;AAC3C,wFAAwF;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAsBnE,MAAM,OAAO,aAAa;IACxB;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAe;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;QAE1F,IAAI,OAAO,GAA4B;YACrC,SAAS,EAAE,EAAE;SACd,CAAC;QAEF,IAAI,eAAe,GAAoC,IAAI,CAAC;QAC5D,IAAI,IAAI,GAAa,EAAE,CAAC;QAExB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,aAAa;YACb,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;gBAClD,SAAS;YACX,CAAC;YAED,gBAAgB;YAChB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACxC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACpB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;oBACpB,IAAI,GAAG,EAAE,CAAC;gBACZ,CAAC;gBACD,SAAS;YACX,CAAC;YAED,iBAAiB;YACjB,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;gBACjC,IAAI,eAAe,EAAE,CAAC;oBACpB,OAAO,CAAC,SAAU,CAAC,IAAI,CAAC,eAAkC,CAAC,CAAC;gBAC9D,CAAC;gBACD,eAAe,GAAG;oBAChB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;oBAC9B,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;oBACxC,KAAK,EAAE,EAAE;iBACV,CAAC;gBACF,IAAI,GAAG,EAAE,CAAC;gBACV,SAAS;YACX,CAAC;YAED,cAAc;YACd,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACnE,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;gBACjC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC;gBACpC,eAAe,CAAC,KAAM,CAAC,IAAI,CAAC;oBAC1B,OAAO,EAAE,OAAc;oBACvB,IAAI;iBACL,CAAC,CAAC;YACL,CAAC;YAED,0DAA0D;YAC1D,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBACpH,OAAO,CAAC,WAAW,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC;YACjE,CAAC;QACH,CAAC;QAED,oBAAoB;QACpB,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,CAAC,SAAU,CAAC,IAAI,CAAC,eAAkC,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,OAAyB,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,KAAoB;QACtC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;YACtB,qDAAqD;YACrD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAE5C,4BAA4B;YAC5B,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;YAEpD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,gCAAgC;gBAChC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAEtB,oCAAoC;gBACpC,MAAM,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;gBAEtE,OAAO;oBACL,GAAG,IAAI;oBACP,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,MAAM;iBACP,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,iBAAiB,CAAC,IAAY,EAAE,QAAkB;QAC/D,MAAM,MAAM,GAAwB,EAAE,CAAC;QAEvC,0BAA0B;QAC1B,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC7C,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,mBAAmB;QACnB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,QAAyB,EAAE,WAAmB;QACnE,MAAM,IAAI,KAAK,CACb,0DAA0D;YAC1D,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAuB;QAC7C,MAAM,IAAI,KAAK,CACb,0DAA0D;YAC1D,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,eAAe,CAAC,WAAmB,EAAE,YAAoB;QACtE,MAAM,YAAY,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QAC3E,MAAM,aAAa,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QAC7E,OAAO,GAAG,YAAY,IAAI,aAAa,EAAE,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,KAAY;QAC/B,OAAO,KAAK;aACT,GAAG,CAAC,IAAI,CAAC,EAAE;YACV,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YAC5D,OAAO,QAAQ;iBACZ,GAAG,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC;iBACvC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,eAAe,CACpB,WAAmB,EACnB,KAAY,EACZ,OAGC;QAED,IAAI,OAAO,GAAG,EAAE,CAAC;QAEjB,OAAO;QACP,IAAI,OAAO,EAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;QAC7D,CAAC;QAED,iBAAiB;QACjB,OAAO,IAAI,YAAY,WAAW,IAAI,CAAC;QAEvC,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;YACzB,OAAO,IAAI,KAAK,OAAO,CAAC,WAAW,IAAI,CAAC;QAC1C,CAAC;QAED,OAAO,IAAI,+CAA+C,CAAC;QAE3D,4BAA4B;QAC5B,OAAO,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAErC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,OAAuB;QACnD,IAAI,IAAI,GAAG,OAAO,CAAC;QACnB,IAAI,IAAI,MAAM,OAAO,CAAC,IAAI,6BAA6B,CAAC;QACxD,IAAI,IAAI,SAAS,CAAC;QAElB,IAAI,IAAI,oDAAoD,CAAC;QAC7D,IAAI,IAAI,+DAA+D,CAAC;QAExE,IAAI,IAAI,kBAAkB,OAAO,CAAC,IAAI,cAAc,CAAC;QAErD,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;YAElE,IAAI,IAAI,WAAW,QAAQ,CAAC,IAAI,4BAA4B,CAAC;YAC7D,IAAI,IAAI,6CAA6C,CAAC;YACtD,IAAI,IAAI,iCAAiC,CAAC;YAC1C,IAAI,IAAI,QAAQ,CAAC;YACjB,IAAI,IAAI,mDAAmD,OAAO,gBAAgB,CAAC;YACnF,IAAI,IAAI,QAAQ,CAAC;YACjB,IAAI,IAAI,0CAA0C,CAAC;YACnD,IAAI,IAAI,WAAW,CAAC;QACtB,CAAC;QAED,IAAI,IAAI,OAAO,CAAC;QAEhB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAY,EAAE,cAAsB,cAAc;QAOzE,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,oBAAoB;QACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAE1D,WAAW;QACX,IAAI,MAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,QAAQ;gBACR,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;gBACnC,WAAW,EAAE,EAAE;gBACf,MAAM,EAAE,CAAC,gBAAgB,KAAK,EAAE,CAAC;aAClC,CAAC;QACJ,CAAC;QAED,mCAAmC;QACnC,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;YAC3D,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC,CAAC;QAEH,uBAAuB;QACvB,MAAM,gBAAgB,GAAG,CAAC,GAAW,EAAE,EAAE,CACvC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAE1D,MAAM,YAAY,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,eAAe,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAEtD,IAAI,YAAY,KAAK,eAAe,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;QACvE,CAAC;QAED,qBAAqB;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACjD,CAAC;QAED,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;YAC1B,QAAQ;YACR,MAAM;YACN,WAAW;YACX,MAAM;SACP,CAAC;IACJ,CAAC;CACF"}

package/dist/esm/src/testing/PlaywrightStateHelpers.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Playwright Test Helpers for Browser State Injection
+ *
+ * Utilities for E2E tests to interact with component state
+ * using the browser state injection system.
+ *
+ * @module PlaywrightStateHelpers
+ */
+import { Page } from '@playwright/test';
+/**
+ * Set component state in the browser
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @param state - Partial state to merge
+ *
+ * @example
+ * ```typescript
+ * await setComponentState(page, 'counter', { count: 5 });
+ * ```
+ */
+export declare function setComponentState(page: Page, componentName: string, state: any): Promise<void>;
+/**
+ * Get component state from the browser
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @returns Current component state or undefined
+ *
+ * @example
+ * ```typescript
+ * const state = await getComponentState(page, 'counter');
+ * expect(state.count).toBe(5);
+ * ```
+ */
+export declare function getComponentState<TState = any>(page: Page, componentName: string): Promise<TState | undefined>;
+/**
+ * Reset component to initial state
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ *
+ * @example
+ * ```typescript
+ * await resetComponentState(page, 'counter');
+ * ```
+ */
+export declare function resetComponentState(page: Page, componentName: string): Promise<void>;
+/**
+ * Wait for component to be available in the DOM
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @param timeoutMs - Timeout in milliseconds (default: 5000)
+ *
+ * @example
+ * ```typescript
+ * await waitForComponent(page, 'counter');
+ * ```
+ */
+export declare function waitForComponent(page: Page, componentName: string, timeoutMs?: number): Promise<void>;
+/**
+ * Check if component is available
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @returns True if component is rendered and available
+ *
+ * @example
+ * ```typescript
+ * const isAvailable = await hasComponent(page, 'counter');
+ * ```
+ */
+export declare function hasComponent(page: Page, componentName: string): Promise<boolean>;
+/**
+ * Set component state from a data contract
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name
+ * @param dataContract - Data contract object (e.g., ExamplesData.counter.state.five)
+ *
+ * @example
+ * ```typescript
+ * import { ExamplesData } from '@supernal-interface/core';
+ *
+ * await setComponentStateFromContract(
+ *   page,
+ *   'counter',
+ *   ExamplesData.counter.state.five
+ * );
+ * ```
+ */
+export declare function setComponentStateFromContract(page: Page, componentName: string, dataContract: any): Promise<void>;
+/**
+ * Assert component state matches data contract
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name
+ * @param expectedContract - Expected data contract
+ *
+ * @example
+ * ```typescript
+ * await assertComponentStateMatches(
+ *   page,
+ *   'counter',
+ *   ExamplesData.counter.state.five
+ * );
+ * ```
+ */
+export declare function assertComponentStateMatches(page: Page, componentName: string, expectedContract: any): Promise<void>;
+/**
+ * Get component element by name
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name
+ * @returns Locator for the component element
+ *
+ * @example
+ * ```typescript
+ * const counter = getComponentElement(page, 'counter');
+ * await expect(counter).toBeVisible();
+ * ```
+ */
+export declare function getComponentElement(page: Page, componentName: string): import("playwright-core").Locator;
+/**
+ * Initialize test state manager in the browser
+ * Call this in beforeEach or at the start of tests
+ *
+ * @param page - Playwright page object
+ *
+ * @example
+ * ```typescript
+ * test.beforeEach(async ({ page }) => {
+ *   await initializeTestState(page);
+ * });
+ * ```
+ */
+export declare function initializeTestState(page: Page): Promise<void>;
+/**
+ * Batch state operations
+ * Useful for setting up complex test scenarios
+ *
+ * @param page - Playwright page object
+ * @param operations - Array of state operations
+ *
+ * @example
+ * ```typescript
+ * await batchStateOperations(page, [
+ *   { type: 'set', component: 'counter', state: { count: 5 } },
+ *   { type: 'set', component: 'chat', state: { messages: [] } },
+ *   { type: 'reset', component: 'form' },
+ * ]);
+ * ```
+ */
+export declare function batchStateOperations(page: Page, operations: Array<{
+    type: 'set';
+    component: string;
+    state: any;
+} | {
+    type: 'reset';
+    component: string;
+}>): Promise<void>;
+//# sourceMappingURL=PlaywrightStateHelpers.d.ts.map

package/dist/esm/src/testing/PlaywrightStateHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaywrightStateHelpers.d.ts","sourceRoot":"","sources":["../../../../src/testing/PlaywrightStateHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,GAAG,GACT,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAClD,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU7B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,GAAG,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,GAAG,GACpB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,qCAEpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,KAAK,CACb;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CACvC,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/esm/src/testing/PlaywrightStateHelpers.js

@@ -0,0 +1,242 @@
+/**
+ * Playwright Test Helpers for Browser State Injection
+ *
+ * Utilities for E2E tests to interact with component state
+ * using the browser state injection system.
+ *
+ * @module PlaywrightStateHelpers
+ */
+/**
+ * Set component state in the browser
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @param state - Partial state to merge
+ *
+ * @example
+ * ```typescript
+ * await setComponentState(page, 'counter', { count: 5 });
+ * ```
+ */
+export async function setComponentState(page, componentName, state) {
+    await page.evaluate(({ component, newState }) => {
+        if (!window.__testState__) {
+            throw new Error('Test state manager not initialized. Did you forget to call initializeTestStateManager()?');
+        }
+        window.__testState__.setState(component, newState);
+    }, { component: componentName, newState: state });
+}
+/**
+ * Get component state from the browser
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @returns Current component state or undefined
+ *
+ * @example
+ * ```typescript
+ * const state = await getComponentState(page, 'counter');
+ * expect(state.count).toBe(5);
+ * ```
+ */
+export async function getComponentState(page, componentName) {
+    return await page.evaluate((component) => {
+        if (!window.__testState__) {
+            throw new Error('Test state manager not initialized');
+        }
+        return window.__testState__.getState(component);
+    }, componentName);
+}
+/**
+ * Reset component to initial state
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ *
+ * @example
+ * ```typescript
+ * await resetComponentState(page, 'counter');
+ * ```
+ */
+export async function resetComponentState(page, componentName) {
+    await page.evaluate((component) => {
+        if (!window.__testState__) {
+            throw new Error('Test state manager not initialized');
+        }
+        window.__testState__.resetState(component);
+    }, componentName);
+}
+/**
+ * Wait for component to be available in the DOM
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @param timeoutMs - Timeout in milliseconds (default: 5000)
+ *
+ * @example
+ * ```typescript
+ * await waitForComponent(page, 'counter');
+ * ```
+ */
+export async function waitForComponent(page, componentName, timeoutMs = 5000) {
+    await page.evaluate(async ({ component, timeout }) => {
+        if (!window.__testState__) {
+            throw new Error('Test state manager not initialized');
+        }
+        await window.__testState__.waitForComponent(component, timeout);
+    }, { component: componentName, timeout: timeoutMs });
+}
+/**
+ * Check if component is available
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name from @Component decorator
+ * @returns True if component is rendered and available
+ *
+ * @example
+ * ```typescript
+ * const isAvailable = await hasComponent(page, 'counter');
+ * ```
+ */
+export async function hasComponent(page, componentName) {
+    return await page.evaluate((component) => {
+        if (!window.__testState__) {
+            return false;
+        }
+        return window.__testState__.hasComponent(component);
+    }, componentName);
+}
+/**
+ * Set component state from a data contract
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name
+ * @param dataContract - Data contract object (e.g., ExamplesData.counter.state.five)
+ *
+ * @example
+ * ```typescript
+ * import { ExamplesData } from '@supernal-interface/core';
+ *
+ * await setComponentStateFromContract(
+ *   page,
+ *   'counter',
+ *   ExamplesData.counter.state.five
+ * );
+ * ```
+ */
+export async function setComponentStateFromContract(page, componentName, dataContract) {
+    await setComponentState(page, componentName, dataContract);
+}
+/**
+ * Assert component state matches data contract
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name
+ * @param expectedContract - Expected data contract
+ *
+ * @example
+ * ```typescript
+ * await assertComponentStateMatches(
+ *   page,
+ *   'counter',
+ *   ExamplesData.counter.state.five
+ * );
+ * ```
+ */
+export async function assertComponentStateMatches(page, componentName, expectedContract) {
+    const actualState = await getComponentState(page, componentName);
+    if (!actualState) {
+        throw new Error(`Component '${componentName}' state is undefined`);
+    }
+    // Deep equality check
+    const actualJson = JSON.stringify(actualState);
+    const expectedJson = JSON.stringify(expectedContract);
+    if (actualJson !== expectedJson) {
+        throw new Error(`Component '${componentName}' state does not match.\n` +
+            `Expected: ${expectedJson}\n` +
+            `Actual: ${actualJson}`);
+    }
+}
+/**
+ * Get component element by name
+ *
+ * @param page - Playwright page object
+ * @param componentName - Component name
+ * @returns Locator for the component element
+ *
+ * @example
+ * ```typescript
+ * const counter = getComponentElement(page, 'counter');
+ * await expect(counter).toBeVisible();
+ * ```
+ */
+export function getComponentElement(page, componentName) {
+    return page.locator(`[data-component="${componentName}"]`);
+}
+/**
+ * Initialize test state manager in the browser
+ * Call this in beforeEach or at the start of tests
+ *
+ * @param page - Playwright page object
+ *
+ * @example
+ * ```typescript
+ * test.beforeEach(async ({ page }) => {
+ *   await initializeTestState(page);
+ * });
+ * ```
+ */
+export async function initializeTestState(page) {
+    await page.evaluate(() => {
+        // Force initialize test state manager regardless of NODE_ENV
+        if (typeof window !== 'undefined' && !window.__testState__) {
+            // Create a minimal test state manager
+            window.__testState__ = {
+                states: new Map(),
+                getState(component) {
+                    return this.states.get(component);
+                },
+                setState(component, state) {
+                    const current = this.states.get(component) || {};
+                    this.states.set(component, { ...current, ...state });
+                },
+                resetState(component) {
+                    this.states.delete(component);
+                }
+            };
+            console.log('[TEST] Test state manager initialized in browser');
+        }
+    });
+}
+/**
+ * Batch state operations
+ * Useful for setting up complex test scenarios
+ *
+ * @param page - Playwright page object
+ * @param operations - Array of state operations
+ *
+ * @example
+ * ```typescript
+ * await batchStateOperations(page, [
+ *   { type: 'set', component: 'counter', state: { count: 5 } },
+ *   { type: 'set', component: 'chat', state: { messages: [] } },
+ *   { type: 'reset', component: 'form' },
+ * ]);
+ * ```
+ */
+export async function batchStateOperations(page, operations) {
+    await page.evaluate((ops) => {
+        if (!window.__testState__) {
+            throw new Error('Test state manager not initialized');
+        }
+        for (const op of ops) {
+            if (op.type === 'set') {
+                window.__testState__.setState(op.component, op.state);
+            }
+            else if (op.type === 'reset') {
+                window.__testState__.resetState(op.component);
+            }
+        }
+    }, operations);
+}
+//# sourceMappingURL=PlaywrightStateHelpers.js.map

package/dist/esm/src/testing/PlaywrightStateHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaywrightStateHelpers.js","sourceRoot":"","sources":["../../../../src/testing/PlaywrightStateHelpers.ts"],"names":[],"mappings":"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"}