qa-flowkit 0.4.0-alpha.0

package/.qa-ai/agents/specialists/available/cypress.md

@@ -0,0 +1,68 @@
+# Cypress Specialist
+
+> Framework-specific guidance for UI/E2E automation with Cypress.
+
+## Activation
+
+Use when `automation.ui.framework` is `cypress`.
+
+## Role
+
+Complements the UI Automation Implementation Agent by providing Cypress-specific patterns, commands and constraints. The implementation agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing Cypress specs, commands, fixtures and support file conventions.
+- Prefer stable selectors (`data-cy`, `data-testid`) and custom commands only when they reduce repeated workflow noise.
+- Avoid arbitrary waits; use Cypress retry behavior, `cy.intercept()` and network aliases.
+- Keep tests independent and avoid leaking state between specs.
+- Do not change Cypress global config without approval.
+
+## Selector Strategy (by priority)
+
+1. `[data-cy="..."]` or `[data-testid="..."]` (dedicated test attributes).
+2. `cy.findByRole()` / `cy.findByText()` (Testing Library integration if available).
+3. Semantic HTML selectors (button, input[type="..."], aria-label).
+4. CSS class selectors (avoid; they change with styling).
+
+## Command Patterns
+
+- **Custom commands**: Use for multi-step repeated workflows (login, navigation, form fill). Keep atomic.
+- **cy.intercept()**: Stub or wait for API calls to control test timing and isolate frontend.
+- **cy.session()**: Cache and restore authentication state across specs. Prefer over repeated login flows.
+- **Fixtures**: Use `cy.fixture()` for static test data. Keep fixtures small and focused.
+
+## Component Testing vs E2E
+
+- Use Cypress Component Testing for isolated component validation (faster, no server needed).
+- Use E2E specs for user flows that cross multiple pages or require backend state.
+- Do not mix component and E2E concerns in the same spec file.
+
+## Anti-Patterns to Avoid
+
+- `cy.wait(N)` with hardcoded milliseconds — use `cy.intercept()` aliases instead.
+- Chaining too many assertions in one `it()` block — split into focused test cases.
+- Using `cy.get()` with dynamic classes — use stable test attributes.
+- Accessing `window` or DOM directly when a Cypress command exists.
+- Tests that depend on execution order within a spec file.
+- Using `{ force: true }` to bypass visibility — fix the UI interaction instead.
+
+## Authentication Pattern
+
+```javascript
+// Preferred: use cy.session() for cached auth
+cy.session('user', () => {
+  cy.visit('/login')
+  cy.get('[data-cy=email]').type(email)
+  cy.get('[data-cy=password]').type(password)
+  cy.get('[data-cy=submit]').click()
+  cy.url().should('not.include', '/login')
+})
+```
+
+## Constraints
+
+- Do not modify `cypress.config.*` without approval.
+- Do not add plugins or dependencies without approval.
+- Do not use `cy.exec()` for test setup when API commands are available.
+- Keep test data isolated; do not rely on shared database state.

package/.qa-ai/agents/specialists/available/generic-test-design.md

@@ -0,0 +1,117 @@
+# Generic Test Design Specialist
+
+> Guidance for non-Gherkin test case design: structured manual tests, test matrices and exploratory charters.
+
+## Activation
+
+Use for test design output that is not written as Gherkin `.feature` files. Activated when the workflow needs manual test documentation, structured test cases, or when the team prefers non-Gherkin formats.
+
+## Role
+
+Complements the Gherkin Test Design Agent when alternative output formats are needed. Produces structured test case documentation for manual execution, exploratory testing, or teams that do not use Gherkin.
+
+## Focus
+
+- Produce clear manual or structured test cases in the configured interface language.
+- Include preconditions, test data, steps, expected results, priority, type and automation suitability.
+- Maintain traceability to RF/CA IDs.
+- Keep one logical test case per section or record.
+- Do not replace required Gherkin generation when `gherkin` output is requested or required by config.
+
+## Test Case Template
+
+```markdown
+## TC-[RF-ID]-[N]: [Title]
+
+**Traceability**: RF-[ID] CA-[N]
+**Priority**: High | Medium | Low
+**Type**: Functional | Regression | Smoke | E2E | Negative | Edge-case
+**Automation**: Automatable | Manual Only | Automated
+**Estimated Time**: [minutes]
+
+### Preconditions
+- [Required state before test execution]
+- [Required test data]
+
+### Test Data
+| Field | Value | Notes |
+|---|---|---|
+| [input field] | [value] | [explanation] |
+
+### Steps
+| # | Action | Expected Result |
+|---|---|---|
+| 1 | [action] | [expected outcome] |
+| 2 | [action] | [expected outcome] |
+
+### Postconditions
+- [State after test execution]
+- [Cleanup needed]
+
+### Notes
+- [Edge cases to consider]
+- [Related test cases]
+```
+
+## Test Design Techniques
+
+Apply appropriate techniques based on the criterion type:
+
+| Technique | When to Use | Output |
+|---|---|---|
+| **Boundary Value Analysis** | Numeric inputs, ranges, limits | Min, min+1, max-1, max, below-min, above-max |
+| **Equivalence Partitioning** | Large input domains | Representative value per partition |
+| **Decision Table** | Multiple conditions with combined outcomes | Condition/action matrix |
+| **State Transition** | Workflows, status changes | State diagram + transition test cases |
+| **Pairwise/Combinatorial** | Multiple parameters with many values | Reduced combination set |
+| **Error Guessing** | Known failure patterns | Negative test cases |
+
+## Decision Table Format
+
+```markdown
+### Decision Table: [Feature]
+
+| Condition | Rule 1 | Rule 2 | Rule 3 | Rule 4 |
+|---|---|---|---|---|
+| [Condition A] | T | T | F | F |
+| [Condition B] | T | F | T | F |
+| **Action** | | | | |
+| [Action X] | ✓ | ✓ | — | — |
+| [Action Y] | — | — | ✓ | ✗ |
+```
+
+## Exploratory Testing Charter
+
+```markdown
+## Charter: [Area/Feature]
+
+**Mission**: Explore [feature/area] to discover [type of issues]
+**Time box**: [30-90 minutes]
+**Focus areas**:
+- [Specific aspect 1]
+- [Specific aspect 2]
+
+**Risks to investigate**:
+- [Known risk 1]
+- [Known risk 2]
+
+**Notes template**:
+- Observations: [what was found]
+- Issues: [bugs or concerns]
+- Questions: [things to clarify]
+```
+
+## Anti-Patterns to Avoid
+
+- Steps that say "verify it works correctly" — specify exact expected outcome.
+- Missing preconditions — tests become unreproducible.
+- Steps that combine multiple actions and verifications — keep atomic.
+- No traceability — every test case must link to a requirement.
+- Overly detailed steps for senior testers / too vague for junior testers — calibrate to team.
+
+## Constraints
+
+- Do not replace Gherkin generation when config requires `.feature` output.
+- Use as complement (manual test docs) or alternative (when explicitly chosen).
+- Write in the configured interface language.
+- Maintain traceability to RF/CA in all formats.

package/.qa-ai/agents/specialists/available/jira.md

@@ -0,0 +1,108 @@
+# Jira Specialist
+
+> Integration guidance for Jira as requirement source and issue tracker.
+
+## Activation
+
+Use when `tools.issueTracker` or `sources.main` is `jira`.
+
+## Role
+
+Complements the Requirements Intake Agent (when Jira is the requirement source) and the Issue Task Agent (when Jira is the issue tracker) by providing Jira-specific extraction patterns, field conventions and constraints.
+
+## Focus
+
+- Treat Jira content as a requirement source when configured.
+- Extract story, RF, acceptance criteria, attachments and linked context.
+- Prepare issue/task drafts locally when automation work cannot be completed now.
+- Keep external writes disabled in the MVP.
+- Never store Jira credentials or private tokens in repository files.
+
+## Requirement Extraction from Jira
+
+When Jira is `sources.main`:
+
+| Jira Field | Maps To | Notes |
+|---|---|---|
+| Issue Key (PROJ-123) | RF ID | Use as-is or map to RF-[key] |
+| Summary | Requirement Title | — |
+| Description | Requirement Description | Parse for user story format |
+| Acceptance Criteria (custom field or description section) | CA list | Extract numbered criteria |
+| Priority | Requirement Priority | Map: Highest/High→high, Medium→medium, Low/Lowest→low |
+| Attachments | Supporting docs | Reference file names |
+| Linked Issues | Dependencies/Context | Note blocking/blocked relationships |
+| Labels/Components | Tags/Categories | Map to test types when applicable |
+
+## User Story Parsing
+
+Detect and extract from common formats:
+
+```
+As a [role]
+I want to [action]
+So that [business value]
+
+Acceptance Criteria:
+- Given [context] When [action] Then [expected]
+- [criterion in natural language]
+```
+
+When the format is non-standard, extract best-effort and flag for review.
+
+## JQL Patterns for Discovery
+
+```
+# Find stories for a sprint/epic
+project = PROJ AND issuetype = Story AND sprint = "Sprint 23"
+project = PROJ AND "Epic Link" = PROJ-100
+
+# Find stories with acceptance criteria
+project = PROJ AND issuetype = Story AND description ~ "Acceptance Criteria"
+
+# Find linked test cases
+project = PROJ AND issuetype = "Test Case" AND issueFunction in linkedIssuesOf("key = PROJ-123")
+```
+
+## Issue Task Draft Format (for Jira)
+
+When creating task drafts for the Issue Task Agent:
+
+```markdown
+# Task Draft: [Title]
+
+## Jira Fields
+- **Project**: [PROJ]
+- **Issue Type**: Task | Story | Sub-task
+- **Priority**: [mapped priority]
+- **Labels**: automation, qa, [framework]
+- **Components**: [if applicable]
+- **Epic Link**: [parent epic if known]
+- **Linked Issues**: relates to [RF issue key]
+
+## Description
+[Task description in Jira markdown format]
+
+## Acceptance Criteria
+- [checkbox style criteria]
+```
+
+## Custom Fields
+
+- Respect existing custom field configurations.
+- Common QA-relevant custom fields: `Acceptance Criteria`, `Test Coverage`, `Automation Status`, `RF ID`.
+- When custom fields are unknown, ask user for the field mapping.
+
+## Anti-Patterns to Avoid
+
+- Parsing Jira wiki markup incorrectly — handle `{panel}`, `{code}`, tables and lists.
+- Assuming all stories follow the same template — handle variations.
+- Creating sub-tasks without knowing the project's workflow — draft only.
+- Ignoring linked issues — they provide context for dependencies and scope.
+- Storing Jira API tokens or cookies in any file.
+
+## Constraints
+
+- Keep external writes disabled in the MVP. Draft tasks locally only.
+- Never store Jira credentials or private tokens in repository files.
+- Do not assume project workflow states; ask when needed.
+- Do not modify Jira issues without explicit approval and future integration.

package/.qa-ai/agents/specialists/available/karate.md

@@ -0,0 +1,97 @@
+# Karate API Specialist
+
+> Framework-specific guidance for API testing with Karate DSL.
+
+## Activation
+
+Use when `automation.api.framework` is `karate`.
+
+## Role
+
+Complements the API Testing Agent by providing Karate-specific patterns, feature file conventions and constraints. The API agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing Karate feature, config and runner conventions.
+- Keep reusable setup in `karate-config.js` or shared feature files according to repo patterns.
+- Prefer readable scenario steps and data tables over complex scripting.
+- Validate status, response structure and business-relevant fields.
+- Do not change build, runner or environment config without approval.
+
+## Feature File Pattern
+
+```gherkin
+Feature: Create Order API
+
+  Background:
+    * url baseUrl
+    * header Authorization = 'Bearer ' + authToken
+
+  Scenario: Create order with valid payload
+    Given path '/orders'
+    And request { items: [{ sku: 'ABC', qty: 2 }] }
+    When method post
+    Then status 201
+    And match response.id == '#notnull'
+    And match response.status == 'pending'
+    And match response.items == '#[1]'
+```
+
+## Reusable Features (call)
+
+```gherkin
+# login.feature (reusable)
+Feature: Login
+  Scenario:
+    Given url baseUrl + '/auth/login'
+    And request { email: '#(email)', password: '#(password)' }
+    When method post
+    Then status 200
+    * def authToken = response.token
+```
+
+Call from other features: `* def login = call read('classpath:login.feature') { email: '...', password: '...' }`
+
+## Data-Driven Testing
+
+```gherkin
+Scenario Outline: Validate order status transitions
+  Given path '/orders/' + orderId + '/status'
+  And request { status: '<newStatus>' }
+  When method patch
+  Then status <expectedCode>
+
+  Examples:
+    | newStatus  | expectedCode |
+    | confirmed  | 200          |
+    | invalid    | 400          |
+    | shipped    | 200          |
+```
+
+## Embedded Expressions
+
+- Use `#(variable)` for simple substitution.
+- Use `#(expression)` for inline JavaScript evaluation.
+- Use `karate.set()` for dynamic values across scenarios.
+- Prefer JSON path matchers (`#notnull`, `#present`, `#[N]`, `#regex`) over custom assertions.
+
+## Anti-Patterns to Avoid
+
+- Complex JavaScript logic inside feature files — move to `karate-config.js` or Java helpers.
+- Hardcoded base URLs — use `karate-config.js` with environment switching.
+- Long scenario chains that depend on order — keep scenarios independent.
+- Not using Background for shared setup.
+- Ignoring response schema — always validate structure, not just status.
+
+## Environment Configuration
+
+- Use `karate-config.js` with `karate.env` for environment switching.
+- Keep sensitive values (tokens, keys) in environment variables referenced via `karate.properties`.
+- Never hardcode environment-specific values in feature files.
+
+## Constraints
+
+- Do not change `karate-config.js`, build files (pom.xml, build.gradle) or runner config without approval.
+- Do not add Java dependencies without approval.
+- Do not hardcode credentials or environment URLs in feature files.
+- Keep features readable by non-developers (QA team members).

package/.qa-ai/agents/specialists/available/playwright-api.md

@@ -0,0 +1,87 @@
+# Playwright API Specialist
+
+> Framework-specific guidance for API/integration testing with Playwright's request context.
+
+## Activation
+
+Use when `automation.api.framework` is `playwright-api` or `playwright`.
+
+## Role
+
+Complements the API Testing Agent by providing Playwright APIRequestContext-specific patterns and constraints. The API agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing Playwright request context, fixture and API client conventions.
+- Keep API clients thin and reusable using custom fixtures.
+- Validate status, contract-relevant response fields and important side effects.
+- Keep auth, test data setup and cleanup explicit.
+- Do not change global Playwright config without approval.
+
+## APIRequestContext Pattern
+
+```typescript
+// fixtures.ts — create API client as a fixture
+import { test as base } from '@playwright/test';
+
+export const test = base.extend<{ apiClient: APIRequestContext }>({
+  apiClient: async ({ playwright }, use) => {
+    const context = await playwright.request.newContext({
+      baseURL: process.env.API_BASE_URL,
+      extraHTTPHeaders: {
+        'Authorization': `Bearer ${process.env.API_TOKEN}`,
+        'Content-Type': 'application/json',
+      },
+    });
+    await use(context);
+    await context.dispose();
+  },
+});
+```
+
+## Response Validation Pattern
+
+```typescript
+test('create order returns expected structure', async ({ apiClient }) => {
+  const response = await apiClient.post('/orders', { data: orderPayload });
+
+  expect(response.status()).toBe(201);
+  const body = await response.json();
+  expect(body).toHaveProperty('id');
+  expect(body.status).toBe('pending');
+  expect(body.items).toHaveLength(orderPayload.items.length);
+});
+```
+
+## Schema Validation
+
+- Use Zod, JSON Schema, or TypeScript type guards for response shape validation.
+- Validate schema in a reusable helper, not inline in every test.
+- Separate "contract tests" (schema shape) from "behavior tests" (business logic).
+
+## Authentication Patterns
+
+- Token-based: Generate token in a global setup, share via environment or fixture.
+- Session-based: Create session in a `beforeAll` fixture, pass context with cookies.
+- API Key: Load from environment variables, never hardcode.
+
+## Anti-Patterns to Avoid
+
+- Hardcoding base URLs — use `baseURL` from config or environment.
+- Not disposing request contexts — always dispose in fixture teardown.
+- Testing implementation details (internal IDs, database state) — test observable behavior.
+- Skipping status code validation — always assert status before parsing body.
+- Chaining dependent API calls without assertions between them.
+
+## Test Data Management
+
+- Create test data via API in setup, clean up in teardown.
+- Use factory patterns for complex payloads.
+- Never depend on pre-existing database state; tests must be self-contained.
+
+## Constraints
+
+- Do not modify `playwright.config.*` without approval.
+- Do not store API tokens or credentials in test files.
+- Do not run destructive operations (DELETE, PATCH) on shared environments without safeguards.
+- Use environment variables for all environment-specific configuration.

package/.qa-ai/agents/specialists/available/playwright-ui.md

@@ -0,0 +1,87 @@
+# Playwright UI Specialist
+
+> Framework-specific guidance for UI/E2E automation with Playwright.
+
+## Activation
+
+Use when `automation.ui.framework` is `playwright` or `playwright-ui`.
+
+## Role
+
+Complements the UI Automation Implementation Agent by providing Playwright-specific patterns, fixtures and constraints. The implementation agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing Playwright test, fixture and page-object conventions.
+- Prefer locators by role, label, text or test id over brittle CSS/XPath.
+- Use Playwright auto-waiting and web-first assertions instead of fixed sleeps.
+- Keep browser context, auth state, fixtures and test data isolated.
+- Do not change Playwright global config without approval.
+
+## Locator Strategy (by priority)
+
+1. `page.getByRole('button', { name: '...' })` — semantic, accessible, stable.
+2. `page.getByLabel('...')` / `page.getByPlaceholder('...')` — form elements.
+3. `page.getByText('...')` — visible text content.
+4. `page.getByTestId('...')` — dedicated test attributes.
+5. `page.locator('css=...')` — last resort for complex cases.
+
+## Modern Fixture Pattern (POM + Fixtures)
+
+```typescript
+// fixtures.ts — compose page objects as fixtures
+import { test as base } from '@playwright/test';
+import { LoginPage } from './pages/login.page';
+
+export const test = base.extend<{ loginPage: LoginPage }>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+});
+```
+
+Prefer fixture-based page object injection over manual instantiation in each test.
+
+## Authentication Pattern
+
+```typescript
+// Use storageState for cached auth across tests
+const authFile = '.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(email);
+  await page.getByLabel('Password').fill(password);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await page.context().storageState({ path: authFile });
+});
+```
+
+## Debugging and Traces
+
+- Use `trace: 'on-first-retry'` in config for CI debugging.
+- Use `video: 'on-first-retry'` to capture failures.
+- Use `await page.pause()` during development, never commit it.
+- Use `test.describe.configure({ mode: 'serial' })` only when tests genuinely depend on order.
+
+## Anti-Patterns to Avoid
+
+- `page.waitForTimeout(N)` — use `expect(locator).toBeVisible()` or similar assertions.
+- `page.locator('.class-name')` as first choice — use semantic locators.
+- Sharing page state between `test()` blocks — each test gets a fresh context by default.
+- Using `{ force: true }` on clicks — fix the actionability issue instead.
+- `page.$()` / `page.$$()` (ElementHandle API) — use Locator API instead.
+- Manual `try/catch` around assertions — let Playwright's retry mechanism handle transient states.
+
+## Parallel Execution
+
+- Tests run in parallel by default. Design for isolation.
+- Use `test.describe.configure({ mode: 'parallel' })` explicitly for clarity.
+- Workers share nothing; avoid filesystem-based shared state.
+
+## Constraints
+
+- Do not modify `playwright.config.*` without approval.
+- Do not add browser dependencies without approval.
+- Do not use `page.evaluate()` for interactions when Locator API methods exist.
+- Keep test data isolated; do not rely on shared database state between workers.

package/.qa-ai/agents/specialists/available/postman.md

@@ -0,0 +1,108 @@
+# Postman/Newman Specialist
+
+> Framework-specific guidance for API testing with Postman collections and Newman CLI.
+
+## Activation
+
+Use when `automation.api.framework` is `postman` or `newman`.
+
+## Role
+
+Complements the API Testing Agent by providing Postman/Newman-specific patterns, variable strategies and constraints. The API agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing collection, environment and data-file conventions.
+- Keep secrets out of collections and repository files.
+- Prefer reusable variables and pre-request scripts only when they clarify repeated setup.
+- Make assertions clear, stable and tied to acceptance criteria.
+- Document Newman execution commands when tests cannot be run locally.
+
+## Collection Structure
+
+```
+postman/
+├── collections/
+│   ├── RF-042-authentication.postman_collection.json
+│   └── RF-015-orders.postman_collection.json
+├── environments/
+│   ├── local.postman_environment.json
+│   └── staging.postman_environment.json
+├── data/
+│   └── order-test-data.json
+└── README.md   (execution instructions)
+```
+
+## Variable Scopes (priority order)
+
+1. **Data variables** — from CSV/JSON data files (highest priority in iteration).
+2. **Environment variables** — environment-specific values (base URL, keys).
+3. **Collection variables** — shared defaults within a collection.
+4. **Global variables** — cross-collection shared values (use sparingly).
+
+Never store secrets in collection or global variables committed to repo.
+
+## Pre-Request Script Patterns
+
+```javascript
+// Token refresh in pre-request
+if (!pm.environment.get('authToken') || tokenExpired()) {
+    pm.sendRequest({
+        url: pm.environment.get('baseUrl') + '/auth/token',
+        method: 'POST',
+        body: { mode: 'raw', raw: JSON.stringify({ ... }) }
+    }, (err, res) => {
+        pm.environment.set('authToken', res.json().token);
+    });
+}
+```
+
+Use pre-request scripts only for: auth token refresh, dynamic test data generation, timestamp/nonce creation.
+
+## Test (Assertion) Patterns
+
+```javascript
+// Clear, tied to acceptance criteria
+pm.test("RF-042 CA-1: Login returns 200 with token", () => {
+    pm.response.to.have.status(200);
+    const body = pm.response.json();
+    pm.expect(body.token).to.be.a('string').and.not.empty;
+    pm.expect(body.expiresIn).to.be.above(0);
+});
+
+pm.test("RF-042 CA-2: Invalid credentials return 401", () => {
+    pm.response.to.have.status(401);
+    pm.expect(pm.response.json().error).to.eql('Invalid credentials');
+});
+```
+
+## Newman CI Execution
+
+```bash
+# Basic execution
+newman run collections/RF-042-auth.postman_collection.json \
+  -e environments/staging.postman_environment.json \
+  --reporters cli,junit \
+  --reporter-junit-export results/junit-report.xml
+
+# Data-driven execution
+newman run collections/RF-015-orders.postman_collection.json \
+  -d data/order-test-data.json \
+  -e environments/staging.postman_environment.json
+```
+
+## Anti-Patterns to Avoid
+
+- Storing secrets (tokens, passwords, API keys) in collection or environment files committed to repo.
+- Complex business logic in pre-request scripts — keep it simple, move complex logic to API-side.
+- Tests that depend on execution order — each request should be independently runnable.
+- Using global variables for request-specific data — scope correctly.
+- Not documenting Newman execution commands — other team members need to run tests.
+- Assertions that only check status code — validate response structure and business fields.
+
+## Constraints
+
+- Do not commit environment files with real credentials to the repository.
+- Do not use Postman Cloud sync for collections that contain sensitive test configurations.
+- Document Newman execution commands in the collection's README.
+- Keep collections importable/exportable (do not rely on Postman-specific cloud features for execution).