@sun-asterisk/sungen 2.3.1 → 2.4.1

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-review.md

@@ -1,228 +0,0 @@
----
-name: sungen-gherkin-review
-description: 'Quality review checklist for Gherkin test cases — assertion quality rules, action-result coherence, and 9-point checklist. Auto-loaded during self-review step of make-tc.'
-user-invocable: false
----
-
-## Assertion Quality Rules
-
-**CRITICAL** — these rules prevent shallow, low-value test cases:
-
-1. **NEVER use `is visible`** — `User see [T] type` already asserts visibility. Writing `is visible` is redundant noise. Only use `is hidden` to assert something is NOT shown.
-2. **Group related assertions** — one scenario can have 3-7 `Then/And` steps. Don't waste a whole scenario on one element. Group elements that verify the same concern.
-3. **Assert content, not just existence** — verify values, text, states, not just "it's there". Every assertion should answer: what EXACTLY should the user see? Add `with {{value}}` or `is state` whenever the expected content/state is known.
-   - `User see [Title] heading with {{page_title}}` — verify text
-   - `User see [Email] field with {{default_email}}` — verify default value
-   - `User see [Submit] button is disabled` — verify state
-   - `User see [Error] message with {{error_text}}` — verify exact error
-4. **Don't assume element roles** — never guess the element type (`button`, `option`, `link`, etc.) based on the label or expected behavior. Developers create custom components that don't match standard HTML roles (e.g., a `<div>` styled as a button, a custom dropdown built from `<li>` elements). Always use the **live-page selector scan result** or the selector YAML to determine the correct type. If you haven't scanned the page and the type is uncertain, use a generic type (`text`) or mark the scenario `@manual` until selectors are confirmed.
-
-**Bad** (shallow — just checks existence):
-```gherkin
-Scenario: VP-UI-001 Email field is visible
-  Given User is on [Login] page
-  Then User see [Email] field is visible
-
-Scenario: VP-UI-002 Password field is visible
-  Given User is on [Login] page
-  Then User see [Password] field is visible
-```
-
-**Good** (rich — verifies content, states, groups related checks):
-```gherkin
-Scenario: VP-UI-001 Login form displays all fields with correct defaults
-  Given User is on [Login] page
-  Then User see [Login] heading with {{login_title}}
-  And User see [Email] field
-  And User see [Password] field
-  And User see [Remember me] checkbox is unchecked
-  And User see [Submit] button is enabled
-  And User see [Forgot password] link
-```
-
-## Action-Result Coherence Rules
-
-Every scenario with a `When` action **must** assert the *result* of that action in `Then` — not just re-assert something already visible.
-
-**Anti-patterns (WRONG):**
-```gherkin
-# BAD: click then assert the same element unchanged
-When User click [Select language] button
-Then User see [Select language] button
-
-# BAD: fill then assert unrelated page (fill doesn't navigate)
-When User fill [Search] field with {{term}}
-Then User see [Home] page
-
-# BAD: action with no meaningful result check
-When User click [Submit] button
-Then User see [Submit] button
-```
-
-**Correct patterns:**
-```gherkin
-# GOOD: click opens something new (dropdown, dialog, page)
-When User click [Select language] button
-Then User see [VN] button
-
-# GOOD: click changes state on the element itself
-When User click [Submit] button
-Then User see [Submit] button is disabled
-
-# GOOD: click navigates to different page
-When User click [Login] button
-Then User see [Dashboard] page
-
-# GOOD: fill triggers visible result (search results, validation)
-When User fill [Search] field with {{term}}
-Then User see [search result] text with {{result_name}}
-
-# GOOD: fill then submit, assert result of submission
-When User fill [Email] field with {{invalid_email}}
-And User click [Submit] button
-Then User see [email error] message with {{email_error_text}}
-
-# GOOD: click opens dialog
-When User click [Submit] button
-Then User see [Confirm] dialog
-
-# GOOD: visibility-only scenario has no When (just Given + Then)
-Given User is on [Login] page
-Then User see [Email] field
-```
-
-**Rules:**
-1. `When click [X]` → `Then` must assert either a **new element appears** (dialog, dropdown, page change, new content) or a **state change on `[X]` itself** (e.g., `is disabled`, `is checked`). Never assert `[X]` unchanged. Asserting something already visible before the click is a pre-existing state error — if the result is uncertain, mark `@manual`.
-2. `When fill [X] field` → `Then` must assert the **visible result of the input** (search results appear, validation message shows, dropdown filters). Do NOT just assert the field has the value — `see [X] field with {{v}}` after fill is a **weak test** (Playwright fill already guarantees the value is set). Only use field value assertion when the field transforms the input (e.g., auto-format phone number, currency mask).
-   - **Search fields need a wait step** — search inputs typically have debounce/delay before results appear. After filling a search field, add `User wait for {{search_delay}}` before asserting results. Without this, the assertion fires before results render and the test flakes.
-   ```gherkin
-   # GOOD: wait for debounce before asserting search results
-   When User fill [Search] field with {{term}}
-   And User wait for {{search_delay}}
-   Then User see [search result] text with {{result_name}}
-   ```
-3. If you only want to verify an element **exists/is visible** — use a UI/UX scenario with **no `When`** (just `Given` + `Then`)
-4. If the result of an action is **unknown or uncertain** (e.g., what appears after filling a search, what dialog opens after click), either **explore via MCP first** to see the actual result, or **mark the scenario `@manual`**. Never guess the result — wrong assertions cause test failures that waste fix cycles.
-5. Scenario **name must match the actual assertion**, not the action. "Fill searchbox shows search results" must assert search results — not field value.
-
-## Quality Review Checklist (9 checks, auto-fix on detection)
-
-After generating scenarios, review every scenario against these checks. **If an issue is detected, fix it immediately** — do not just flag it.
-
-### 1. Redundant scenarios
-
-**Problem:** Two scenarios test the same element with overlapping assertions.
-```gherkin
-# REDUNDANT: VP-UI-009 and VP-UI-010 both test CTA button
-Scenario: CTA button is visible      → Then see [cta] button
-Scenario: CTA button shows text      → Then see [cta] button with {{text}}
-```
-**Fix:** Keep only the stronger assertion (`with {{text}}` implies visibility). Remove the weaker one.
-
-### 2. Misclassified viewpoint
-
-**Problem:** A scenario classified in the wrong viewpoint category.
-
-**Classification rules:**
-- **UI/UX** = Given + Then asserting **static, always-the-same** defaults (layout, placeholder text, initial state on first-ever load)
-- **Logic** = Given + When + Then (action causes a result), OR Given + Then asserting **behavior-dependent state** (persisted values, dynamic content, conditional defaults)
-
-**Key distinction:** If the element's state depends on **previous user interaction, saved preferences, or business rules** — it's Logic even without a `When`, because it verifies behavior, not layout.
-
-```gherkin
-# UI/UX — static default, always the same for every user
-Given User is on [Settings] page
-Then User see [Language] dropdown with {{default_language}}
-
-# Logic — checkbox remembers last user choice (persisted state)
-Given User is on [Settings] page
-Then User see [Newsletter] checkbox is checked
-
-# Logic — empty state text depends on business rule (no data yet)
-Given User is on [Orders] page
-Then User see [empty state] text with {{no_orders_message}}
-```
-
-**Fix:** Check whether the asserted state is truly static (same for all users, all times) or depends on data/behavior. Move accordingly.
-
-### 3. Dynamic/data-dependent content
-
-**Problem:** Asserting content that depends on live data which may change.
-```gherkin
-# FRAGILE: "Attachment 1" only exists if first card has an attachment
-Scenario: Card shows attachment image
-  Then User see [Attachment 1] image
-```
-**Fix:** Mark as `@manual` with a comment explaining the data dependency.
-
-### 4. Duplicate across sections
-
-**Problem:** Security scenario has identical steps to a UI scenario.
-```gherkin
-# VP-UI-006 and VP-SEC-002 are identical
-Scenario: VP-UI-006 User profile button is visible
-Scenario: VP-SEC-002 Authenticated user sees profile button
-```
-**Fix:** Remove the duplicate. Security scenarios should test **auth boundaries** (e.g., `@no-auth` → redirect), not re-test visibility.
-
-### 5. "Enabled" state on always-enabled elements
-
-**Problem:** Testing `is enabled` on elements that have no disabled state in the application.
-```gherkin
-# BAD: this button is never disabled — the assertion adds no value
-Then User see [Home] button is enabled
-```
-**Fix:** Remove. Only assert `is enabled` or `is disabled` when the element **actually toggles** between states based on conditions (e.g., form validity, permissions).
-
-### 6. Exact match on dynamic counters/numbers
-
-**Problem:** Using exact match (`with {{value}}`) on data that changes (counters, totals, timestamps).
-```gherkin
-# FRAGILE: "+61 KUDOS" changes when new kudos are sent
-Then User see [kudos count] text with {{kudos_count}}
-```
-**Fix:** Use partial match (`text contains`) with a stable keyword:
-```gherkin
-Then User see [kudos count] text contains {{kudos_count_keyword}}
-```
-
-### 7. Current active page link
-
-**Problem:** Testing visibility of a nav link pointing to the current page.
-```gherkin
-# LOW VALUE: we are ON /kudos, Sun* Kudos link is always there
-Scenario: Nav link Sun Kudos is visible
-  Given User is on [kudos] page
-  Then User see [Sun* Kudos] link
-```
-**Fix:** Remove or replace with active state test.
-
-### 8. Test-data completeness
-
-**Problem:** Feature file references `{{variable}}` but the corresponding key is missing in `test-data.yaml`.
-```gherkin
-# Feature uses {{login_error}} but test-data.yaml has no "login_error" key
-When User fill [Email] field with {{invalid_email}}
-And User click [Submit] button
-Then User see [error] message with {{login_error}}
-```
-**Fix:** After generation, verify every `{{variable}}` in the `.feature` file has a matching entry in `test-data.yaml`. Add missing entries with realistic values. This is a **mandatory post-generation check** — missing test data causes compile failures.
-
-### 9. Negative/boundary coverage
-
-**Problem:** All scenarios are happy-path. No validation, error, or boundary cases exist.
-```gherkin
-# BAD: only tests successful login — what about invalid credentials?
-Scenario: VP-LOGIC-001 User logs in successfully
-  Given User is on [Login] page
-  When User fill [Email] field with {{valid_email}}
-  And User fill [Password] field with {{valid_password}}
-  And User click [Submit] button
-  Then User see [Dashboard] page
-```
-**Fix:** For every form/input section, ensure at least one scenario covers:
-- **Required field empty** → validation message appears
-- **Invalid format** (email, phone, etc.) → format error appears
-- **Boundary values** (max length, min value) → when relevant
-
-If specific error messages are unknown, mark validation scenarios `@manual` rather than omitting them entirely.