@sun-asterisk/sungen 1.0.24 → 2.0.1

package/docs/makeauth.md

@@ -0,0 +1,225 @@
+# sungen makeauth
+
+Generate authentication state for E2E tests with SSO (Single Sign-On) support.
+
+## Overview
+
+The `makeauth` command opens a browser window for manual login (including SSO providers like Google, Facebook, GitHub, etc.) and saves the authentication state to a JSON file. This storage state can then be used in Playwright tests to skip the login process.
+
+## Usage
+
+```bash
+sungen makeauth <name> [options]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `name` | Name for the auth state (e.g., `admin`, `user`, `guest`) |
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-u, --url <url>` | Base URL of the application | Auto-detect from `playwright.config.ts` |
+| `-p, --path <path>` | Login page path | `/login` |
+| `-o, --output <dir>` | Output directory for auth files | `specs/.auth` |
+| `-t, --timeout <ms>` | Overall timeout for login process | `180000` (3 minutes) |
+| `--nav-timeout <ms>` | Navigation timeout (page load) | `180000` (3 minutes) |
+| `--stability-wait <ms>` | URL stability wait before confirming login | `5000` (5 seconds) |
+| `--headless` | Run browser in headless mode | `false` |
+| `--verify` | Verify existing auth state is still valid | - |
+| `--list` | List all existing auth states | - |
+| `--export` | Export auth state as base64 (for CI) | - |
+
+### Timeout Configuration
+
+| Config | Default | Description |
+|--------|---------|-------------|
+| `timeout` | 180000 (3 min) | Overall timeout for the entire login process |
+| `nav-timeout` | 180000 (3 min) | Timeout for page navigation (page.goto) |
+| `stability-wait` | 5000 (5 sec) | Time URL must remain stable before confirming successful login |
+
+## Examples
+
+### Create auth state
+
+```bash
+# Basic usage - auto-detect URL from playwright.config.ts
+sungen makeauth admin
+
+# Specify URL explicitly
+sungen makeauth admin --url https://myapp.com
+
+# Custom login path
+sungen makeauth admin --url https://myapp.com --path /auth/signin
+
+# Longer timeout for slow SSO providers
+sungen makeauth admin --timeout 300000
+```
+
+### Manage auth states
+
+```bash
+# List all auth states
+sungen makeauth admin --list
+
+# Verify auth state is still valid
+sungen makeauth admin --verify
+
+# Export for CI (base64)
+sungen makeauth admin --export
+```
+
+## URL Detection Priority
+
+The command automatically detects the base URL in this order:
+
+1. `--url` flag (if provided)
+2. `playwright.config.ts` - reads `baseURL` from the config
+3. `APP_BASE_URL` environment variable
+4. Default: `http://localhost:3000`
+
+## Supported SSO Providers
+
+The tool automatically detects and displays the SSO provider being used:
+
+| Provider | Detection |
+|----------|-----------|
+| Google | accounts.google.com |
+| Facebook | facebook.com |
+| GitHub | github.com |
+| Microsoft/Azure AD | login.microsoftonline.com |
+| Apple | appleid.apple.com |
+| X (Twitter) | twitter.com, x.com |
+| LinkedIn | linkedin.com |
+| Okta | *.okta.com |
+| Auth0 | *.auth0.com |
+| GitLab | gitlab.com |
+| Atlassian | atlassian.com, bitbucket.org |
+| Slack | slack.com |
+| Discord | discord.com |
+| Amazon Cognito | amazoncognito.com |
+| Yahoo | yahoo.com |
+
+Any other SSO provider will show the domain name.
+
+## How It Works
+
+1. **Open Browser**: Launches Chromium browser and navigates to login page
+2. **Wait for SSO**: Detects when user clicks SSO button (redirect to external domain)
+3. **Wait for Callback**: Monitors for redirect back to application
+4. **Save State**: Stores cookies, localStorage, and sessionStorage to JSON file
+5. **Auto-close**: Browser closes automatically after successful login
+
+You can also press **ENTER** at any time to manually save the current state.
+
+## Output
+
+Auth states are saved to `specs/.auth/<name>.json`:
+
+```
+specs/
+  .auth/
+    admin.json
+    user.json
+    guest.json
+```
+
+## Using in Playwright Tests
+
+### Method 1: Global Setup (Recommended)
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'authenticated',
+      use: {
+        storageState: 'specs/.auth/admin.json',
+      },
+    },
+  ],
+});
+```
+
+### Method 2: Per-test Setup
+
+```typescript
+// my-test.spec.ts
+import { test } from '@playwright/test';
+
+test.use({ storageState: 'specs/.auth/admin.json' });
+
+test('authenticated test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // Already logged in!
+});
+```
+
+### Method 3: Multiple Roles
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'admin',
+      use: { storageState: 'specs/.auth/admin.json' },
+    },
+    {
+      name: 'user',
+      use: { storageState: 'specs/.auth/user.json' },
+    },
+  ],
+});
+```
+
+## CI/CD Integration
+
+### Option 1: Pre-generated Auth State
+
+1. Generate auth state locally:
+   ```bash
+   sungen makeauth admin
+   ```
+
+2. Export as base64:
+   ```bash
+   sungen makeauth admin --export
+   ```
+
+3. Save to CI secret (e.g., `AUTH_STATE_ADMIN`)
+
+4. In CI, decode and save:
+   ```bash
+   echo "$AUTH_STATE_ADMIN" | base64 -d > specs/.auth/admin.json
+   ```
+
+### Option 2: Service Account
+
+For automated CI without SSO:
+1. Create a service account with username/password login
+2. Use Playwright's built-in auth setup
+
+## Troubleshooting
+
+### Browser closes immediately
+- Make sure to click the SSO button before the browser closes
+- The tool waits for you to leave the base URL domain
+
+### Auth state expired
+- Run `sungen makeauth admin --verify` to check
+- Regenerate with `sungen makeauth admin`
+
+### Wrong URL detected
+- Check your `playwright.config.ts` has correct `baseURL`
+- Or specify explicitly: `--url https://your-app.com`
+
+### Timeout error
+- Increase timeout: `--timeout 300000` (5 minutes)
+- Or press ENTER to save manually at any time

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "1.0.24",
-  "description": "AI-Native E2E Test Generator - Generate Playwright tests from Gherkin features using AI",
+  "version": "2.0.1",
+  "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "build": "tsc && npm run copy-templates",
-    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true",
+    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/",
     "dev": "tsx src/cli/index.ts",
     "test": "echo \"Error: no test specified\" && exit 1",
     "prepublishOnly": "npm run build"
@@ -67,6 +67,7 @@
     "dist",
     "bin",
     "src",
+    "docs",
     "README.md",
     "LICENSE"
   ]

package/src/cli/commands/add.ts

@@ -3,9 +3,10 @@ import { Command } from 'commander';
 export function registerAddCommand(program: Command): void {
   program
     .command('add')
-    .description('Add screen definition with scaffolded files')
+    .description('Add screen or feature definition with scaffolded files')
     .requiredOption('--screen <name>', 'Screen name')
-    .option('-p, --path <path>', 'Screen route path')
+    .option('-p, --path <path>', 'Screen route path (e.g. /awards)')
+    .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
     .action(async (options) => {
       try {
@@ -15,10 +16,11 @@ export function registerAddCommand(program: Command): void {
         await manager.addScreen({
           name: options.screen,
           path: options.path,
+          feature: options.feature,
           description: options.description,
         });
       } catch (error) {
-        console.error('❌ Add screen failed:', error);
+        console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);
       }
     });

package/src/cli/commands/generate.ts

@@ -1,54 +1,106 @@
 import { Command } from 'commander';
-import { ConfigLoader } from '../../config/config-loader';
-import { Pipeline } from '../../orchestrator/pipeline';
-import { ValidationResult } from '../../core/validator';
-import { printValidationResult } from '../utils';
+import * as path from 'path';
+import * as fs from 'fs';
+import { CodeGenerator } from '../../generators/test-generator/code-generator';
+
+/**
+ * Find .feature files recursively in a directory
+ */
+function findFeatureFiles(dir: string): string[] {
+  const files: string[] = [];
+  if (!fs.existsSync(dir)) return files;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...findFeatureFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Find feature files for a specific screen
+ */
+function findFeatureFilesForScreen(screenName: string): string[] {
+  const screenFeaturesDir = path.join(process.cwd(), 'qa', 'screens', screenName, 'features');
+  return findFeatureFiles(screenFeaturesDir);
+}
+
+/**
+ * Find all feature files across all screens
+ */
+function findAllFeatureFiles(): string[] {
+  const allFiles: string[] = [];
+  const screensDir = path.join(process.cwd(), 'qa', 'screens');
+
+  if (fs.existsSync(screensDir)) {
+    const screenDirs = fs.readdirSync(screensDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name);
+
+    for (const screenName of screenDirs) {
+      const screenFeaturesDir = path.join(screensDir, screenName, 'features');
+      allFiles.push(...findFeatureFiles(screenFeaturesDir));
+    }
+  }
+
+  return allFiles;
+}
 
 export function registerGenerateCommand(program: Command): void {
   program
     .command('generate')
-    .description('Generate Playwright test code from features')
-    .option('--ai-mapper', 'Enable AI fallback for unknown Gherkin patterns')
-    .option('--framework <name>', 'Test framework (playwright, appium, integration)', 'playwright')
-    .option('-s, --screen <name>', 'Filter generation to specific screen')
-    .option('-f, --force', 'Force regeneration, bypass cache')
-    .option('--skip-validation', 'Skip validation before generation')
+    .description('Generate Playwright test code from Gherkin features')
+    .option('-s, --screen <name>', 'Generate tests for a specific screen')
+    .option('--all', 'Generate tests for all screens')
+    .option('--framework <name>', 'Test framework (default: playwright)', 'playwright')
     .action(async (options) => {
       try {
-        // Run validation first (unless --skip-validation is set)
-        if (!options.skipValidation) {
-          const { ScreenValidator } = require('../../core/validator');
-          const validator = new ScreenValidator();
-
-          let validationResult: ValidationResult;
-          if (options.screen) {
-            console.log(`🔍 Validating screen: ${options.screen}...\n`);
-            validationResult = validator.validateScreen(options.screen);
-          } else {
-            console.log('🔍 Validating all screens...\n');
-            validationResult = validator.validateAll();
-          }
+        const screenName = options.screen;
 
-          if (!validationResult.valid) {
-            printValidationResult(validationResult, false);
-            console.error('\n❌ Validation failed. Fix errors before generating tests.');
-            console.error('   Tip: Use --skip-validation to bypass validation (not recommended)');
-            process.exit(1);
+        // Find feature files
+        let featureFiles: string[];
+        if (screenName) {
+          featureFiles = findFeatureFilesForScreen(screenName);
+          if (featureFiles.length === 0) {
+            throw new Error(
+              `No feature files found for screen: ${screenName}\n` +
+              `Looked in: qa/screens/${screenName}/features/`
+            );
           }
-
-          console.log(`✅ Validation passed (${validationResult.summary.totalFiles} files)\n`);
+          console.log(`\nGenerating tests: ${screenName}\n`);
+        } else {
+          featureFiles = findAllFeatureFiles();
+          if (featureFiles.length === 0) {
+            throw new Error('No feature files found in qa/screens/');
+          }
+          console.log(`\nGenerating tests for all screens\n`);
         }
 
-        const cliOptions = {
-          ...program.opts(),
-          ...options,
-        };
-        const config = new ConfigLoader().load(cliOptions);
-        const pipeline = new Pipeline(config);
+        // Output directory
+        const outputDir = path.join(process.cwd(), 'specs', 'generated');
+
+        // Create generator and compile
+        const generator = new CodeGenerator({
+          framework: options.framework || 'playwright',
+          screenName,
+          verbose: program.opts().verbose,
+        });
+
+        const results = await generator.generateAllTests(
+          path.join(process.cwd(), 'qa', 'screens'),
+          outputDir,
+          featureFiles
+        );
 
-        await pipeline.runTestGeneration(options.screen);
+        console.log(`\n${results.length} test file(s) generated.`);
+        console.log(`Next step: npx playwright test --ui\n`);
       } catch (error) {
-        console.error('❌ Test generation failed:', error);
+        console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);
       }
     });

package/src/cli/index.ts

@@ -1,18 +1,13 @@
 #!/usr/bin/env node
 /**
- * Sungen CLI - AI-Native E2E Test Generator
- * Command-line interface for generating E2E tests from Gherkin features
+ * Sungen CLI v2 - Deterministic E2E Test Compiler
+ * Compiles Gherkin features + selector YAML + test data → Playwright tests
  */
 
 import { Command } from 'commander';
 import { registerInitCommand } from './commands/init';
 import { registerAddCommand } from './commands/add';
-import { registerLiveScanCommand } from './commands/live-scan';
-import { registerMapCommand } from './commands/map';
 import { registerGenerateCommand } from './commands/generate';
-import { registerFullCommand } from './commands/full';
-import { registerValidateCommand } from './commands/validate';
-import { registerCacheClearCommand } from './commands/cache-clear';
 import { registerMakeauthCommand } from './commands/makeauth';
 
 async function main() {
@@ -20,23 +15,17 @@ async function main() {
 
   program
     .name('sungen')
-    .description('AI-Native E2E Test Generator - Generate Playwright tests from Gherkin features')
-    .version('1.0.24');
+    .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
+    .version('2.0.0');
 
   // Global options
   program
-    .option('-c, --config <path>', 'Path to custom config file')
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register all commands
+  // Register commands (5 only)
   registerInitCommand(program);
   registerAddCommand(program);
-  registerLiveScanCommand(program);
-  registerMapCommand(program);
   registerGenerateCommand(program);
-  registerFullCommand(program);
-  registerValidateCommand(program);
-  registerCacheClearCommand(program);
   registerMakeauthCommand(program);
 
   await program.parseAsync(process.argv);

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/frame-enter-action.hbs

@@ -0,0 +1 @@
+const frame = page.frameLocator('{{value}}');

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/frame-exit-action.hbs

@@ -0,0 +1 @@
+// Back to main page context

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/keyboard-global-action.hbs

@@ -0,0 +1 @@
+await page.keyboard.press('{{key}}');

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/scroll-action.hbs

@@ -0,0 +1 @@
+await {{> locator}}.scrollIntoViewIfNeeded();

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/table-action-in-row.hbs

@@ -0,0 +1,2 @@
+const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
+await tableRow.getByRole('button', { name: '{{escapeQuotes elementName}}' }).{{action}}();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-cell-by-filter.hbs

@@ -0,0 +1,3 @@
+await page.waitForLoadState('networkidle');
+const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
+await expect(tableRow.getByRole('cell').filter({ hasText: '{{escapeQuotes cellValue}}' })).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-cell-by-index.hbs

@@ -0,0 +1,3 @@
+await page.waitForLoadState('networkidle');
+const tableRow = {{> locator}}.getByRole('row').nth({{rowIndex}});
+await expect(tableRow.getByRole('cell').filter({ hasText: '{{escapeQuotes cellValue}}' })).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-column-exists.hbs

@@ -0,0 +1,2 @@
+await page.waitForLoadState('networkidle');
+await expect({{> locator}}.getByRole('columnheader', { name: '{{escapeQuotes columnName}}' })).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-empty.hbs

@@ -0,0 +1,2 @@
+await page.waitForLoadState('networkidle');
+await expect({{> locator}}.locator('tbody').getByRole('row')).toHaveCount(0);

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-count.hbs

@@ -0,0 +1,2 @@
+await page.waitForLoadState('networkidle');
+await expect({{> locator}}.locator('tbody').getByRole('row')).toHaveCount({{expectedCount}});

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-exists.hbs

@@ -0,0 +1,2 @@
+await page.waitForLoadState('networkidle');
+await expect({{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' })).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-not-exists.hbs

@@ -0,0 +1,2 @@
+await page.waitForLoadState('networkidle');
+await expect({{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' })).toHaveCount(0);

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-with-value-assertion.hbs

@@ -1,2 +1,2 @@
 await page.waitForLoadState('networkidle');
-await expect(page.getByText('{{escapeQuotes value}}').filter({ hasText: /^{{escapeRegex dataValue}}$/ })).toBeVisible();
+await expect(page.getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{#if (gt nth 0)}}.nth({{subtract nth 1}}){{/if}}).toBeVisible();

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator-base.hbs

@@ -1,4 +1,13 @@
-{{#switch strategy~}}
+{{#if scope}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{#switch strategy~}}
+  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
+  {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{value}}'){{/case~}}
+  {{~#default}}locator('{{value}}'){{/default~}}
+{{~/switch}}{{else}}{{#switch strategy~}}
   {{~#case 'testid'}}{{> locator-strategies/testid}}{{/case~}}
   {{~#case 'role'}}{{> locator-strategies/role}}{{/case~}}
   {{~#case 'placeholder'}}{{> locator-strategies/placeholder}}{{/case~}}
@@ -7,4 +16,4 @@
   {{~#case 'locator'}}{{> locator-strategies/locator}}{{/case~}}
   {{~#case 'id'}}{{> locator-strategies/id}}{{/case~}}
   {{~#default}}{{> locator-strategies/default}}{{/default~}}
-{{~/switch}}
+{{~/switch}}{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/locator.hbs

@@ -1,4 +1,13 @@
-{{#switch strategy~}}
+{{#if scope}}{{pageRoot}}.getByLabel('{{escapeQuotes scope}}').{{#switch strategy~}}
+  {{~#case 'testid'}}getByTestId('{{value}}'){{/case~}}
+  {{~#case 'role'}}{{#if name}}getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{else}}getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}){{/if}}{{/case~}}
+  {{~#case 'placeholder'}}getByPlaceholder('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'label'}}getByLabel('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'text'}}getByText('{{escapeQuotes value}}'{{#if exact}}, { exact: true }{{/if}}){{/case~}}
+  {{~#case 'locator'}}locator('{{value}}'){{/case~}}
+  {{~#case 'id'}}locator('{{value}}'){{/case~}}
+  {{~#default}}locator('{{value}}'){{/default~}}
+{{~/switch}}{{> locator-nth}}{{else}}{{#switch strategy~}}
   {{~#case 'testid'}}{{> locator-strategies/testid}}{{/case~}}
   {{~#case 'role'}}{{> locator-strategies/role}}{{/case~}}
   {{~#case 'placeholder'}}{{> locator-strategies/placeholder}}{{/case~}}
@@ -7,4 +16,4 @@
   {{~#case 'locator'}}{{> locator-strategies/locator}}{{/case~}}
   {{~#case 'id'}}{{> locator-strategies/id}}{{/case~}}
   {{~#default}}{{> locator-strategies/default}}{{/default~}}
-{{~/switch}}{{> locator-nth}}
+{{~/switch}}{{> locator-nth}}{{/if}}