@sun-asterisk/sungen 2.0.0 → 2.0.2

package/src/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/src/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)