specweave 0.23.18 → 0.24.0

package/plugins/specweave-testing/agents/qa-engineer/README.md

@@ -0,0 +1,443 @@
+# QA Engineer Agent
+
+## Overview
+
+The QA Engineer agent is a specialized AI agent designed to help with test strategy, test planning, test automation, and comprehensive quality assurance for modern software projects.
+
+## When to Use This Agent
+
+Invoke this agent when you need:
+
+- **Test Strategy**: Design comprehensive testing approaches (unit, integration, E2E)
+- **Test Planning**: Break down features into testable scenarios
+- **Test Automation**: Set up Playwright, Vitest, Cypress, or other testing frameworks
+- **TDD Workflow**: Implement test-driven development practices
+- **Quality Gates**: Define coverage thresholds and quality metrics
+- **Performance Testing**: Load testing, stress testing, benchmarking
+- **Accessibility Testing**: WCAG compliance, a11y automation
+- **Security Testing**: Vulnerability scanning, penetration testing
+- **CI/CD Integration**: Automated testing in pipelines
+- **Test Maintenance**: Refactor flaky tests, improve test reliability
+
+## How to Invoke
+
+Use the Task tool with `subagent_type`:
+
+```typescript
+Task({
+  subagent_type: "specweave-testing:qa-engineer:qa-engineer",
+  prompt: "Design a comprehensive test strategy for a React e-commerce application with Vitest unit tests, Playwright E2E tests, and accessibility testing"
+});
+```
+
+## Agent Capabilities
+
+### 1. Testing Frameworks
+
+**JavaScript/TypeScript**:
+- Vitest for unit and integration testing
+- Playwright for cross-browser E2E testing
+- Cypress for browser automation
+- Testing Library (React, Vue, Angular)
+- MSW (Mock Service Worker) for API mocking
+- Jest with modern features
+
+**Other Languages**:
+- pytest (Python) with fixtures
+- JUnit 5 (Java) with Mockito
+- RSpec (Ruby) with factories
+- Go testing package with testify
+
+**Specialized Testing**:
+- Percy/Chromatic for visual regression
+- axe-core for accessibility
+- k6 for load testing
+- OWASP ZAP for security
+
+### 2. Testing Strategies
+
+**Testing Pyramid**:
+- Unit Tests (70%): Fast, isolated, single responsibility
+- Integration Tests (20%): Module interactions, API contracts
+- E2E Tests (10%): Critical user journeys
+
+**Test-Driven Development (TDD)**:
+- Red-Green-Refactor cycle
+- Behavior-driven naming
+- Design through tests
+- Refactoring safety net
+
+**Behavior-Driven Development (BDD)**:
+- Given-When-Then format
+- Cucumber/Gherkin syntax
+- Living documentation
+- Stakeholder-readable tests
+
+### 3. Test Coverage & Quality
+
+- Code coverage (line, branch, statement, function)
+- Mutation testing (Stryker)
+- Risk-based prioritization
+- Boundary value analysis
+- State transition testing
+- Quality gates and thresholds
+
+### 4. Test Organization
+
+- AAA pattern (Arrange-Act-Assert)
+- Page Object Model (POM) for E2E
+- Test fixtures and factories
+- Tagging and categorization
+- Parallel test execution
+- Test data management
+
+### 5. CI/CD Integration
+
+- GitHub Actions workflows
+- GitLab CI pipelines
+- Pre-commit hooks (Husky)
+- Pull request checks
+- Automated regression runs
+- Test result reporting
+
+## Common Use Cases
+
+### 1. Design Test Strategy
+
+**Prompt**:
+```
+"Design a test strategy for a Next.js SaaS application with:
+- User authentication (OAuth, email/password)
+- Real-time dashboard with WebSocket
+- Payment processing (Stripe)
+- Admin panel with RBAC
+- Multi-tenancy support
+
+Target: 80%+ code coverage, < 5 min test execution, zero flaky tests"
+```
+
+**What the agent provides**:
+- Testing pyramid breakdown
+- Framework selection (Vitest, Playwright, etc.)
+- Coverage targets per layer
+- Test data management strategy
+- CI/CD integration plan
+- Quality gates definition
+
+### 2. Implement Unit Tests
+
+**Prompt**:
+```
+"Set up Vitest for a TypeScript React project with:
+- Unit tests for custom hooks
+- Component tests with Testing Library
+- API mocking with MSW
+- Coverage thresholds (80%+ lines, 75%+ branches)
+- Watch mode for development
+- CI integration"
+```
+
+**What the agent provides**:
+- Vitest configuration
+- Test file structure
+- Mock setup examples
+- Coverage configuration
+- CI workflow YAML
+- Best practices documentation
+
+### 3. Implement E2E Tests
+
+**Prompt**:
+```
+"Set up Playwright E2E tests for an e-commerce checkout flow:
+- Product search and filtering
+- Add to cart
+- Checkout with guest and authenticated users
+- Payment processing (test mode)
+- Order confirmation
+
+Cross-browser testing (Chrome, Firefox, Safari)
+Mobile emulation (iPhone, Android)
+Visual regression testing
+Parallel execution"
+```
+
+**What the agent provides**:
+- Playwright configuration
+- Page Object Model architecture
+- Test fixtures for authentication
+- API mocking strategies
+- Visual regression setup
+- Parallelization strategy
+
+### 4. Implement TDD Workflow
+
+**Prompt**:
+```
+"Guide me through TDD for implementing a shopping cart feature:
+- Add item to cart
+- Remove item from cart
+- Update quantity
+- Calculate total with tax
+- Apply discount code
+
+Use Vitest, follow red-green-refactor strictly"
+```
+
+**What the agent provides**:
+- Step-by-step TDD cycle
+- Failing test examples (RED)
+- Minimal implementation (GREEN)
+- Refactoring strategies
+- Test-first design patterns
+- Best practices checklist
+
+### 5. Accessibility Testing
+
+**Prompt**:
+```
+"Set up automated accessibility testing for a React application:
+- WCAG AA compliance
+- axe-core integration in Vitest
+- Playwright accessibility assertions
+- Keyboard navigation tests
+- Screen reader compatibility
+- Color contrast validation
+
+Target: Lighthouse accessibility score 95+"
+```
+
+**What the agent provides**:
+- axe-core setup with Vitest
+- Playwright accessibility tests
+- Keyboard navigation test examples
+- Manual testing checklist
+- WCAG compliance guide
+- Accessibility audit process
+
+### 6. Performance Testing
+
+**Prompt**:
+```
+"Set up performance testing for a REST API:
+- Load testing (1000 concurrent users)
+- Stress testing (find breaking point)
+- Soak testing (24 hour sustained load)
+- Metrics: p50, p95, p99 response times
+
+Use k6, integrate with CI/CD, track trends"
+```
+
+**What the agent provides**:
+- k6 test scripts
+- Load testing scenarios
+- Performance thresholds
+- CI integration (GitHub Actions)
+- Grafana dashboard setup
+- Performance budget definition
+
+## Example Workflows
+
+### Workflow 1: TDD Feature Development
+
+1. **Write Failing Test (RED)**: Define expected behavior
+2. **Implement Minimally (GREEN)**: Make test pass
+3. **Refactor**: Improve code quality
+4. **Repeat**: Next requirement
+
+### Workflow 2: E2E Test Setup
+
+1. **Install Playwright**: `npm install -D @playwright/test`
+2. **Configure**: Browser setup, base URL, screenshots
+3. **Create Page Objects**: Reusable page interactions
+4. **Write Tests**: Critical user journeys
+5. **CI Integration**: Run on every PR
+6. **Monitor**: Track flakiness and execution time
+
+### Workflow 3: Quality Audit
+
+1. **Analyze Coverage**: Identify gaps
+2. **Review Test Quality**: Flaky tests, slow tests
+3. **Refactor**: Improve reliability
+4. **Set Thresholds**: Enforce quality gates
+5. **Monitor**: Track metrics over time
+
+## Input Format
+
+The agent expects a clear, specific prompt describing:
+
+1. **Context**: What are you testing? What technology stack?
+2. **Requirements**: What features need tests?
+3. **Quality Targets**: Coverage %, performance, accessibility
+4. **Constraints**: Team size, timeline, CI/CD platform
+
+**Good prompt**:
+```
+"Design test strategy for Node.js REST API with:
+- 50+ endpoints (CRUD operations)
+- Authentication (JWT)
+- Rate limiting
+- PostgreSQL database
+- Redis caching
+
+Stack: TypeScript, Express, Prisma
+Target: 85%+ coverage, < 2 min test execution
+CI: GitHub Actions
+Team: 5 developers, all familiar with Jest"
+```
+
+**Poor prompt**:
+```
+"Need tests for my API"
+```
+
+## Output Format
+
+The agent provides:
+
+1. **Test Strategy**: High-level approach and distribution
+2. **Framework Setup**: Configuration files and installation
+3. **Test Examples**: Code samples for each test type
+4. **Best Practices**: Patterns and anti-patterns
+5. **CI/CD Integration**: Workflow files
+6. **Quality Metrics**: Coverage targets, thresholds
+7. **Documentation**: Testing guidelines for team
+
+## Best Practices
+
+### 1. Test Behavior, Not Implementation
+Focus on what code does, not how it does it.
+
+### 2. Independent Tests
+No shared state between tests.
+
+### 3. Fast Feedback
+Unit tests should run in seconds.
+
+### 4. Readable Tests
+Self-documenting test names and structure.
+
+### 5. Maintainable Tests
+Page Object Model, fixtures, utilities.
+
+### 6. Realistic Tests
+Test against production-like environment.
+
+### 7. Coverage Targets
+80%+ code coverage, 100% critical paths.
+
+### 8. Flakiness Zero Tolerance
+Fix or quarantine flaky tests immediately.
+
+## Integration with SpecWeave
+
+### Use with /specweave:increment
+
+When planning a feature increment:
+
+```bash
+# 1. Plan increment
+/specweave:increment "Implement user authentication with OAuth"
+
+# 2. Generate test strategy
+Task({
+  subagent_type: "specweave-testing:qa-engineer:qa-engineer",
+  prompt: "Design test strategy for OAuth authentication with Google, GitHub, and email/password. Include unit tests for auth logic, integration tests for OAuth flow, and E2E tests for complete user journey."
+});
+
+# 3. Implement with TDD
+/specweave:do
+```
+
+### Use with /specweave:qa
+
+After implementation, validate test coverage:
+
+```bash
+# Run quality assessment
+/specweave:qa 0123
+
+# Agent checks:
+# - Test coverage (lines, branches, functions)
+# - Test quality (independent, fast, readable)
+# - Critical path coverage
+# - E2E test completeness
+# - Accessibility test coverage
+```
+
+## Troubleshooting
+
+### Issue: Flaky tests
+
+**Solution**:
+- Use proper wait strategies (no hardcoded delays)
+- Isolate test data
+- Mock external dependencies
+- Use fake timers for time-based code
+
+### Issue: Slow tests
+
+**Solution**:
+- Mock expensive operations (DB, API, file I/O)
+- Use fake timers
+- Run tests in parallel
+- Profile slow tests
+
+### Issue: Low coverage
+
+**Solution**:
+- Identify untested paths
+- Add tests for edge cases
+- Test error handling
+- Use mutation testing to find weak tests
+
+## Advanced Usage
+
+### Contract Testing
+
+```typescript
+Task({
+  subagent_type: "specweave-testing:qa-engineer:qa-engineer",
+  prompt: `Set up Pact contract testing between:
+    - Frontend (React SPA)
+    - Backend API (Node.js)
+    - Third-party payment API (Stripe)
+
+    Ensure API compatibility across teams`
+});
+```
+
+### Visual Regression Testing
+
+```typescript
+Task({
+  subagent_type: "specweave-testing:qa-engineer:qa-engineer",
+  prompt: `Set up visual regression testing with Percy for:
+    - 20+ pages across 3 breakpoints (mobile, tablet, desktop)
+    - 5+ themes (light, dark, high-contrast)
+    - Component library (Storybook integration)
+
+    CI integration, baseline management`
+});
+```
+
+## Resources
+
+- **Vitest Docs**: https://vitest.dev
+- **Playwright Docs**: https://playwright.dev
+- **Testing Library**: https://testing-library.com
+- **TDD Guide**: https://martinfowler.com/bliki/TestDrivenDevelopment.html
+- **Testing Best Practices**: https://testingjavascript.com
+
+## Version History
+
+- **v1.0.0** (2025-01-22): Initial release with Vitest, Playwright, TDD expertise
+- **v1.1.0** (TBD): Add mobile testing support (Appium, Detox)
+- **v1.2.0** (TBD): Add chaos engineering guidance
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/anton-abyzov/specweave/issues
+- Discord: https://discord.gg/specweave
+- Documentation: https://spec-weave.com