qa-skills 3.0.0

package/skills/qa-codeceptjs-writer/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: qa-codeceptjs-writer
+description: Generate CodeceptJS scenario-driven E2E and BDD tests for TypeScript with human-readable syntax, multi-backend support (Playwright/WebDriver/Puppeteer), and Gherkin integration.
+output_dir: tests/e2e
+---
+
+# QA CodeceptJS Writer
+
+## Purpose
+
+Write CodeceptJS BDD/scenario-driven E2E tests from test case specifications. Transform structured test cases into executable scenarios using human-readable syntax (`I.click`, `I.see`, `I.fillField`), multi-backend support, and optional Gherkin BDD integration.
+
+## Trigger Phrases
+
+- "Write CodeceptJS tests for [feature/flow]"
+- "Generate CodeceptJS E2E tests from test cases"
+- "Create CodeceptJS BDD scenarios for [flow]"
+- "Add CodeceptJS tests with Gherkin for [feature]"
+- "CodeceptJS scenario-driven tests for [page]"
+- "CodeceptJS data-driven tests for [scenario]"
+- "CodeceptJS Page Object for [page]"
+- "CodeceptJS tests with Playwright/WebDriver/Puppeteer backend"
+
+## Workflow
+
+1. **Read test cases** — From qa-testcase-from-docs, qa-manual-test-designer, qa-browser-data-collector
+2. **Generate scenarios** — Create `Feature`/`Scenario` blocks or `.feature` files
+3. **Add step definitions** — If BDD mode: implement Given/When/Then in step definition files
+4. **Configure helper** — Ensure `codecept.conf.ts` has correct helper (Playwright, WebDriver, Puppeteer)
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Scenario-driven syntax** | `I.click`, `I.see`, `I.fillField`, `I.grabTextFrom` — human-readable, framework-agnostic |
+| **Multi-backend** | Playwright, WebDriver, Puppeteer — switch via config without changing test code |
+| **BDD Gherkin** | `.feature` files + step definitions; Given/When/Then; Background, Examples, tables |
+| **Page Objects** | Encapsulate page logic; inject via `inject()` |
+| **Custom helpers** | Extend I with custom methods |
+| **Data-driven** | `Data().Scenario` for parameterized scenarios |
+| **within()** | Scope locators to a container element |
+
+## Test Types
+
+| Type | Scope | Approach |
+|------|-------|----------|
+| **Scenario** | E2E user flows | `Feature`/`Scenario` blocks; `I` actor |
+| **BDD Gherkin** | Business-readable acceptance | `.feature` files + step definitions |
+| **Data-driven** | Same flow, multiple data sets | `Data(table).Scenario` with `current` |
+
+## Key Patterns
+
+- **Structure:** `Feature('name')` / `Scenario('title', ({ I }) => { ... })`
+- **Navigation:** `I.amOnPage('/path')`
+- **Interactions:** `I.click('Submit')`, `I.fillField('Email', 'a@b.com')`, `I.selectOption('Country', 'US')`
+- **Assertions:** `I.see('Welcome')`, `I.seeElement('.user')`, `I.dontSee('Error')`
+- **Scoped locators:** `within('.modal', () => { I.click('OK'); })`
+- **Data-driven:** `Data(accounts).Scenario('Login', ({ I, current }) => { ... })`
+- **Debugging:** `pause()` — interactive console during execution
+- **Auth:** `autoLogin` plugin — login once, reuse session
+
+See `references/patterns.md` for full pattern reference.
+
+## BDD Mode (Gherkin)
+
+- **Feature files:** `features/*.feature` — human-readable scenarios
+- **Step definitions:** `step_definitions/steps.ts` — Given/When/Then implementations
+- **Init:** `npx codeceptjs gherkin:init`
+- **Snippets:** `npx codeceptjs gherkin:snippets` — generate stubs for undefined steps
+- **Run features only:** `npx codeceptjs run --features`
+
+See `references/patterns.md` for Gherkin patterns.
+
+## Configuration
+
+- **codecept.conf.ts** — helpers (Playwright/WebDriver/Puppeteer), plugins (autoLogin, allure), include (Page Objects), output
+- **Helper options** — url, browser, restart, video, trace, storageState
+
+See `references/config.md` for full configuration guide.
+
+## Context7 MCP
+
+Uses Context7 MCP to fetch CodeceptJS documentation when needed. Query for CodeceptJS API, helpers, or configuration when patterns are unclear.
+
+## Scope
+
+**Can do (autonomous):**
+- Generate CodeceptJS scenario and BDD tests from test case specs
+- Create Page Objects and inject them via `inject()`
+- Add `Data().Scenario` for data-driven tests
+- Configure `codecept.conf.ts` (helpers, plugins, include)
+- Use `within()` for scoped interactions
+- Add step definitions for Gherkin scenarios
+- Use autoLogin plugin for auth
+- Use Context7 MCP for CodeceptJS docs
+
+**Cannot do (requires confirmation):**
+- Change production code structure
+- Add dependencies not in package.json
+- Override project CodeceptJS config without approval
+- Switch helper (Playwright ↔ WebDriver) without user preference
+
+**Will not do (out of scope):**
+- Execute tests (user runs `npx codeceptjs run`)
+- Write Jest/Vitest unit tests (use qa-jest-writer)
+- Modify CI/CD pipelines
+- Bypass security or access restricted areas
+
+## References
+
+- `references/patterns.md` — Scenario syntax, BDD Gherkin, Page Objects, custom helpers, data-driven
+- `references/config.md` — codecept.conf.ts, helpers, plugins, output
+- `references/best-practices.md` — Readable scenarios, step granularity, helper selection
+
+## Quality Checklist
+
+- [ ] Human-readable steps; avoid raw CSS/XPath when semantic locators suffice
+- [ ] Page Objects for page-specific logic; inject via `inject()`
+- [ ] No hardcoded waits; use helper retry or explicit `I.waitForVisible`
+- [ ] Tests independent; no shared state between scenarios
+- [ ] BDD step definitions map to single, focused actions
+- [ ] Data-driven tests use `Data().Scenario` with `current`
+- [ ] Traceability to test case IDs where applicable
+- [ ] No hardcoded secrets (use env vars)
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Element not found | Locator too specific, dynamic content | Use semantic locators (text, label); add `data-test` with customLocator |
+| I is undefined | Wrong inject/context | Ensure `({ I }) =>` in Scenario; use `inject()` in step defs |
+| Step definition not matched | Regex/string mismatch | Run `gherkin:snippets`; check Cucumber expressions |
+| Backend-specific failure | Helper API differs | Playwright/WebDriver/Puppeteer have different methods; check helper docs |
+| autoLogin not working | Config or TypeScript | Ensure plugin enabled; check login function export |
+| Data().Scenario fails | current not passed | Use `({ I, current })`; access `current.columnName` |
+| within() scope wrong | Nested structure | Verify container selector; use strict locators `{ css: '...' }` |

package/skills/qa-codeceptjs-writer/references/best-practices.md

@@ -0,0 +1,207 @@
+# CodeceptJS Best Practices
+
+Guidelines for maintainable, readable CodeceptJS scenarios.
+
+## Readable Scenarios
+
+### Use Human-Readable Steps
+
+Prefer semantic, visible keywords over raw selectors:
+
+```typescript
+// GOOD: Readable, intent-focused
+Scenario('user logs in', ({ I }) => {
+  I.amOnPage('/login');
+  I.fillField('Username', 'john');
+  I.fillField('Password', 'secret');
+  I.click('Sign In');
+  I.see('Welcome');
+});
+
+// AVOID: Overly technical
+Scenario('user logs in', ({ I }) => {
+  I.amOnPage('/login');
+  I.fillField('#username', 'john');
+  I.fillField('input[type="password"]', 'secret');
+  I.click('.btn-primary');
+  I.seeElement('.welcome-msg');
+});
+```
+
+### Leverage Locator Resolution
+
+CodeceptJS resolves locators by label, link text, button text, then CSS/XPath. Use that:
+
+```typescript
+// Prefer label/button text when unique
+I.fillField('Email address', 'user@example.com');
+I.click('Submit');
+
+// Use data-test or data-qa with customLocator plugin for stability
+I.click({ custom: 'submit-btn' });
+```
+
+## Step Granularity
+
+### One Logical Action Per Step
+
+```typescript
+// GOOD: Clear, debuggable steps
+Scenario('checkout flow', ({ I }) => {
+  I.amOnPage('/cart');
+  I.click('Proceed to checkout');
+  I.fillField('Card number', '4111111111111111');
+  I.fillField('Expiry', '12/25');
+  I.click('Pay');
+  I.see('Order confirmed');
+});
+
+// AVOID: One giant step
+Scenario('checkout flow', ({ I }) => {
+  I.amOnPage('/cart');
+  I.click('Proceed to checkout');
+  I.fillField('Card number', '4111111111111111');
+  I.fillField('Expiry', '12/25');
+  I.click('Pay');
+  I.see('Order confirmed');
+  // All in one — hard to debug which step failed
+});
+```
+
+### Use Page Objects for Complex Flows
+
+```typescript
+// Extract repeated flows to Page Objects
+const { I, checkoutPage } = inject();
+
+Scenario('checkout', () => {
+  checkoutPage.addItem('Product A');
+  checkoutPage.proceedToPayment();
+  checkoutPage.payWithCard('4111111111111111', '12/25');
+  I.see('Order confirmed');
+});
+```
+
+## Helper Selection
+
+| Helper | When to Use |
+|--------|-------------|
+| **Playwright** | Modern apps, multi-browser, trace/video, auto-wait |
+| **WebDriver** | Selenium grid, cloud providers, legacy browsers |
+| **Puppeteer** | Chrome-only, lightweight, fast |
+
+Choose based on project constraints (browser support, CI, existing stack).
+
+## BDD Best Practices
+
+### Keep Feature Files Business-Focused
+
+```gherkin
+# GOOD: Business language
+Feature: Checkout
+  As a customer I want to checkout my cart
+
+  Scenario: apply discount
+    Given I have products totaling $50 in my cart
+    When I apply coupon "SAVE10"
+    Then my total should be $45
+```
+
+```gherkin
+# AVOID: Technical implementation details
+Feature: Checkout
+  Scenario: apply discount
+    Given I am on /cart
+    And I click .coupon-input
+    And I type SAVE10
+```
+
+### Use Background for Common Setup
+
+```gherkin
+Feature: Dashboard
+
+  Background:
+    Given I am logged in as administrator
+
+  Scenario: view reports
+    When I open reports page
+    Then I should see sales report
+```
+
+### Use Scenario Outline for Data Variations
+
+```gherkin
+  Scenario Outline: login with role
+    Given I am on login page
+    When I login as "<user>" with "<password>"
+    Then I should see "<welcome>" message
+    Examples:
+      | user   | password | welcome   |
+      | admin  | admin123 | Admin     |
+      | user   | user123  | User      |
+```
+
+## Data-Driven vs Gherkin
+
+| Approach | Use When |
+|----------|----------|
+| **Data().Scenario** | Same flow, different data; technical tests |
+| **Scenario Outline** | BDD; business examples; readable to stakeholders |
+
+## Stability and Flakiness
+
+| Practice | Description |
+|----------|-------------|
+| **Stable selectors** | Prefer label, `data-test`, `data-qa` over CSS |
+| **Avoid I.wait(ms)** | Use `I.waitForVisible`, `I.waitForElement` when needed |
+| **Isolation** | Each scenario independent; use `restart: 'context'` |
+| **No shared state** | Don't rely on order; use Background/login for setup |
+
+## Custom Helpers for Reuse
+
+Extract cross-cutting logic:
+
+```typescript
+// helpers/DbHelper.ts
+async haveUser(email: string) {
+  // Create user in DB
+  return { id, email };
+}
+
+// In test
+const { I, DbHelper } = inject();
+Scenario('test', async () => {
+  const user = await DbHelper.haveUser('test@example.com');
+  I.amOnPage(`/user/${user.id}`);
+});
+```
+
+## Debugging
+
+| Tool | Use |
+|------|-----|
+| `pause()` | Interactive console; inspect state, run I.* commands |
+| `--steps` | Step-by-step output in console |
+| `--debug` | Debug mode with detailed output |
+| `screenshotOnFail` | Auto-screenshot on failure |
+
+## File Organization
+
+```
+tests/
+  login_test.ts
+  checkout_test.ts
+features/
+  login.feature
+  checkout.feature
+step_definitions/
+  steps.ts
+  checkout_steps.ts
+pages/
+  LoginPage.ts
+  CheckoutPage.ts
+helpers/
+  MyHelper.ts
+output/           # Screenshots, videos, traces
+```

package/skills/qa-codeceptjs-writer/references/config.md

@@ -0,0 +1,255 @@
+# CodeceptJS Configuration Guide
+
+Configuration for `codecept.conf.ts` (or `.js`) and related setup.
+
+## Basic Structure
+
+```typescript
+// codecept.conf.ts
+import { Config } from 'codeceptjs';
+
+const config: Config = {
+  tests: './tests/**/*_test.ts',
+  output: './output',
+  helpers: {
+    Playwright: {
+      url: 'http://localhost:3000',
+      show: false,
+      browser: 'chromium',
+    },
+  },
+  include: {
+    I: './steps_file.ts',
+    loginPage: './pages/LoginPage.ts',
+  },
+  mocha: {},
+  bootstrap: null,
+  timeout: null,
+  teardown: null,
+  hooks: [],
+  gherkin: {
+    features: './features/**/*.feature',
+    steps: ['./step_definitions/steps.ts'],
+  },
+  plugins: {
+    screenshotOnFail: {
+      enabled: true,
+    },
+  },
+  stepTimeout: 0,
+  stepTimeoutOverride: [
+    {
+      pattern: 'wait.*',
+      timeout: 0,
+    },
+  ],
+  name: 'my-app',
+};
+
+export = config;
+```
+
+## Helpers
+
+### Playwright Helper
+
+```typescript
+helpers: {
+  Playwright: {
+    url: 'http://localhost:3000',
+    show: false,
+    browser: 'chromium', // or 'firefox', 'webkit'
+    restart: 'context',  // 'context' | 'session' | 'browser'
+    waitForNavigation: 'load',
+    waitForAction: 100,
+    timeout: 10000,
+    video: false,
+    trace: false,
+    keepVideoForPassedTests: false,
+    recordHar: false,
+    storageState: 'auth.json', // Reuse auth state
+  },
+},
+```
+
+| Option | Description | Values |
+|--------|-------------|--------|
+| `url` | Base URL | `'http://localhost:3000'` |
+| `browser` | Browser to use | `'chromium'`, `'firefox'`, `'webkit'` |
+| `restart` | Restart strategy | `'context'`, `'session'`, `'browser'` |
+| `video` | Record failed tests | `true` / `false` |
+| `trace` | Enable trace recording | `true` / `false` |
+| `storageState` | Auth state file | Path to JSON file |
+
+### WebDriver Helper
+
+```typescript
+helpers: {
+  WebDriver: {
+    url: 'http://localhost:3000',
+    browser: 'chrome',
+    host: 'localhost',
+    port: 4444,
+    restart: true,
+    smartWait: 5000,
+    waitForTimeout: 10000,
+    desiredCapabilities: {},
+  },
+},
+```
+
+### Puppeteer Helper
+
+```typescript
+helpers: {
+  Puppeteer: {
+    url: 'http://localhost:3000',
+    show: false,
+    restart: true,
+    waitForNavigation: 'networkidle0',
+    waitForAction: 100,
+    chrome: {
+      args: ['--no-sandbox'],
+    },
+  },
+},
+```
+
+## Include (Page Objects and Steps)
+
+```typescript
+include: {
+  I: './steps_file.ts',
+  loginPage: './pages/LoginPage.ts',
+  dashboardPage: './pages/DashboardPage.ts',
+},
+```
+
+- `I` — Custom steps file extending `I` object
+- Other keys — Page Objects or custom objects injected via `inject()`
+
+## Gherkin Configuration
+
+```typescript
+gherkin: {
+  features: './features/**/*.feature',
+  steps: [
+    './step_definitions/steps.ts',
+    './step_definitions/checkout_steps.ts',
+  ],
+  avoidDuplicateSteps: true,
+},
+```
+
+## Plugins
+
+### Built-in Plugins
+
+```typescript
+plugins: {
+  screenshotOnFail: {
+    enabled: true,
+    uniqueScreenshotNames: true,
+  },
+  retryFailedStep: {
+    enabled: true,
+    retries: 3,
+  },
+  tryTo: {
+    enabled: true,
+  },
+  retryTo: {
+    enabled: true,
+    retries: 3,
+  },
+  stepByStepReport: {
+    enabled: true,
+    output: './output',
+  },
+  autoLogin: {
+    enabled: true,
+    inject: 'login',
+    users: {
+      admin: {
+        login: (I) => {
+          I.amOnPage('/login');
+          I.fillField('Username', 'admin');
+          I.fillField('Password', 'admin123');
+          I.click('Sign In');
+        },
+        check: (I) => {
+          I.see('Dashboard');
+        },
+      },
+    },
+  },
+},
+```
+
+### autoLogin Plugin
+
+Eliminates repeated login steps in scenarios:
+
+```typescript
+// Enable in plugins
+autoLogin: {
+  enabled: true,
+  inject: 'login',
+  users: {
+    admin: {
+      login: (I) => {
+        I.amOnPage('/login');
+        I.fillField('Username', 'admin');
+        I.fillField('Password', 'admin123');
+        I.click('Sign In');
+      },
+      check: (I) => {
+        I.see('Dashboard');
+      },
+    },
+  },
+},
+
+// In test
+Scenario('admin flow', ({ I, login }) => {
+  login('admin');
+  I.amOnPage('/settings');
+  I.see('Settings');
+});
+```
+
+## Output and Reports
+
+| Option | Description |
+|--------|-------------|
+| `output` | Directory for screenshots, videos, traces |
+| `stepByStepReport` | Human-readable step output |
+| `mocha.reporter` | Mocha reporter (e.g., `'spec'`) |
+
+## Test Discovery
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `tests` | Glob for test files | `'./tests/**/*_test.ts'` |
+| `gherkin.features` | Glob for feature files | `'./features/**/*.feature'` |
+
+## Bootstrap and Teardown
+
+```typescript
+bootstrap: './bootstrap.ts',
+teardown: './teardown.ts',
+```
+
+## CLI Options
+
+| Command | Description |
+|---------|-------------|
+| `npx codeceptjs run` | Run all tests |
+| `npx codeceptjs run --steps` | Show step-by-step output |
+| `npx codeceptjs run --debug` | Debug mode |
+| `npx codeceptjs run --features` | Run only feature files |
+| `npx codeceptjs run --tests` | Run only JS/TS tests |
+| `npx codeceptjs run --grep "login"` | Run tests matching pattern |
+| `npx codeceptjs gherkin:init` | Initialize Gherkin |
+| `npx codeceptjs gherkin:snippets` | Generate step definition stubs |
+| `npx codeceptjs gherkin:steps` | List defined steps |