@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/standards/8-testing-documentation-standards.md

@@ -0,0 +1,401 @@
+# Testing & Documentation Standards
+
+**🤖 Cursor Rule**: See [08-testing-documentation.mdc](../../cursor-rules/08-testing-documentation.mdc) for AI-optimized directives that automatically enforce testing and documentation standards.
+
+## Purpose
+
+This standard defines testing strategies, documentation requirements, and issue reporting templates to ensure consistent quality, maintainability, and effective communication across pace-core and consuming apps.
+
+---
+
+## Testing Strategy
+
+### Test Types
+
+**MUST** use this testing strategy:
+
+- **Unit tests** - For utils & hooks (≥90% coverage)
+- **Integration tests** - For components (≥70% coverage)
+- **Few meaningful E2E tests** - In consuming apps only (critical user flows)
+
+### Test Structure
+
+**MUST** colocate tests with source files:
+
+```
+src/
+├── components/
+│   └── events/
+│       ├── EventCard.tsx
+│       └── EventCard.test.tsx        # ✅ Colocated
+│
+├── hooks/
+│   ├── useEventData.ts
+│   └── useEventData.test.ts           # ✅ Colocated
+│
+└── utils/
+    ├── formatEvent.ts
+    └── formatEvent.test.ts            # ✅ Colocated
+```
+
+### Test File Naming
+
+- Unit tests: `*.test.ts` or `*.test.tsx`
+- Integration tests: `*.integration.test.ts`
+- E2E tests: Place in `tests/` directory
+
+### Testing Tools
+
+**MUST** use:
+
+- **React Testing Library** - For component testing
+- **userEvent** - For user interaction simulation
+- **Vitest** - For test runner
+- **Avoid unnecessary mocks** - Prefer real implementations when possible
+
+### Test Timeouts
+
+**MUST** configure timeouts for all test commands to prevent tests from hanging indefinitely.
+
+**Recommended Configuration:**
+
+**Option 1: Configure in `vitest.config.ts` (Recommended)**
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    testTimeout: 10000,        // 10 seconds per test
+    hookTimeout: 10000,         // 10 seconds for hooks
+    teardownTimeout: 5000,      // 5 seconds for cleanup
+  },
+});
+```
+
+**Option 2: Configure in `package.json` scripts (Alternative)**
+```json
+{
+  "scripts": {
+    "test": "vitest run --test-timeout=10000",
+    "test:watch": "vitest --test-timeout=10000",
+    "test:coverage": "vitest run --coverage --test-timeout=10000"
+  }
+}
+```
+
+**Recommended Timeout Values:**
+- **Unit tests**: 5-10 seconds (most tests should complete in < 1 second)
+- **Integration tests**: 10-15 seconds (may involve async operations)
+- **E2E tests**: 30-60 seconds (may involve network requests)
+
+**Why:** Tests in this project have issues with hanging and require manual cancellation without timeouts. Always configure timeouts to prevent CI/CD pipelines from hanging indefinitely.
+
+**Example:**
+```typescript
+// ✅ CORRECT - Test with explicit timeout for slow operations
+import { describe, it, expect, vi } from 'vitest';
+
+describe('Slow API call', () => {
+  it('should complete within timeout', async () => {
+    const result = await slowApiCall();
+    expect(result).toBeDefined();
+  }, 15000); // 15 second timeout for this specific test
+});
+```
+
+### Example Test
+
+```typescript
+// src/components/events/EventCard.test.tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { EventCard } from './EventCard';
+
+describe('EventCard', () => {
+  it('renders event title', () => {
+    const event = { id: '1', name: 'Test Event', date: new Date() };
+    render(<EventCard event={event} />);
+    expect(screen.getByText('Test Event')).toBeInTheDocument();
+  });
+
+  it('handles click interaction', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    const event = { id: '1', name: 'Test Event', date: new Date() };
+    
+    render(<EventCard event={event} onClick={handleClick} />);
+    await user.click(screen.getByRole('button'));
+    
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Test Coverage Requirements
+
+- **Utils & Hooks**: ≥90% coverage
+- **Components**: ≥70% coverage
+- **Critical paths**: 100% coverage (authentication, payments, etc.)
+
+---
+
+## Documentation Requirements
+
+### Purpose
+
+Documentation ensures code is maintainable, understandable, and usable. All documentation MUST follow these standards.
+
+### When to Document
+
+**MUST document:**
+- New components, hooks, utilities, or APIs
+- Breaking changes to existing APIs
+- Complex business logic or algorithms
+- Non-obvious implementation decisions
+- Configuration requirements
+- Migration paths for breaking changes
+
+**SHOULD document:**
+- Public APIs and their usage
+- Component props and behavior
+- Hook return values and dependencies
+- Utility function parameters and return types
+- Error conditions and handling
+
+**MAY document:**
+- Internal implementation details (if helpful)
+- Performance considerations
+- Future plans or limitations
+
+### Documentation Structure
+
+**Every component/API documentation MUST include:**
+
+1. **Overview** - What it does and when to use it
+2. **API/Props** - Complete prop/parameter definitions with types
+3. **Examples** - Real-world usage examples
+4. **Accessibility (A11y)** - Accessibility considerations and requirements
+5. **Edge Cases** - Known limitations, error conditions, and special cases
+
+**Example Structure:**
+
+```markdown
+# ComponentName
+
+## Overview
+Brief description of what the component does and when to use it.
+
+## API
+
+### Props
+- `propName` (type): Description
+- `optionalProp?` (type): Description (default: value)
+
+## Examples
+
+### Basic Usage
+\`\`\`tsx
+<ComponentName prop="value" />
+\`\`\`
+
+### Advanced Usage
+\`\`\`tsx
+<ComponentName prop="value" optionalProp="optional" />
+\`\`\`
+
+## Accessibility
+- Keyboard navigation: Supported
+- Screen readers: Announced as...
+- Focus management: ...
+
+## Edge Cases
+- Handles null/undefined: Yes/No
+- Error conditions: ...
+- Performance considerations: ...
+```
+
+### Documentation Formats
+
+**Component Documentation:**
+- Location: `packages/core/docs/api-reference/components.md` or component-specific README
+- Format: Markdown with code examples
+- Must include: Overview, Props, Examples, A11y, Edge Cases
+
+**API Documentation:**
+- Location: `packages/core/docs/api-reference/`
+- Format: TypeScript types + Markdown descriptions
+- Must include: Function signatures, Parameters, Return types, Examples
+
+**Implementation Guides:**
+- Location: `packages/core/docs/implementation-guides/`
+- Format: Step-by-step guides with examples
+- Must include: Overview, Step-by-step instructions, Code examples, Troubleshooting
+
+**Standards Documentation:**
+- Location: `packages/core/docs/standards/`
+- Format: Markdown with examples and checklists
+- Must include: Purpose, Requirements, Examples, Checklists
+
+### Documentation Maintenance
+
+**MUST update documentation when:**
+- Adding new props/parameters
+- Changing behavior (breaking or non-breaking)
+- Fixing bugs that change user-facing behavior
+- Deprecating features
+
+**SHOULD update documentation when:**
+- Improving examples
+- Adding new use cases
+- Clarifying edge cases
+
+**Update Process:**
+1. Update code and tests first
+2. Update documentation to match
+3. Verify examples still work
+4. Update related documentation if needed
+
+### Documentation Quality Checklist
+
+Before committing documentation, verify:
+
+- [ ] Overview clearly explains purpose and usage
+- [ ] All props/parameters documented with types
+- [ ] Examples are complete and working
+- [ ] Accessibility considerations documented
+- [ ] Edge cases and limitations documented
+- [ ] Code examples are syntax-highlighted
+- [ ] Links to related documentation included
+- [ ] Breaking changes have migration guides
+- [ ] Documentation matches actual implementation
+
+---
+
+## Bug Reports
+
+### Bug Report Template
+
+**MUST** use this template when reporting bugs:
+
+```markdown
+## Description
+Clear description of the bug and expected vs actual behavior.
+
+## Steps to Reproduce
+1. Step one
+2. Step two
+3. Step three
+
+## Minimal Reproduction
+Link to CodeSandbox/StackBlitz or minimal code snippet that reproduces the issue.
+
+## Environment
+- pace-core version: X.X.X
+- React version: X.X.X
+- Node version: X.X.X
+- Browser: Chrome/Firefox/Safari X.X
+- OS: macOS/Windows/Linux
+
+## Error Messages/Logs
+```
+Paste error messages or logs here
+```
+
+## Additional Context
+Screenshots, videos, or other context that helps understand the issue.
+```
+
+### Bug Report Checklist
+
+Before submitting a bug report, verify:
+
+- [ ] Description clearly explains the issue
+- [ ] Steps to reproduce are minimal and ordered
+- [ ] Minimal reproduction provided (link or code)
+- [ ] Environment information complete
+- [ ] Error messages/logs included
+- [ ] Additional context provided if helpful
+
+---
+
+## Feature Requests
+
+### Feature Request Template
+
+**MUST** use this template when requesting features:
+
+```markdown
+## Feature Description
+Clear description of the feature and the problem it solves.
+
+## Proposed Solution/API
+Description of how the feature should work, including API design if applicable.
+
+## Use Case
+Real-world scenario where this feature would be useful.
+
+## Alternatives Considered
+Other approaches you've considered and why they don't work.
+
+## Example Code
+\`\`\`tsx
+// Example of how the feature would be used
+<NewComponent prop="value" />
+\`\`\`
+
+## Additional Context
+Mockups, diagrams, or other context that helps understand the feature.
+```
+
+### Feature Request Checklist
+
+Before submitting a feature request, verify:
+
+- [ ] Feature description is clear
+- [ ] Problem statement is well-defined
+- [ ] Proposed solution/API is described
+- [ ] Use case with real scenario provided
+- [ ] Alternatives considered and documented
+- [ ] Example code snippet included
+- [ ] Additional context provided if helpful
+
+---
+
+## Testing Checklist
+
+Before committing code with tests, verify:
+
+- [ ] Tests colocated with source files
+- [ ] React Testing Library + userEvent used
+- [ ] Unnecessary mocks avoided
+- [ ] Coverage requirements met (≥90% utils/hooks, ≥70% components)
+- [ ] Critical paths have 100% coverage
+- [ ] Tests are meaningful and test behavior, not implementation
+
+---
+
+## Documentation Checklist
+
+Before committing code with documentation, verify:
+
+- [ ] New components/APIs documented
+- [ ] Breaking changes have migration guides
+- [ ] Examples are complete and working
+- [ ] Accessibility considerations documented
+- [ ] Edge cases documented
+- [ ] Documentation matches implementation
+
+---
+
+## Related Documentation
+
+- [Standards Overview](./0-standards-overview.md) - Standards system overview
+- [Code Quality](./4-code-quality-standards.md) - Code patterns and TypeScript
+- [Architecture](./3-architecture-standards.md) - Component design principles
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 2.0.0  
+**Applies to:** All pace-core and consuming apps