qa-skills 3.0.0

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

@@ -0,0 +1,62 @@
+# Vitest Best Practices
+
+## Test Structure
+
+1. **One assertion focus per test** — Prefer narrow tests; use multiple `it` blocks instead of one test with many assertions when behaviors differ.
+2. **Descriptive names** — Test names should read like specs: `it('returns 404 when user not found', ...)`.
+3. **Arrange-Act-Assert** — Structure tests: setup → call code under test → assert.
+
+## Mocking
+
+1. **Prefer vi.spyOn when possible** — More type-safe and flexible than full module replacement.
+2. **Use vi.hoisted for ESM** — When `vi.mock` factory needs variables, define them with `vi.hoisted()`.
+3. **Reset mocks between tests** — Use `beforeEach(() => vi.clearAllMocks())` to avoid cross-test pollution.
+4. **Mock at the boundary** — Mock external services (HTTP, DB), not internal implementation details.
+
+## Isolation
+
+1. **No shared mutable state** — Each test should be independent; use `beforeEach` for fresh state.
+2. **Concurrent tests** — Use `it.concurrent` only when tests have no shared state.
+3. **Clean up** — Restore spies, clear timers, reset env in `afterEach` when needed.
+
+## Assertions
+
+1. **Prefer specific assertions** — Use `toBe(5)` over `toBeTruthy()` when the value matters.
+2. **Use toStrictEqual for objects** — Catches `undefined` vs missing key differences.
+3. **Avoid snapshot overuse** — Use for stable, structured output; avoid for frequently changing UI.
+
+## Performance
+
+1. **Exclude unnecessary files** — Ensure `node_modules`, `dist`, and non-test paths are excluded.
+2. **Use workspace for monorepos** — Split projects to parallelize and scope config.
+3. **Mock heavy dependencies** — Don't load real DBs, external APIs, or large libs in unit tests.
+
+## Migration from Jest
+
+### API Mapping
+
+| Jest | Vitest |
+| ---- | ------ |
+| `jest.mock()` | `vi.mock()` |
+| `jest.fn()` | `vi.fn()` |
+| `jest.spyOn()` | `vi.spyOn()` |
+| `jest.useFakeTimers()` | `vi.useFakeTimers()` |
+| `jest.runAllTimers()` | `vi.runAllTimers()` |
+| `jest.setSystemTime()` | `vi.setSystemTime()` |
+| `jest.resetModules()` | `vi.resetModules()` |
+
+### Key Differences
+
+1. **ESM by default** — Vitest is ESM-native; use `import`/`export`. For `vi.mock` factory variables, use `vi.hoisted()`.
+2. **Config** — Vitest uses `vitest.config.ts` or `vite.config.ts` with a `test` block, not `jest.config.js`.
+3. **Globals** — Enable `globals: true` for `describe`, `it`, `expect`, `vi` without imports.
+4. **Coverage** — Use `@vitest/coverage-v8` or `@vitest/coverage-istanbul`; configure under `test.coverage`.
+
+### Migration Steps
+
+1. Install Vitest: `npm i -D vitest`
+2. Add `vitest.config.ts` (or `test` block to `vite.config.ts`)
+3. Replace `jest` with `vi` in test files
+4. Update `package.json` scripts: `"test": "vitest"`
+5. Fix ESM issues: add `vi.hoisted()` where `vi.mock` needs variables
+6. Run tests and fix any environment or config differences

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

@@ -0,0 +1,127 @@
+# Vitest Configuration
+
+## Basic vitest.config.ts
+
+```ts
+import { defineConfig } from 'vitest/config'
+import tsconfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{ts,tsx}', 'tests/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules', 'dist'],
+  },
+})
+```
+
+## Vite Config Integration
+
+When using Vite for the app, add a `test` block to `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./tests/setup.ts'],
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+  },
+})
+```
+
+## Environment
+
+| Value | Use Case |
+| ----- | -------- |
+| `node` | Node.js APIs, backend, CLI |
+| `jsdom` | DOM APIs, React, Vue (browser-like) |
+| `happy-dom` | Lighter DOM alternative |
+| `edge-runtime` | Edge workers |
+| Custom | Path to custom env file |
+
+## Coverage
+
+### v8 (recommended)
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.spec.ts'],
+    },
+  },
+})
+```
+
+Install: `npm i -D @vitest/coverage-v8`
+
+### Istanbul
+
+```ts
+coverage: {
+  provider: 'istanbul',
+  reporter: ['text', 'lcov', 'html'],
+}
+```
+
+Install: `npm i -D @vitest/coverage-istanbul`
+
+## Workspace (Monorepo)
+
+```ts
+// vitest.workspace.ts
+import { defineWorkspace } from 'vitest/config'
+
+export default defineWorkspace([
+  'packages/core',
+  'packages/utils',
+  'apps/web',
+])
+```
+
+Each workspace project can define its own `vitest.config.ts` or `vite.config.ts`.
+
+## Setup Files
+
+Run code before all tests:
+
+```ts
+test: {
+  setupFiles: ['./tests/setup.ts'],
+  globalSetup: './tests/globalSetup.ts',
+}
+```
+
+- `setupFiles`: Runs in each test environment (e.g., per worker)
+- `globalSetup`: Runs once before all tests
+
+## Plugins
+
+Common plugins:
+
+- `vite-tsconfig-paths` — Resolve `@/` and tsconfig paths
+- `@vitest/coverage-v8` — Coverage
+- `@vitest/ui` — Browser UI for test runs
+
+## Common Options
+
+| Option | Description |
+| ------ | ----------- |
+| `globals` | Expose `describe`, `it`, `expect`, `vi` globally |
+| `unstubEnvs` | Reset `vi.stubEnv` between tests |
+| `unstubGlobals` | Reset `vi.stubGlobal` between tests |
+| `pool` | `threads` (default) or `forks` |
+| `poolMatchGlobs` | Limit which files run in which pool |
+| `testTimeout` | Default timeout per test (ms) |
+| `hookTimeout` | Timeout for before/after hooks (ms) |

package/skills/qa-vitest-writer/references/patterns.md

@@ -0,0 +1,141 @@
+# Vitest Test Patterns
+
+## ESM Mocking
+
+### vi.mock() Hoisting
+
+`vi.mock()` is **hoisted** to the top of the file and runs before all imports. Variables used in the factory must be defined via `vi.hoisted()`:
+
+```ts
+import { vi } from 'vitest'
+
+const mockFn = vi.hoisted(() => vi.fn())
+
+vi.mock('./my-module', () => ({
+  myFunction: mockFn,
+}))
+```
+
+### vi.spyOn vs vi.mock
+
+| Use Case | Prefer | Reason |
+| -------- | ------ | ------ |
+| Replace entire module | `vi.mock()` | Full substitution |
+| Spy on single export | `vi.spyOn(exports, 'name')` | Type-safe, flexible |
+| Partial mock (keep some exports) | `vi.mock` with `importOriginal` | Merge original + overrides |
+| Browser mode | `vi.mock` (vi.spyOn has limitations) | See Vitest browser docs |
+
+### Partial Module Mock
+
+```ts
+vi.mock('./some-path.js', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('./some-path.js')>()
+  return {
+    ...mod,
+    mockedExport: vi.fn(),
+  }
+})
+```
+
+## In-Source Testing
+
+### Layout Options
+
+| Layout | Path | Use Case |
+| ------ | ---- | -------- |
+| Colocated | `src/utils/__tests__/format.test.ts` | Unit tests next to source |
+| Suffix | `src/utils/format.test.ts` | Same directory, suffix |
+| Separate | `tests/unit/utils/format.test.ts` | Centralized test dir |
+
+### Config for In-Source
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    include: ['src/**/*.{test,spec}.{ts,tsx}', 'tests/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules', 'dist'],
+  },
+})
+```
+
+## Concurrent Tests
+
+Run tests in parallel within a file:
+
+```ts
+it.concurrent('test 1', async () => { /* ... */ })
+it.concurrent('test 2', async () => { /* ... */ })
+
+// Or with test.each
+it.concurrent.each([
+  [1, 2, 3],
+  [4, 5, 9],
+])('adds %i + %i = %i', async (a, b, expected) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+**Caveats:** Avoid shared mutable state; each concurrent test should be independent.
+
+## Workspace Testing (Monorepos)
+
+Use `vitest.workspace.ts` to define multiple projects:
+
+```ts
+// vitest.workspace.ts
+import { defineWorkspace } from 'vitest/config'
+
+export default defineWorkspace([
+  'packages/*',
+  'apps/*',
+])
+```
+
+Each workspace entry can have its own `vitest.config.ts` or `vite.config.ts` with a `test` block.
+
+## Parameterized Tests (test.each)
+
+```ts
+test.each([
+  { a: 1, b: 2, expected: 3 },
+  { a: 0, b: 0, expected: 0 },
+])('adds $a + $b = $expected', ({ a, b, expected }) => {
+  expect(a + b).toBe(expected)
+})
+
+// Array of arrays
+test.each([
+  [1, 2, 3],
+  [4, 5, 9],
+])('adds %i + %i = %i', (a, b, expected) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+## Snapshot Testing
+
+```ts
+expect(obj).toMatchSnapshot()
+expect(html).toMatchInlineSnapshot(`<div>...</div>`)
+```
+
+Use inline snapshots for small, stable outputs; file snapshots for larger structures.
+
+## Setup and Teardown
+
+```ts
+beforeAll(() => { /* once per describe */ })
+afterAll(() => { /* once per describe */ })
+beforeEach(() => { /* before each it */ })
+afterEach(() => { /* after each it */ })
+```
+
+Reset mocks in `beforeEach` to avoid cross-test pollution:
+
+```ts
+beforeEach(() => {
+  vi.clearAllMocks()
+  // or vi.restoreAllMocks() to restore original implementations
+})
+```

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

@@ -0,0 +1,145 @@
+---
+name: qa-webdriverio-writer
+description: Generate WebdriverIO E2E and mobile web tests for TypeScript using W3C WebDriver protocol with multi-browser support, Appium integration, and Page Object pattern.
+output_dir: tests/e2e
+---
+
+# QA WebdriverIO Writer
+
+## Purpose
+
+Write WebdriverIO E2E and mobile web tests from test case specifications. Transform structured test cases into executable TypeScript test files using the W3C WebDriver protocol, multi-browser support, Appium for mobile web, and the Page Object pattern.
+
+## Trigger Phrases
+
+- "Write WebdriverIO tests for [feature/flow]"
+- "Generate WebdriverIO E2E tests from test cases"
+- "Create WebdriverIO tests with Page Objects"
+- "Add WebdriverIO mobile web tests"
+- "WebdriverIO tests for [URL/flow]"
+- "Multi-browser WebdriverIO tests"
+- "Appium + WebdriverIO tests for mobile web"
+- "WDIO tests with custom commands"
+
+## Workflow
+
+1. **Read test cases** — From qa-testcase-from-docs, qa-manual-test-designer, qa-browser-data-collector
+2. **Analyze target** — Page structure, selectors, mobile vs desktop
+3. **Generate test files** — Create `*.spec.ts` in `test/specs/` or project convention
+4. **Add Page Objects** — Encapsulate selectors and actions in `pageobjects/`
+5. **Configure wdio.conf.ts** — Capabilities, services, reporters
+
+## Key Features
+
+- **W3C WebDriver protocol** — Standard browser automation
+- **Multi-browser** — Chrome, Firefox, Safari, Edge via capabilities
+- **Appium integration** — Mobile web testing (iOS Safari, Android Chrome)
+- **Page Object pattern** — Encapsulate page logic, reusable selectors
+- **Built-in wait strategies** — `waitForDisplayed`, `waitForClickable`, `waitForExist`
+- **WDIO test runner** — Parallel execution, retries, reporters
+
+## Test Types
+
+| Type | Scope | Approach |
+|------|-------|----------|
+| **E2E** | Full user flows, page navigation | browser.url, $(), $$(), click, setValue, getText |
+| **Mobile Web** | Mobile browser testing | Appium service, mobile capabilities, viewport |
+
+## E2E Testing
+
+- **Navigation:** `browser.url()`, `browser.back()`, `browser.refresh()`
+- **Selectors:** `$('selector')` single element, `$$('selector')` element array
+- **Actions:** `.click()`, `.setValue()`, `.addValue()`, `.clearValue()`, `.selectByVisibleText()`
+- **Getters:** `.getText()`, `.getAttribute()`, `.getValue()`, `.isDisplayed()`
+- **Waits:** `.waitForDisplayed()`, `.waitForClickable()`, `.waitForExist()`, `browser.waitUntil()`
+
+See `references/patterns.md` for selectors, waits, Page Objects, custom commands, file upload, multiremote.
+
+## Page Object Pattern
+
+- **Base page:** Shared selectors, navigation helpers, common actions
+- **Page-specific:** Extend base; encapsulate page-specific locators and methods
+- **WDIO Page Object** — Use `get` getters for lazy element resolution
+
+See `references/best-practices.md` for Page Object structure.
+
+## Key Patterns
+
+- **Structure:** `describe` / `it`, `before` / `after`, `beforeEach` / `afterEach`
+- **Selectors:** CSS, XPath, accessibility (aria), data attributes
+- **Assertions:** `expect()` (Chai/Expect), `browser.assert` (if using expect-webdriverio)
+- **Custom commands:** `browser.addCommand()` for reusable actions
+- **Multiremote:** Run same test across multiple browsers in parallel
+
+## Services
+
+| Service | Purpose |
+|---------|---------|
+| `@wdio/local-runner` | Local test execution |
+| `@wdio/mocha-framework` | Mocha describe/it (or Jasmine, Cucumber) |
+| `wdio-chromedriver-service` | ChromeDriver for Chrome |
+| `@wdio/appium-service` | Appium for mobile web |
+| `@wdio/selenium-standalone-service` | Selenium Grid / standalone |
+
+## Configuration
+
+- **wdio.conf.ts** — Capabilities, services, framework, reporters, specs
+- **Multi-capability** — Run same tests on multiple browsers
+- **Environment-specific** — baseUrl, timeouts via config
+
+See `references/config.md` for full configuration guide.
+
+## Context7 MCP
+
+Uses Context7 MCP to fetch WebdriverIO documentation when needed. Query for WebdriverIO API, selectors, or configuration when patterns are unclear.
+
+## Scope
+
+**Can do (autonomous):**
+- Generate WebdriverIO E2E and mobile web tests from test cases
+- Apply Page Object pattern with getters and methods
+- Add custom commands via `browser.addCommand()`
+- Configure wdio.conf.ts (capabilities, services, reporters)
+- Use multiremote for parallel browser testing
+- Use Context7 MCP for WebdriverIO docs
+
+**Cannot do (requires confirmation):**
+- Change production code structure
+- Add dependencies not in package.json
+- Override project WDIO config without approval
+- Modify Appium server configuration
+
+**Will not do (out of scope):**
+- Execute tests (user runs `npx wdio run wdio.conf.ts`)
+- Write Jest/Vitest unit tests (use qa-jest-writer)
+- Modify CI/CD pipelines
+- Native mobile app testing (Appium native, not mobile web)
+
+## References
+
+- `references/patterns.md` — Selectors, waits, Page Objects, custom commands, file upload, multiremote
+- `references/config.md` — wdio.conf.ts, capabilities, services, reporters
+- `references/best-practices.md` — Stable selectors, wait strategies, Page Objects, parallel execution
+
+## Quality Checklist
+
+- [ ] Explicit waits used; avoid `browser.pause()` in committed code
+- [ ] Page Object pattern applied for page-specific logic
+- [ ] Stable selectors (data-testid, aria, semantic over brittle CSS)
+- [ ] Tests independent (no shared state, order-independent)
+- [ ] Proper teardown (afterEach, cleanup)
+- [ ] Traceability to test case IDs where applicable
+- [ ] No hardcoded secrets (use env vars)
+- [ ] Capabilities match target browsers
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Element not found | Selector too specific, timing | Use data-testid; add waitForDisplayed before action |
+| Stale element | DOM changed after query | Re-query element; use getters in Page Objects |
+| Timeout on wait | Element never meets condition | Verify selector; check overlays, iframes |
+| Multiremote fails | Capability mismatch | Ensure all browsers support same commands |
+| Appium not starting | Service/config issue | Check @wdio/appium-service; verify Appium installed |
+| ChromeDriver version mismatch | Chrome updated | Update wdio-chromedriver-service or chromedriver |
+| Flaky tests | Race conditions | Use waitForDisplayed/waitForClickable; avoid fixed delays |

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

@@ -0,0 +1,176 @@
+# WebdriverIO Best Practices
+
+## Stable Selectors
+
+### Prefer Data Attributes
+
+```typescript
+// Good — test-specific, stable
+await $('[data-testid="submit-btn"]').click();
+await $('[data-testid="email-input"]').setValue('user@example.com');
+
+// Avoid — brittle
+await $('.btn-primary').click();
+await $('#email').setValue('user@example.com');
+await $('div > form > div:nth-child(2) > input').setValue('user@example.com');
+```
+
+Add `data-testid` to production markup or recommend adding to the app. Avoid relying on CSS classes, IDs, or DOM structure that may change with refactors.
+
+### Selector Priority
+
+1. **data-testid** — Explicit, stable, test-specific
+2. **Semantic attributes** — name, aria-label, role
+3. **Stable IDs** — IDs that won't change
+4. **CSS** — Simple, meaningful classes
+5. **XPath** — Last resort; use for text when necessary
+
+---
+
+## Wait Strategies
+
+### Use Explicit Waits
+
+```typescript
+// Good — wait for condition
+await $('#results').waitForDisplayed({ timeout: 5000 });
+await $('#loading').waitForExist({ reverse: true });
+await $('button').waitForClickable();
+
+// Bad — arbitrary delay
+await browser.pause(3000);
+```
+
+### waitUntil for Custom Conditions
+
+```typescript
+await browser.waitUntil(
+  async () => (await $('#status').getText()) === 'Complete',
+  { timeout: 10000, interval: 500, timeoutMsg: 'Status never became Complete' }
+);
+```
+
+### Assertions Include Implicit Waits
+
+WebdriverIO assertions retry until timeout:
+
+```typescript
+await expect($('#results')).toBeDisplayed();
+await expect($('h1')).toHaveText('Welcome');
+```
+
+---
+
+## Page Object Pattern
+
+### Structure
+
+```
+test/
+  specs/
+    login.spec.ts
+  pages/
+    BasePage.ts
+    LoginPage.ts
+    DashboardPage.ts
+```
+
+### Encapsulation
+
+- **One page object per page/screen** — Encapsulate selectors and actions
+- **Base page for shared logic** — Navigation, common helpers
+- **Getters for elements** — Lazy evaluation; elements resolved when used
+- **Methods for actions** — Reusable flows (login, fillForm, etc.)
+
+### Avoid Logic in Tests
+
+```typescript
+// Bad — implementation details in test
+it('logs in', async () => {
+  await $('input[name="email"]').setValue('user@test.com');
+  await $('input[name="password"]').setValue('secret');
+  await $('button').click();
+});
+
+// Good — page object encapsulates
+it('logs in', async () => {
+  await loginPage.login('user@test.com', 'secret');
+});
+```
+
+---
+
+## Parallel Execution
+
+### maxInstances
+
+```typescript
+// wdio.conf.ts
+maxInstances: 5, // Run up to 5 specs in parallel
+```
+
+### Test Independence
+
+- Each test must run in isolation
+- No shared mutable state between tests
+- Use `beforeEach` for setup; avoid order-dependent tests
+- Prefer API or fixture data over UI-created state
+
+### Sharding for CI
+
+```bash
+wdio run wdio.conf.ts --shard=1/4
+wdio run wdio.conf.ts --shard=2/4
+wdio run wdio.conf.ts --shard=3/4
+wdio run wdio.conf.ts --shard=4/4
+```
+
+---
+
+## Error Handling and Debugging
+
+### Screenshots on Failure
+
+```typescript
+afterTest: async function (test, context, result) {
+  if (result.error) {
+    await browser.takeScreenshot();
+  }
+},
+```
+
+### Logs
+
+```typescript
+browser.debug(); // Pause and open REPL
+browser.pause(5000); // Pause (avoid in production tests)
+```
+
+### Traceability
+
+Include test case IDs in describe/it names:
+
+```typescript
+describe('Login [TC-001]', () => {
+  it('displays error on invalid credentials [TC-001-01]', async () => {
+    // ...
+  });
+});
+```
+
+---
+
+## Security and Secrets
+
+- Never hardcode credentials — use `process.env` or config
+- Store API keys in `.env` (gitignored)
+- Use `browser.addCommand` for login flows that need credentials from env
+
+---
+
+## Mobile Web (Appium)
+
+- Use `browser.isMobile` to branch mobile vs desktop logic when needed
+- Prefer touch actions for mobile: `element.touchAction('tap')` or `element.click()`
+- Set viewport/capabilities for target device sizes
+- Use Appium inspector to discover selectors on real devices/emulators