@sun-asterisk/sungen 2.1.0 → 2.2.0

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -0,0 +1,206 @@
+---
+name: sungen-selector-fix
+description: 'Selector generation and fixing strategy for make-test — explores live page, generates selectors.yaml, auto-fixes on test failure. Use this when generating selectors.yaml from a live page or fixing failing selectors.'
+user-invocable: false
+---
+
+## Selector Generation & Fix Strategy
+
+### When to Generate Selectors
+
+Selectors are generated during `/sungen:make-test`, NOT during `/sungen:make-tc`. This ensures selectors are always validated against the live page.
+
+---
+
+### Step 1: Authenticate
+
+1. Read `baseURL` from `playwright.config.ts`
+2. `browser_navigate` to `baseURL`
+3. If redirected to login, ask the user to log in manually:
+   > "This page requires login. Please log in using the browser. Confirm when you're done."
+4. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
+**Never use `browser_evaluate` to inject cookies or localStorage.** Use `browser_evaluate` only to read DOM info (e.g. detect `data-testid` attributes, check element properties).
+
+---
+
+### Step 2: Build an Element Catalog from the Snapshot
+
+**Never guess or infer selector names from Gherkin labels. Always copy exact values from the snapshot.**
+
+After taking the snapshot, mentally catalog ALL accessible elements:
+
+- **Buttons**: list each `button "..."` with its exact accessible name
+- **Links**: list each `link "..."` with its exact accessible name
+- **Headings**: list each `heading "..."` with level and exact name
+- **Inputs**: list each `textbox`, `searchbox`, `combobox` — note if it has an accessible name or not
+- **Regions/landmarks**: `region "..."`, `navigation "..."`, `dialog "..."`
+- **Images**: `img "..."` with accessible name (alt text)
+
+Then check for `data-testid` attributes (more stable than accessible names):
+```js
+// browser_evaluate — read-only, safe:
+Array.from(document.querySelectorAll('[data-testid]'))
+  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
+```
+
+---
+
+### Step 3: Map Gherkin Labels → Selectors
+
+For each `[Reference]` in the `.feature` file, find the best match in the element catalog.
+
+#### Selector priority (use first applicable)
+
+| Priority | type | When to use |
+|---|---|---|
+| 1 | `testid` | `data-testid` attribute exists |
+| 2 | `role` + exact name | Interactive elements (button, link, heading) |
+| 3 | `placeholder` | Input with visible placeholder text |
+| 4 | `label` | Form field with `<label>` association |
+| 5 | `locator` (CSS / aria attr) | No accessible name (e.g. bare searchbox, icon button) |
+| 6 | `text` | Static text only — avoid for dynamic/data-driven content |
+
+#### The exact name rule
+
+Copy the accessible name **character-for-character** from the snapshot. Do not transform, translate, or infer from the Gherkin label.
+
+```yaml
+# BAD — name inferred from Gherkin label, not from snapshot
+notification bell:
+  type: 'role'
+  value: 'button'
+  name: 'Notification Bell'
+
+# GOOD — exact name from snapshot: button "Notifications"
+notification bell:
+  type: 'role'
+  value: 'button'
+  name: 'Notifications'
+```
+
+#### When there is no accessible name
+
+Use a `locator` with a CSS attribute selector or ARIA role:
+
+```yaml
+search field:
+  type: 'locator'
+  value: '[role="searchbox"]'
+
+icon button:
+  type: 'locator'
+  value: '[aria-label="Close"]'
+```
+
+---
+
+### Step 4: Handle Dynamic Content
+
+For elements whose text changes between test runs (list items, card data, user-generated content, timestamps):
+
+**Never use `type: text` with a specific value** — it breaks when data changes.
+
+```yaml
+# BAD — specific text breaks when data changes
+card title:
+  type: 'text'
+  value: 'Some specific title'
+
+# GOOD — structural: first heading inside a card container
+card title:
+  type: 'role'
+  value: 'heading'
+  nth: 1    # skip page-level headings, get first card heading
+
+# BEST — if the app has data-testid
+card title:
+  type: 'testid'
+  value: 'card-title'
+```
+
+To determine the correct `nth` offset, count how many matching elements appear before the target in the snapshot (e.g. how many headings come before the first card heading).
+
+---
+
+### Step 5: Handle SPA / Client-side Routing
+
+Many modern apps (Next.js, Nuxt, SvelteKit, etc.) return the same HTML shell for all URLs and route client-side. `domcontentloaded` fires on the shell before the target page renders.
+
+**Symptom**: Tests see a different page than expected (e.g. home page instead of `/dashboard`).
+
+**Fix in the feature file**: Add an explicit assertion after navigation to confirm the correct page has loaded before proceeding:
+
+```gherkin
+Scenario: VP-UI-001 Some test
+  Given User is on [Dashboard] page
+  Then User see [Dashboard Title] heading is visible   ← confirms page loaded
+  When User click [Some Button] button
+  ...
+```
+
+The "page loaded" check should use a **stable, always-visible element** on that specific page — typically the main page heading.
+
+---
+
+### Step 6: Handle Multiple Matches (strict mode)
+
+When an element appears more than once (e.g. desktop + mobile nav, repeated list items), add `nth`:
+
+```yaml
+nav link:
+  type: 'role'
+  value: 'link'
+  name: 'Dashboard'
+  nth: 0    # first occurrence (desktop nav)
+```
+
+Use `nth: 0` for the first match of dynamic/repeated elements.
+
+---
+
+### Auto-Infer (skip YAML entry)
+
+Many elements don't need a YAML entry — sungen auto-infers from the Gherkin label:
+
+| Gherkin | Auto-inferred locator |
+|---|---|
+| `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
+| `[Home] link` | `getByRole('link', { name: 'Home' })` |
+| `[Welcome] heading` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Email] field` | `getByPlaceholder('Email')` |
+| `[Success] text` | `getByText('Success')` |
+
+**Only add a YAML entry when auto-infer won't work:**
+- The accessible name differs from the Gherkin label
+- Needs `nth` to disambiguate
+- Needs `testid` or CSS locator
+- Is dynamic content (needs structural selector)
+- Is a bare input with no label or placeholder
+
+---
+
+### Fix Loop on Test Failure
+
+```
+attempt = 0
+while attempt < 5:
+    compile → run test
+    if pass → done
+    read error-context.md in test-results/ → check exact snapshot state at failure time
+    fix selectors.yaml or test-data.yaml
+    recompile → attempt++
+if still failing → ask user about direct .spec.ts fix
+```
+
+**Always read the error context snapshot first** — it shows the exact page state when the test failed, which is more reliable than re-navigating with MCP.
+
+---
+
+### Key Rules (from sungen-selector-keys)
+
+- `[Reference]` → lowercase, keep Unicode: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
+- Keys use **spaces** (not dots) as word separators
+- Same label, different element types → add `--type` suffix
+- Same label, nth occurrence → add `--N` suffix

package/src/orchestrator/templates/ai-instructions/{copilot-skill-selector-keys.md → github-skill-sungen-selector-keys.md}

@@ -1,33 +1,31 @@
 ---
-description: 'Rules for generating correct YAML selector keys from Gherkin [Reference] names. Referenced by other sungen prompts when creating or fixing selectors.yaml files.'
-mode: 'agent'
-tools: []
+name: sungen-selector-keys
+description: 'Rules for generating correct YAML selector keys from Gherkin [Reference] names. Use this when creating or fixing selectors.yaml files with YAML key generation.'
+user-invocable: false
 ---
 
 ## Key Generation: `[Reference]` → YAML key
 
-Transform: Vietnamese/Japanese → ASCII → lowercase → remove special chars → spaces to dots.
+Copy the text from `[Reference]` as-is, then lowercase. Unicode characters (Vietnamese, Japanese, etc.) are preserved.
 
 ```
 [Submit]              → submit
-[Search Content]      → search.content
-[User's Profile]      → users.profile
-[Thời gian]           → thoi.gian
-[Địa điểm]            → dia.diem
-[ログイン]              → roguin
-[パスワード]            → pasuwaado
-[Page 2]              → page.2
-[Kudos Detail Modal]  → kudos.detail.modal
+[Search Content]      → search content
+[User's Profile]      → user's profile
+[Thời gian]           → thời gian
+[Địa điểm]            → địa điểm
+[ログイン]              → ログイン
+[パスワード]            → パスワード
+[Page 2]              → page 2
+[Kudos Detail Modal]  → kudos detail modal
 ```
 
 **Rules:**
-1. Remove Vietnamese diacritics: `ằắẳẵặ` → `a`, `đ` → `d`, etc.
-2. Convert Japanese Hiragana/Katakana to Romaji
-3. Lowercase everything
-4. `'s` → `s` (apostrophe-s becomes just s)
-5. Remove all special chars except spaces
-6. Trim, then spaces → dots
-7. **NEVER use spaces, underscores, or uppercase in YAML keys**
+1. Lowercase the text
+2. Trim leading/trailing whitespace
+3. Collapse multiple spaces into one
+4. **Keep all Unicode characters as-is** (Vietnamese diacritics, Japanese, etc.)
+5. **Keys use spaces** (not dots) as word separators
 
 ## Type-Suffixed Keys
 
@@ -35,12 +33,12 @@ When the same label is used for different element types, add `--type` suffix:
 
 ```yaml
 # [Add Campaign] button AND [Add Campaign] text
-add.campaign--button:
+add campaign--button:
   type: 'role'
   value: 'button'
   name: 'Add Campaign'
 
-add.campaign--text:
+add campaign--text:
   type: 'text'
   value: 'Add Campaign'
 ```
@@ -61,11 +59,11 @@ Type aliases (normalized automatically):
 When targeting a specific occurrence by index, add `--N` suffix:
 
 ```yaml
-# [Send Thank You] button 3
-hay.gui.loi.cam.on--3:
+# [Gửi lời cảm ơn] button 3
+gửi lời cảm ơn--3:
   type: 'role'
   value: 'button'
-  name: 'Send Thank You'
+  name: 'Gửi lời cảm ơn'
 ```
 
 ## Lookup Priority

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -0,0 +1,256 @@
+---
+name: sungen-tc-generation
+description: 'Exhaustive test case generation strategy — section-focused, 20+ scenarios per viewpoint per section, Gherkin + test-data only, no selectors. Use this when creating test cases for a screen with Gherkin scenarios.'
+user-invocable: false
+---
+
+## Test Case Generation Strategy
+
+### Goal
+
+Generate **focused, high-quality test cases per screen section** with **at least 20 scenarios per viewpoint category**. Output only `.feature` and `test-data.yaml` — selectors are deferred to `/sungen:make-test`.
+
+### Update Mode (existing test cases)
+
+When the `.feature` file already has scenarios, read it first and summarize what exists:
+
+> This screen already has **57 scenarios**:
+> - Section: Filters & Search — 22 scenarios (UI: 7, VAL: 8, LOGIC: 5, SEC: 2)
+> - Section: User Table — 23 scenarios (UI: 13, LOGIC: 11, SEC: 3)
+> - Section: Pagination — 12 scenarios (UI: 4, LOGIC: 6, SEC: 2)
+>
+> What would you like to do?
+> 1. **Add new sections** — keep existing, add tests for uncovered sections
+> 2. **Add viewpoints to existing sections** — e.g., more edge cases, more security tests
+> 3. **Replace all** — start fresh
+
+For options 1 and 2:
+- Read the existing scenarios to understand current coverage and the highest `VP-<CAT>-<NNN>` number
+- Continue numbering from the next available number (e.g., if last is `VP-UI-024`, start at `VP-UI-025`)
+- **Append** new scenarios to the end of the relevant section — never modify or delete existing scenarios
+- Merge new test-data variables into `test-data.yaml` without overwriting existing ones
+
+For option 3:
+- Overwrite both `.feature` and `test-data.yaml` completely
+
+### Page Exploration & Auth
+
+Use Playwright MCP to explore the live page. If the page requires authentication:
+1. `browser_navigate` to `baseURL` (from `playwright.config.ts`)
+2. If redirected to login, ask the user to log in manually:
+   > "This page requires login. Please log in using the browser. Confirm when you're done."
+3. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
+
+### Single Screen Focus
+
+**One screen = one URL path.** Only generate test cases for elements visible on the target page.
+
+- Navigate to the target screen path — do NOT explore sibling paths (e.g., testing `/admin/users` should not scan `/admin/review`)
+- Take ONE snapshot of the target page — do not click links to navigate away
+- If a link goes to a different path, test only that the link is visible and clickable — the destination page is a SEPARATE screen
+- If a modal/dialog opens on the same page, that IS part of this screen
+- Each screen gets its own `qa/screens/<name>/` directory — never mix screens
+
+#### Detail screens with dynamic IDs
+
+For screens like `/admin/users/:id` or `/products/:slug`:
+1. Navigate to the **list page** first via MCP browser to find a real record ID
+2. Use that ID in the page selector value
+3. Use `User is on [X] page` — sungen resolves the path from the selector
+
+```yaml
+# selectors.yaml — full path with real ID (generated during make-test)
+user detail:
+  type: 'page'
+  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
+```
+
+```gherkin
+Scenario: VP-UI-001 User detail displays name
+  Given User is on [User Detail] page
+  And User wait for [User Name] heading is visible
+  Then User see [User Name] heading with {{user_name}}
+```
+
+Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
+
+### Section-Focused Approach
+
+After exploring the page, identify distinct **sections** based on common UI patterns. Present them as a numbered list and ask the user which to focus on.
+
+#### Common Section Patterns
+
+Identify which patterns exist on the screen:
+
+| Pattern | Elements to look for |
+|---|---|
+| **Header / Navigation** | Logo, nav links, breadcrumbs, user menu, notifications, language selector |
+| **Form** | Input fields, dropdowns, checkboxes, radio buttons, date pickers, file uploads, submit/cancel buttons |
+| **Data Table** | Column headers, sortable columns, row data, row actions, bulk actions, column filters |
+| **Search & Filters** | Search input, filter dropdowns, clear/reset, active filter tags |
+| **Card Grid / List** | Cards with title/image/description, load more, infinite scroll |
+| **Pagination** | Previous/next buttons, page numbers, page size selector, total count |
+| **Tabs / Accordion** | Tab headers, tab panels, expand/collapse |
+| **Modal / Dialog** | Open trigger, close button, form inside modal, confirmation dialog |
+| **Sidebar** | Stats, quick actions, related links, mini widgets |
+| **File Upload** | Drop zone, file picker, progress bar, file list, delete |
+| **Rich Text Editor** | Toolbar, content area, formatting buttons, preview |
+| **Carousel / Slider** | Prev/next arrows, dots/indicators, auto-play, swipe |
+
+Example output:
+
+> This screen has the following sections:
+> 1. Header (logo, navigation tabs, user menu)
+> 2. Create Form (name, email, role dropdown, department, submit)
+> 3. User Table (columns: name, email, status, actions; sortable, filterable)
+> 4. Pagination (previous/next, page indicator)
+>
+> Which sections do you want to create test cases for? (e.g., "2, 3" or "all")
+
+For each selected section, generate **20+ scenarios per applicable viewpoint**. Skip viewpoint categories that don't apply.
+
+Present a test plan summary and wait for user confirmation before generating files.
+
+### Viewpoint Categories
+
+| VP Category | Description |
+|---|---|
+| **UI/UX** | Default appearance, element visibility, default states |
+| **Validation** | Input validation, error messages, edge cases |
+| **Logic** | Business logic, interactions, state changes |
+| **Security** | Auth guards, injection, permission checks |
+
+### Coverage Checklist per Section Pattern
+
+Apply the relevant checklist based on the section pattern:
+
+#### Form sections
+- **UI/UX**: All fields visible, labels correct, default values, placeholder text, required indicators
+- **Validation**: Empty submit, each required field empty, invalid format (email, phone, URL), min/max length, special chars, unicode, XSS, SQL injection, whitespace-only, boundary values
+- **Logic**: Successful submit, submit with all optional fields, edit existing record, cancel resets form, field dependencies (show/hide), auto-complete, date range validation
+- **Security**: CSRF protection, unauthorized submit, role-based field visibility, input sanitization
+
+#### Data Table sections
+- **UI/UX**: All columns visible, column headers, row data displays correctly, empty state, loading state, action buttons visible
+- **Validation**: N/A (read-only) or inline edit validation
+- **Logic**: Sort ascending/descending per sortable column, filter by each column, search within table, row action menu (edit/delete/view), bulk select, bulk action, row click navigation, column resize
+- **Security**: Cannot access other users' data, action permissions per role, data not exposed in DOM
+
+#### Search & Filter sections
+- **UI/UX**: Search field visible, filter buttons visible, clear button state
+- **Validation**: Empty search, special chars, SQL injection, XSS, very long text, unicode/emoji, whitespace, partial match, case insensitive
+- **Logic**: Apply single filter, combine multiple filters, clear single filter, clear all filters, search + filter combined, filter persists across pagination, no results state
+- **Security**: Injection via search, injection via filter params
+
+#### Pagination sections
+- **UI/UX**: Page indicator visible, previous disabled on page 1, next enabled
+- **Logic**: Next page, previous page, navigate to last page, boundary (first/last), page indicator updates, data refreshes on navigation
+- **Security**: Filters persist across pages, search persists, cannot access page beyond max
+
+#### Modal / Dialog sections
+- **UI/UX**: Modal opens, close button visible, overlay visible, form fields inside modal
+- **Validation**: Submit empty form in modal, field validation inside modal
+- **Logic**: Open modal, close with X, close with Escape, close with overlay click, submit success closes modal, submit error keeps modal open
+- **Security**: Cannot open unauthorized modals, CSRF on modal submit
+
+#### Card Grid / List sections
+- **UI/UX**: Cards display all expected fields (title, image, description, metadata), empty state, loading state
+- **Logic**: Click card navigates to detail, load more / infinite scroll, card action buttons (like, share, delete), responsive layout
+- **Security**: User-generated content sanitized, cannot access other users' cards
+
+#### Carousel / Slider sections
+- **UI/UX**: Arrows visible, indicators visible, current slide highlighted
+- **Logic**: Next slide, previous slide, wrap at end, auto-play, indicator click navigates, swipe gesture
+- **Security**: N/A
+
+#### Tabs / Accordion sections
+- **UI/UX**: All tabs visible, active tab highlighted, default tab selected
+- **Logic**: Switch tabs, content updates per tab, deep link to tab, accordion expand/collapse, only one accordion open at a time
+- **Security**: Tab content respects permissions
+
+### General Coverage Dimensions (aim for 20+ total per viewpoint)
+
+**Happy paths (3-5):** Standard flow, all optional fields, minimum required
+**Edge cases (5-8):** Empty, max length, special chars, unicode/CJK/emoji, whitespace, leading/trailing spaces, overflow
+**Boundary values (3-5):** At min/max limit, one above/below, zero/null
+**Negative cases (3-5):** Invalid format, missing required, wrong type, injection attempts
+**State transitions (2-4):** Before/after action, undo, cancel mid-flow
+**Combinatorial (2-4):** Multiple invalid fields, valid+invalid combos, different roles
+
+### SPA Wait-For Steps
+
+If the page is an SPA (Next.js, Nuxt, React Router, etc.), add a `wait for` step after navigation:
+
+```gherkin
+Given User is on [Screen] page
+And User wait for [Page Title] heading is visible
+```
+
+For scenarios needing dynamic data, add a second wait:
+
+```gherkin
+And User wait for [Data Element] button is visible
+```
+
+### Output Files
+
+**1. Feature file** — `qa/screens/<screen>/features/<screen>.feature`
+
+Group by section, then by viewpoint within each section:
+
+```gherkin
+@auth:role
+Feature: <Screen> Screen
+
+  # ============================================================
+  # Section: Create User Form
+  # ============================================================
+
+  # --- UI/UX (20+) ---
+
+  Scenario: VP-UI-001 Name field is visible
+    ...
+
+  # --- Validation (20+) ---
+
+  Scenario: VP-VAL-001 Submit with empty name
+    ...
+
+  # ============================================================
+  # Section: User Table
+  # ============================================================
+
+  # --- UI/UX (20+) ---
+
+  Scenario: VP-UI-025 Table displays all columns
+    ...
+```
+
+**Naming convention:** `VP-<CATEGORY>-<NNN>` prefix in Scenario name.
+
+**2. Test data file** — `qa/screens/<screen>/test-data/<screen>.yaml`
+
+Group variables by section:
+
+```yaml
+# ============================================================
+# Create User Form
+# ============================================================
+valid_name: 'John Doe'
+valid_email: 'john@example.com'
+empty_input: ''
+special_chars: '!@#$%^&*()'
+
+# ============================================================
+# User Table
+# ============================================================
+sort_column: 'Name'
+search_term: 'John'
+```
+
+### Do NOT Generate
+
+- `selectors.yaml` — this is created during `/sungen:make-test`
+- Playwright code — sungen compiles Gherkin to Playwright

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

@@ -20,7 +20,9 @@ export default defineConfig({
   /* Retry on CI only */
   retries: process.env.CI ? 2 : 0,
   /* Opt out of parallel tests on CI. */
-  workers: process.env.CI ? 1 : undefined,
+  workers: process.env.CI ? 1 : 2,
+  /* Global timeout per test */
+  timeout: 10_000,
   /* 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. */