qa-skills 3.0.0

package/skills/qa-api-contract-curator/references/openapi-structure.md

@@ -0,0 +1,404 @@
+# OpenAPI 3.x Specification Structure Reference
+
+Reference for building and validating OpenAPI 3.x specifications. Use when generating or curating API contracts.
+
+## Document Root
+
+```yaml
+openapi: 3.0.3
+info:
+  title: API Title
+  description: API description
+  version: 1.0.0
+  contact:
+    name: API Support
+    email: support@example.com
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://staging-api.example.com/v1
+    description: Staging
+paths: {}
+components: {}
+```
+
+## Paths
+
+### Basic Path Structure
+
+```yaml
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags:
+        - Users
+      parameters: []
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+    post:
+      summary: Create user
+      operationId: createUser
+      tags:
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserCreate'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /users/{userId}:
+    parameters:
+      - $ref: '#/components/parameters/UserId'
+    get:
+      summary: Get user by ID
+      operationId: getUserById
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '404':
+          description: Not found
+```
+
+### Path Parameters
+
+```yaml
+/users/{userId}/orders/{orderId}:
+  parameters:
+    - name: userId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    - name: orderId
+      in: path
+      required: true
+      schema:
+        type: string
+```
+
+## Parameters
+
+### Query Parameters
+
+```yaml
+parameters:
+  - name: page
+    in: query
+    description: Page number (1-based)
+    schema:
+      type: integer
+      minimum: 1
+      default: 1
+  - name: limit
+    in: query
+    description: Items per page
+    schema:
+      type: integer
+      minimum: 1
+      maximum: 100
+      default: 20
+  - name: sort
+    in: query
+    schema:
+      type: string
+      enum: [createdAt, updatedAt, name]
+  - name: filter
+    in: query
+    description: JSON filter expression
+    schema:
+      type: string
+```
+
+### Header Parameters
+
+```yaml
+parameters:
+  - name: X-Request-ID
+    in: header
+    description: Idempotency key
+    schema:
+      type: string
+      format: uuid
+  - name: X-Correlation-ID
+    in: header
+    schema:
+      type: string
+```
+
+## Schemas (Components)
+
+### Basic Schema
+
+```yaml
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+```
+
+### Schema with Examples
+
+```yaml
+User:
+  type: object
+  properties:
+    id:
+      type: string
+      format: uuid
+      example: "550e8400-e29b-41d4-a716-446655440000"
+    email:
+      type: string
+      format: email
+      example: "user@example.com"
+  example:
+    id: "550e8400-e29b-41d4-a716-446655440000"
+    email: "user@example.com"
+    name: "Jane Doe"
+    createdAt: "2024-01-15T10:30:00Z"
+```
+
+### Array Schema
+
+```yaml
+UserList:
+  type: object
+  properties:
+    items:
+      type: array
+      items:
+        $ref: '#/components/schemas/User'
+    total:
+      type: integer
+      description: Total count
+    page:
+      type: integer
+    limit:
+      type: integer
+```
+
+### Enum and OneOf
+
+```yaml
+OrderStatus:
+  type: string
+  enum: [pending, confirmed, shipped, delivered, cancelled]
+
+PaymentMethod:
+  oneOf:
+    - $ref: '#/components/schemas/CardPayment'
+    - $ref: '#/components/schemas/BankTransfer'
+```
+
+### Error Schema
+
+```yaml
+Error:
+  type: object
+  required:
+    - code
+    - message
+  properties:
+    code:
+      type: string
+      example: "VALIDATION_ERROR"
+    message:
+      type: string
+      example: "Invalid input"
+    details:
+      type: array
+      items:
+        type: object
+        properties:
+          field:
+            type: string
+          reason:
+            type: string
+```
+
+## Security Schemes
+
+### API Key (Header)
+
+```yaml
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key for authentication
+```
+
+### Bearer JWT
+
+```yaml
+BearerAuth:
+  type: http
+  scheme: bearer
+  bearerFormat: JWT
+  description: JWT token from /auth/login
+```
+
+### OAuth2
+
+```yaml
+OAuth2:
+  type: oauth2
+  flows:
+    authorizationCode:
+      authorizationUrl: https://auth.example.com/oauth/authorize
+      tokenUrl: https://auth.example.com/oauth/token
+      scopes:
+        read: Read access
+        write: Write access
+```
+
+### Applying Security
+
+```yaml
+# Global (all operations)
+security:
+  - ApiKeyAuth: []
+
+# Per-operation override
+paths:
+  /users:
+    get:
+      security: []  # Public
+    post:
+      security:
+        - BearerAuth: [write]
+```
+
+## Responses
+
+### Success and Error Responses
+
+```yaml
+responses:
+  '200':
+    description: Success
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/User'
+        examples:
+          default:
+            value:
+              id: "550e8400-e29b-41d4-a716-446655440000"
+              email: "user@example.com"
+  '400':
+    description: Bad request
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/Error'
+  '401':
+    description: Unauthorized
+  '404':
+    description: Not found
+  '500':
+    description: Internal server error
+```
+
+## Reusable Components
+
+### Parameters
+
+```yaml
+components:
+  parameters:
+    UserId:
+      name: userId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    PageSize:
+      name: limit
+      in: query
+      schema:
+        type: integer
+        default: 20
+        maximum: 100
+```
+
+### Examples
+
+```yaml
+components:
+  examples:
+    UserExample:
+      summary: Sample user
+      value:
+        id: "550e8400-e29b-41d4-a716-446655440000"
+        email: "jane@example.com"
+        name: "Jane Doe"
+```
+
+## Tags
+
+```yaml
+tags:
+  - name: Users
+    description: User management operations
+  - name: Orders
+    description: Order lifecycle operations
+```
+
+## Deprecation
+
+```yaml
+paths:
+  /v1/legacy/users:
+    deprecated: true
+    get:
+      summary: List users (deprecated)
+      deprecated: true
+      description: Use GET /v2/users instead. Will be removed in v3.
+```

package/skills/qa-browser-data-collector/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: qa-browser-data-collector
+description: Autonomously explore live web applications using Playwright MCP to collect page structure, form fields, validation rules, API endpoints, and user flows for test case generation.
+---
+
+# QA Browser Data Collector
+
+## Purpose
+
+Use Playwright MCP to autonomously explore live web applications and collect structured data for test generation. The skill navigates URLs, captures accessibility snapshots, inspects forms, records network traffic, and maps navigation paths—producing a "UI spec" that feeds into test case generators (e.g., qa-testcase-from-docs, qa-playwright-ts-writer).
+
+## Trigger Phrases
+
+- "Collect data from [URL]" / "Explore [app URL] and gather UI spec"
+- "Capture form fields and validation from [URL]"
+- "Map navigation and API calls for [application]"
+- "Generate UI spec from live app at [URL]"
+- "Browser data collection for test generation"
+- "Explore [URL] and extract page structure, forms, and endpoints"
+
+## Data Collection Workflow
+
+1. **Navigate URLs** — Open target URLs via Playwright MCP; support multiple entry points (home, login, key flows).
+2. **Capture accessibility snapshots** — Use snapshot tools to extract DOM structure, headings, landmarks, interactive elements.
+3. **Collect form fields & validation rules** — Identify inputs, selects, textareas; infer types, required/optional, placeholders, validation patterns.
+4. **Record error messages** — Trigger validation (e.g., submit empty), capture error text, fallback pages, toast/alert messages.
+5. **Capture API endpoints from network** — Intercept or record XHR/fetch requests: endpoints, methods, status codes, payloads.
+6. **Map navigation paths** — Extract links, menus, breadcrumbs, routing patterns; document user flow sequences.
+7. **Screenshot pages** — Capture key screens for visual reference and test traceability.
+8. **Extract state transitions** — Document login/logout, modal open/close, tab switches, conditional visibility.
+
+## Collected Data Types
+
+| Category | Examples |
+|----------|----------|
+| **Page structure** | DOM tree, headings (h1–h6), landmarks (main, nav, aside), ARIA roles |
+| **Forms** | Fields (name, type, placeholder, required/optional), validation rules, submit targets |
+| **Navigation** | Links (href, text), menus, breadcrumbs, routing patterns |
+| **API calls** | Endpoints, HTTP methods, status codes, request/response payloads |
+| **Error handling** | Validation messages, error pages, fallbacks, console errors |
+| **Authentication flows** | Login form, session indicators, token storage, logout paths |
+
+## Output Format
+
+Structured "UI spec" suitable for test case generators:
+
+```json
+{
+  "url": "https://example.com/login",
+  "collectedAt": "ISO8601",
+  "pages": [
+    {
+      "path": "/login",
+      "title": "Sign In",
+      "headings": ["Sign In", "Forgot password?"],
+      "forms": [
+        {
+          "id": "login-form",
+          "fields": [
+            { "name": "email", "type": "email", "required": true },
+            { "name": "password", "type": "password", "required": true }
+          ],
+          "submitButton": "Sign In",
+          "validationMessages": ["Email is required", "Invalid email format"]
+        }
+      ],
+      "links": [...],
+      "apiCalls": [...]
+    }
+  ],
+  "navigationPaths": [...],
+  "authFlow": { "login": "/login", "logout": "/logout" }
+}
+```
+
+Markdown output is also supported for human-readable specs. See `references/data-collection-checklist.md` for a full checklist.
+
+## Scope
+
+**Can do (autonomous):**
+- Navigate to provided URLs and follow links within scope
+- Capture accessibility snapshots and extract structure
+- Inspect forms (fields, types, validation) without submitting real data
+- Record network requests (endpoints, methods, status codes)
+- Map navigation paths and document user flows
+- Take screenshots for reference
+- Produce structured JSON/markdown UI spec
+- Reference `references/data-collection-checklist.md` and `references/playwright-mcp-patterns.md`
+
+**Cannot do (requires confirmation):**
+- Navigate to URLs not explicitly provided
+- Submit forms with real user data (use placeholders/test data only)
+- Access authenticated areas without credentials provided by user
+- Modify app state beyond read-only exploration
+
+**Will not do (out of scope):**
+- **Modify any data in the application** — No form submissions with real data, no create/update/delete actions
+- Execute tests or assertions
+- Generate test code (hand off to qa-playwright-ts-writer or similar)
+- Bypass security or access restricted areas without permission
+
+## Quality Checklist
+
+Before delivering a UI spec:
+
+- [ ] All target URLs explored per user scope
+- [ ] Page structure captured (headings, landmarks, key elements)
+- [ ] Forms documented with field types, required/optional, validation
+- [ ] API endpoints recorded with method, path, and status
+- [ ] Navigation paths mapped (links, menus, flows)
+- [ ] Error/validation messages captured where applicable
+- [ ] Screenshots taken for key pages
+- [ ] Output format valid (JSON or markdown)
+- [ ] No real user data submitted or stored
+- [ ] Scope boundaries respected (no unintended modifications)
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Snapshot empty or incomplete | Page not fully loaded, SPA hydration | Use wait patterns; retry snapshot after load |
+| Forms not detected | Dynamic forms, iframes | Check for iframes; wait for form visibility |
+| API calls not captured | Network interception not active | Ensure network recording started before navigation |
+| Login required | Protected area | Ask user for test credentials or skip authenticated routes |
+| Rate limiting / blocking | Bot detection | Reduce request frequency; use realistic delays |
+| CORS or mixed content | Cross-origin restrictions | Document observed behavior; note limitations |
+| Element refs stale | DOM changed between snapshot and action | Re-snapshot before interaction |
+
+## References
+
+- `references/data-collection-checklist.md` — Checklist of data points to collect per page
+- `references/playwright-mcp-patterns.md` — Common Playwright MCP patterns for data collection

package/skills/qa-browser-data-collector/references/data-collection-checklist.md

@@ -0,0 +1,91 @@
+# Data Collection Checklist
+
+Use this checklist when collecting data from each page during browser exploration. Tick items as they are captured.
+
+## Page Metadata
+
+- [ ] **URL** — Full URL of the page
+- [ ] **Title** — Document title (`<title>`)
+- [ ] **Timestamp** — When the page was captured
+
+## Page Structure
+
+- [ ] **Headings** — h1, h2, h3, h4, h5, h6 (text and hierarchy)
+- [ ] **Landmarks** — main, nav, aside, header, footer, section
+- [ ] **ARIA roles** — role attributes on key containers
+- [ ] **DOM depth** — Notable nesting for key interactive areas
+
+## Forms
+
+- [ ] **Form ID/name** — Form identifier
+- [ ] **Action URL** — Form action (if present)
+- [ ] **Method** — GET or POST
+- [ ] **Fields:**
+  - [ ] Name/label
+  - [ ] Input type (text, email, password, number, checkbox, radio, select, textarea)
+  - [ ] Required vs optional
+  - [ ] Placeholder text
+  - [ ] Validation attributes (min, max, pattern, maxlength)
+  - [ ] Autocomplete hints
+- [ ] **Submit button** — Text and selector
+- [ ] **Validation messages** — Trigger validation and capture error text
+
+## Links
+
+- [ ] **Internal links** — href, link text, destination
+- [ ] **External links** — href, link text (for documentation)
+- [ ] **Navigation menu items** — Structure and labels
+- [ ] **Breadcrumbs** — If present, full path
+
+## Buttons
+
+- [ ] **Primary actions** — Text, type (button/submit), associated form
+- [ ] **Secondary actions** — Cancel, back, etc.
+- [ ] **Icon buttons** — aria-label or title for accessibility
+
+## Images
+
+- [ ] **Decorative images** — Count and context
+- [ ] **Content images** — alt text, src (for traceability)
+- [ ] **Lazy-loaded images** — Note loading behavior
+
+## Tables
+
+- [ ] **Table structure** — Headers, rows, columns
+- [ ] **Sortable columns** — If applicable
+- [ ] **Row actions** — Edit, delete, view links
+- [ ] **Pagination** — Controls and behavior
+
+## Modals & Dialogs
+
+- [ ] **Modal triggers** — Buttons/links that open modals
+- [ ] **Modal content** — Title, body, form fields
+- [ ] **Close behavior** — Close button, overlay click, Escape
+- [ ] **Confirm/Cancel** — Button labels and actions
+
+## Network Requests
+
+- [ ] **XHR/Fetch** — Endpoint, method, status code
+- [ ] **Request payload** — Structure (not sensitive values)
+- [ ] **Response structure** — Key fields for assertions
+- [ ] **WebSocket** — If applicable, connection URL and message types
+
+## Console & Errors
+
+- [ ] **Console errors** — JavaScript errors on load
+- [ ] **Console warnings** — Notable warnings
+- [ ] **404 or error pages** — Structure of error fallbacks
+
+## State & Transitions
+
+- [ ] **Authentication state** — Logged in vs logged out indicators
+- [ ] **Conditional visibility** — Elements that appear based on state
+- [ ] **Tab/accordion state** — Default open/closed
+- [ ] **Loading states** — Spinners, skeletons, disabled buttons
+
+## Screenshots
+
+- [ ] **Full page** — For key pages
+- [ ] **Above-the-fold** — Initial viewport
+- [ ] **Modals** — When open (if applicable)
+- [ ] **Error states** — Validation or error page captures