@sun-asterisk/sungen 2.0.0 → 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,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -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/generators/test-generator/code-generator.ts

@@ -190,6 +190,17 @@ export class CodeGenerator {
       featureName = this.featureNameToFileName(feature.name).replace('.spec.ts', '');
     }
     
+    // Derive screen name from source file path when not explicitly set
+    // qa/screens/{screenName}/features/{featureName}.feature -> screenName
+    if (!this.screenName && feature.sourceFile) {
+      const sourceDir = path.dirname(feature.sourceFile);
+      const parts = sourceDir.split(path.sep);
+      const screensIndex = parts.indexOf('screens');
+      if (screensIndex >= 0 && screensIndex < parts.length - 2) {
+        this.stepMapper.setScreenContext(parts[screensIndex + 1]);
+      }
+    }
+
     // Set feature context for data resolution and navigation
     this.stepMapper.setFeatureContext(featureName, feature.path);
     

package/src/generators/test-generator/step-mapper.ts

@@ -57,6 +57,15 @@ export class StepMapper {
     this.selectorResolver.setFeatureContext(featureName);
   }
 
+  /**
+   * Update screen context (used in --all mode to set per-feature screen name)
+   */
+  setScreenContext(screenName: string): void {
+    this.screenName = screenName;
+    this.selectorResolver.setScreenContext(screenName);
+    this.dataResolver.setScreenContext(screenName);
+  }
+
   /**
    * Set scenario context for path variable resolution
    */