@sun-asterisk/sungen 2.0.0 → 2.0.1

package/dist/orchestrator/templates/ai-rules.md

@@ -0,0 +1,189 @@
+# Sungen AI Rules
+
+You generate 3 files for sungen — a Gherkin compiler that produces Playwright tests.
+**You do NOT write Playwright code.** You only write `.feature`, `selectors.yaml`, and `test-data.yaml`.
+
+## Complete Example
+
+Given a login page, here are the 3 files you generate:
+
+**qa/screens/login/features/login.feature**
+```gherkin
+@auth:admin
+Feature: Login Screen
+
+  Scenario: Successful login
+    Given User is on [login] page
+    When User fill [Email] field with {{email}}
+    And User fill [Password] field with {{password}}
+    And User click [Submit] button
+    Then User see [Welcome] heading with {{welcome_text}}
+    And User see [Dashboard] link is visible
+```
+
+**qa/screens/login/selectors/login.yaml**
+```yaml
+login:
+  type: 'page'
+  value: '/login'
+
+email:
+  type: 'placeholder'
+  value: 'Enter your email'
+
+password:
+  type: 'placeholder'
+  value: 'Enter your password'
+
+submit:
+  type: 'role'
+  value: 'button'
+  name: 'Submit'
+
+welcome:
+  type: 'role'
+  value: 'heading'
+  name: 'Welcome'
+
+dashboard:
+  type: 'role'
+  value: 'link'
+  name: 'Dashboard'
+```
+
+**qa/screens/login/test-data/login.yaml**
+```yaml
+email: 'admin@example.com'
+password: 'password123'
+welcome_text: 'Welcome back'
+```
+
+## Key Rules
+
+### YAML key format (CRITICAL)
+
+YAML keys = Gherkin `[Reference]` converted to: **lowercase, spaces→dots, no special chars**.
+
+| Gherkin | YAML Key |
+|---|---|
+| `[Submit]` | `submit:` |
+| `[Search Content]` | `search.content:` |
+| `[Kudos Detail Modal]` | `kudos.detail.modal:` |
+| `[Page 2]` | `page.2:` |
+
+**NEVER use spaces in YAML keys.**
+
+### Gherkin patterns (all 17)
+
+```
+User click [Target] button                              # click
+User fill [Target] field with {{value}}                  # fill
+User check [Target] checkbox                             # check/uncheck
+User select [Target] dropdown with {{value}}             # select
+User upload [Target] file with {{filename}}              # upload
+User double click [Target] element                       # double click
+User hover [Target] icon                                 # hover
+User clear [Target] field                                # clear
+User press Escape key                                    # global key
+User press Enter on [Target] field                       # key on element
+User is on [target] page                                 # navigate (Given)
+User see [target] page                                   # URL assertion (Then)
+User wait for 3 seconds                                  # wait timeout
+User wait for [Target] dialog is hidden                  # wait state
+User scroll to [Target] section                          # scroll
+User switch to [Target] frame                            # iframe
+User see [Target] heading with {{value}}                 # visible assertion
+User see [Target] button is disabled                     # state assertion
+User see [Target] text contains {{partial}}              # text contains
+User see [Table] table has row with {{filter}}           # table row
+User see [Table] table row with {{f}} has [Col] with {{v}} # table cell
+User click [Edit] in [Table] table row with {{name}}     # action in row
+```
+
+States: `hidden`, `visible`, `disabled`, `enabled`, `checked`, `unchecked`, `focused`, `empty`
+
+### Selector types
+
+| type | value | name | when to use |
+|---|---|---|---|
+| `role` | `button`, `heading`, `link`, etc. | accessible name | **preferred** for interactive elements |
+| `testid` | `data-testid` value | — | when `data-testid` exists |
+| `placeholder` | placeholder text | — | input fields |
+| `label` | label text | — | labeled inputs |
+| `text` | — | — | static text content |
+| `locator` | CSS selector | — | **last resort** |
+| `page` | relative URL path | — | navigation targets |
+| `upload` | — | — | file upload inputs |
+| `frame` | iframe selector | — | iframe targets |
+
+Priority: `testid` > `role+name` > `placeholder` > `label` > `text` > `locator`
+
+### Tags
+
+| Tag | Effect |
+|---|---|
+| `@auth:role` | Adds `test.use({ storageState: 'specs/.auth/role.json' })` |
+| `@steps:name` | Define reusable step group |
+| `@extend:name` | Inherit steps from another scenario |
+| `@manual` | Skip in generation |
+
+### Selector options
+
+```yaml
+element.key:
+  type: 'role'
+  value: 'button'
+  name: 'Submit'          # accessible name
+  nth: 0                  # element index (0=first)
+  exact: true             # exact name match (avoid substring collisions)
+  scope: 'navigation'     # parent landmark scope
+  match: 'exact'          # exact text match for getByText
+  variant: 'native'       # dropdown: 'native' (<select>) or 'custom' (div-based)
+  frame: '#iframe-id'     # iframe scope
+  contenteditable: true   # rich text editor
+  columns:                # table columns
+    name: { index: 0, header: 'Name' }
+```
+
+### Navigation and baseURL
+
+Page selectors use **relative paths only**. Playwright prepends `baseURL` from `playwright.config.ts`.
+
+```yaml
+login:
+  type: 'page'
+  value: '/login'       # NOT https://example.com/login
+```
+
+### Auth
+
+- `@auth:admin` on Feature or Scenario → compiler adds `test.use({ storageState: 'specs/.auth/admin.json' })`
+- Auth JSON created by: `sungen makeauth admin` (opens browser for manual login)
+- **Login pages**: no `@auth` tag needed
+- **Authenticated pages**: always add `@auth:role`
+
+## Using Playwright MCP to explore pages
+
+When exploring a page to generate test files:
+1. Read `playwright.config.ts` for `baseURL`
+2. Use `browser_navigate` to open `baseURL + /path`
+3. Use `browser_snapshot` to see all elements
+4. Generate the 3 files from the snapshot
+
+**NEVER use `browser_run_code`.** It fails with `require is not defined`.
+Only use: `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill_form`, `browser_evaluate`.
+
+To browse authenticated pages via MCP:
+1. Read `specs/.auth/role.json` with your file read tool
+2. `browser_navigate` to the page
+3. `browser_evaluate` to inject localStorage and cookies from the JSON
+4. `browser_navigate` again to reload with auth
+
+## Commands
+
+```bash
+sungen add --screen <name> --path <url-path>  # Create screen
+sungen generate --screen <name>                # Compile to .spec.ts
+sungen generate --all                          # Compile all
+sungen makeauth <role>                         # Capture auth state
+```

package/dist/orchestrator/templates/gitignore

@@ -0,0 +1,16 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo

package/dist/orchestrator/templates/playwright.config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+declare const _default: import("@playwright/test").PlaywrightTestConfig<{}, {}>;
+export default _default;
+//# sourceMappingURL=playwright.config.d.ts.map

package/dist/orchestrator/templates/playwright.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.config.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAKH;;GAEG;;AACH,wBAkEG"}

package/dist/orchestrator/templates/playwright.config.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+exports.default = (0, test_1.defineConfig)({
+    testDir: './specs/generated',
+    /* Run tests in files in parallel */
+    fullyParallel: true,
+    /* Fail the build on CI if you accidentally left test.only in the source code. */
+    forbidOnly: !!process.env.CI,
+    /* Retry on CI only */
+    retries: process.env.CI ? 2 : 0,
+    /* Opt out of parallel tests on CI. */
+    workers: process.env.CI ? 1 : undefined,
+    /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+    reporter: 'html',
+    /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+    use: {
+        /* Base URL to use in actions like `await page.goto('')`. */
+        baseURL: 'https://example.com',
+        /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+        trace: 'on-first-retry',
+    },
+    /* Configure projects for major browsers */
+    projects: [
+        {
+            name: 'chromium',
+            use: { ...test_1.devices['Desktop Chrome'] },
+        },
+        /*
+        // {
+        //   name: 'firefox',
+        //   use: { ...devices['Desktop Firefox'] },
+        // },
+    
+        // {
+        //   name: 'webkit',
+        //   use: { ...devices['Desktop Safari'] },
+        // },
+    
+        /* Test against mobile viewports.
+        // {
+        //   name: 'Mobile Chrome',
+        //   use: { ...devices['Pixel 5'] },
+        // },
+        // {
+        //   name: 'Mobile Safari',
+        //   use: { ...devices['iPhone 12'] },
+        // },
+    
+        /* Test against branded browsers. */
+        // {
+        //   name: 'Microsoft Edge',
+        //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+        // },
+        // {
+        //   name: 'Google Chrome',
+        //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+        // },
+    ],
+    /* Run your local dev server before starting the tests */
+    // webServer: {
+    //   command: 'npm run start',
+    //   url: 'http://localhost:3000',
+    //   reuseExistingServer: !process.env.CI,
+    // },
+});
+//# sourceMappingURL=playwright.config.js.map

package/dist/orchestrator/templates/playwright.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.config.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":";;AAAA,2CAAyD;AAEzD;;;GAGG;AACH,+BAA+B;AAC/B,2BAA2B;AAC3B,4DAA4D;AAE5D;;GAEG;AACH,kBAAe,IAAA,mBAAY,EAAC;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,oCAAoC;IACpC,aAAa,EAAE,IAAI;IACnB,iFAAiF;IACjF,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;IAC5B,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;IACvC,qEAAqE;IACrE,QAAQ,EAAE,MAAM;IAChB,wGAAwG;IACxG,GAAG,EAAE;QACH,4DAA4D;QAC5D,OAAO,EAAE,qBAAqB;QAE9B,+FAA+F;QAC/F,KAAK,EAAE,gBAAgB;KACxB;IAED,2CAA2C;IAC3C,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,EAAE,GAAG,cAAO,CAAC,gBAAgB,CAAC,EAAE;SACtC;QAED;;;;;;;;;;;;;;;;;;;;;4CAqBoC;QACpC,IAAI;QACJ,4BAA4B;QAC5B,4DAA4D;QAC5D,KAAK;QACL,IAAI;QACJ,2BAA2B;QAC3B,8DAA8D;QAC9D,KAAK;KACN;IAED,yDAAyD;IACzD,eAAe;IACf,8BAA8B;IAC9B,kCAAkC;IAClC,0CAA0C;IAC1C,KAAK;CACN,CAAC,CAAC"}

package/dist/orchestrator/templates/playwright.config.ts

@@ -0,0 +1,80 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: './specs/generated',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('')`. */
+    baseURL: 'https://example.com',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    /*
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+
+    /* Test against mobile viewports.
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  // webServer: {
+  //   command: 'npm run start',
+  //   url: 'http://localhost:3000',
+  //   reuseExistingServer: !process.env.CI,
+  // },
+});

package/dist/orchestrator/templates/readme.md

@@ -0,0 +1,197 @@
+# Sungen Test Automation
+
+This project uses [Sungen v2](https://github.com/sun-asterisk/sungen) — a deterministic E2E test compiler.
+
+## How it works
+
+```
+AI (Copilot/Claude + MCP Playwright) → visits URL → generates files
+sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
+```
+
+## Directory Structure
+
+```
+├── qa/screens/<name>/
+│   ├── features/         # .feature files (Gherkin)
+│   ├── selectors/        # Element locator YAML mappings
+│   └── test-data/        # Test data YAML values
+├── specs/
+│   ├── generated/        # Auto-generated Playwright tests
+│   └── .auth/            # Auth storage states
+├── docs/
+│   └── gherkin-dictionary.md  # Full grammar & compiler rules
+├── .github/
+│   └── copilot-instructions.md  # AI rules for GitHub Copilot
+└── CLAUDE.md                    # AI rules for Claude Code
+```
+
+## Workflow
+
+### 1. Add a screen
+
+```bash
+sungen add --screen login --path /login
+# Add more features to an existing screen:
+sungen add --screen login --feature forgot-password
+```
+
+### 2. Set up auth (if needed)
+
+```bash
+sungen makeauth admin
+# Opens browser → login manually → saves specs/.auth/admin.json
+```
+
+### 3. Generate Gherkin + selectors with AI
+
+Use your AI assistant (GitHub Copilot or Claude Code) to:
+1. Navigate to the page URL via MCP Playwright
+2. Take an accessibility snapshot
+3. Generate `.feature` + `selectors.yaml` + `test-data.yaml`
+
+The AI rules in `.github/copilot-instructions.md` and `CLAUDE.md` teach the AI
+how to write correct Gherkin syntax and selector YAML for sungen.
+
+### 4. Compile to Playwright tests
+
+```bash
+sungen generate --screen login
+# or for all screens:
+sungen generate --all
+```
+
+### 5. Run tests
+
+```bash
+npx playwright test
+npx playwright test --ui   # interactive mode
+```
+
+### 6. Fix failures (AI Verify loop)
+
+When tests fail, use AI to read the error → fix `selectors.yaml` → recompile → re-run.
+
+| Error | Fix in selectors.yaml |
+|---|---|
+| strict mode: resolved to N elements | Add `exact: true` or `scope` or `nth` |
+| element(s) not found | Fix `name`, `type`, or `value` |
+| getByText matched too many | Add `match: 'exact'` or `nth` |
+
+---
+
+## Gherkin Guide
+
+### Syntax
+
+```
+User <action> [<Target>] <type> with {{<Value>}}
+```
+
+- `[Target]` → selector reference → lookup in `selectors/*.yaml`
+- `{{Value}}` → test data reference → lookup in `test-data/*.yaml`
+- `<type>` → element type: button, link, field, heading, text, etc.
+
+### Pattern Shapes (17 total)
+
+#### Actions
+
+| Pattern | Example |
+|---|---|
+| Simple click | `User click [Submit] button` |
+| Click with data | `User click [Teammate] button with {{name}}` |
+| Fill field | `User fill [Email] field with {{email}}` |
+| Check/Uncheck | `User check [Remember me] checkbox` |
+| Select dropdown | `User select [Country] dropdown with {{country}}` |
+| Upload file | `User upload [Avatar] file with {{path}}` |
+| Double click | `User double click [Cell] element` |
+| Hover | `User hover [Info] icon` |
+| Clear | `User clear [Search] field` |
+
+#### Keyboard
+
+| Pattern | Example |
+|---|---|
+| Global key | `User press Escape key` |
+| Key on element | `User press Enter on [Search] field` |
+
+#### Navigation
+
+| Pattern | Example |
+|---|---|
+| Open page | `User is on [login] page` |
+| See page (URL) | `User see [dashboard] page` |
+
+#### Wait
+
+| Pattern | Example |
+|---|---|
+| Wait timeout | `User wait for 3 seconds` |
+| Wait element | `User wait for [Modal] dialog` |
+| Wait hidden | `User wait for [Loading] spinner is hidden` |
+| Wait with data | `User wait for [Dialog] dialog with {{title}}` |
+
+#### Assertions
+
+| Pattern | Example |
+|---|---|
+| See element | `User see [Welcome] heading` |
+| See with value | `User see [Title] heading with {{title}}` |
+| State check | `User see [Submit] button is disabled` |
+| State + data | `User see [Panel] dialog with {{title}} is hidden` |
+| Text contains | `User see [Message] text contains {{partial}}` |
+
+States: `hidden`, `visible`, `disabled`, `enabled`, `checked`, `unchecked`, `focused`, `empty`
+
+#### Table
+
+| Pattern | Example |
+|---|---|
+| Row exists | `User see [Users] table has row with {{name}}` |
+| No row | `User see [Users] table has no row with {{name}}` |
+| Row count | `User see [Users] table has {{count}} rows` |
+| Column exists | `User see [Users] table has [Email] column` |
+| Cell by filter | `User see [Users] table row with {{name}} has [Status] with {{status}}` |
+| Cell by index | `User see [Users] table row 1 [Name] cell with {{name}}` |
+| Action in row | `User click [Edit] in [Users] table row with {{name}}` |
+| Empty table | `User see [Users] table is empty` |
+
+#### Scope
+
+| Pattern | Example |
+|---|---|
+| Scroll | `User scroll to [Footer] section` |
+| Frame enter | `User switch to [Payment] frame` |
+| Frame exit | `User switch to [main] frame` |
+
+### Tags
+
+| Tag | Purpose |
+|---|---|
+| `@auth:role` | Use Playwright storage state for auth |
+| `@steps:name` | Define reusable step group |
+| `@extend:name` | Inherit steps from another scenario |
+| `@manual` | Skip scenario in generation |
+
+### Selector YAML
+
+```yaml
+submit.button:
+  type: 'role'              # testid, role, text, label, placeholder, locator, page
+  value: 'button'           # role name, testid value, CSS selector, etc.
+  name: 'Submit'            # accessible name
+  nth: 0                    # element index (0=first, 1=.nth(0), 2=.nth(1))
+  exact: true               # exact name match (avoid "Submit" matching "Submit Form")
+  scope: 'desktop navigation'  # scope to parent landmark
+  match: 'exact'            # exact text match for getByText
+```
+
+Locator priority: `data-testid` > `role+name` > `label` > `text` > `CSS`
+
+---
+
+## Documentation
+
+- [Gherkin Dictionary](docs/gherkin-dictionary.md) — full grammar, all 17 patterns, compiler rules
+- [Sungen GitHub](https://github.com/sun-asterisk/sungen)
+- [Playwright Documentation](https://playwright.dev)