agile-context-engineering 0.5.0 → 0.5.1

package/skills/map-system/templates/testing-framework.xml

@@ -1,283 +1,283 @@
-<!-- Credits: Testing template content adapted from GSD (Get Shit Done) by @raisiqueira -->
-<!-- Original source: .gsd/get-shit-done/templates/codebase/testing.md -->
-
-<testing-framework>
-    <purpose>
-        Template for `.docs/wiki/testing-framework.md` — captures test framework, patterns, and
-        conventions for the project. Answers "How do I write and run tests that match existing patterns?"
-
-        **Purpose:** Document how tests are written and run. Guide for adding tests that match
-        existing patterns.
-    </purpose>
-
-    <template>
-        <test-framework>
-            ## Test Framework
-
-            **Runner:**
-            - [Framework: e.g., "Jest 29.x", "Vitest 1.x"]
-            - [Config: e.g., "jest.config.js in project root"]
-
-            **Assertion Library:**
-            - [Library: e.g., "built-in expect", "chai"]
-            - [Matchers: e.g., "toBe, toEqual, toThrow"]
-
-            **Run Commands:**
-            ```bash
-            [e.g., "npm test" or "npm run test"]              # Run all tests
-            [e.g., "npm test -- --watch"]                     # Watch mode
-            [e.g., "npm test -- path/to/file.test.ts"]       # Single file
-            [e.g., "npm run test:coverage"]                   # Coverage report
-            ```
-        </test-framework>
-
-        <test-file-organization>
-            ## Test File Organization
-
-            **Location:**
-            - [Pattern: e.g., "*.test.ts alongside source files"]
-            - [Alternative: e.g., "__tests__/ directory" or "separate tests/ tree"]
-
-            **Naming:**
-            - [Unit tests: e.g., "module-name.test.ts"]
-            - [Integration: e.g., "feature-name.integration.test.ts"]
-            - [E2E: e.g., "user-flow.e2e.test.ts"]
-
-            **Structure:**
-            ```
-            [Show actual directory pattern, e.g.:
-            src/
-              lib/
-                utils.ts
-                utils.test.ts
-              services/
-                user-service.ts
-                user-service.test.ts
-            ]
-            ```
-        </test-file-organization>
-
-        <test-structure>
-            ## Test Structure
-
-            **Suite Organization:**
-            ```typescript
-            [Show actual pattern used, e.g.:
-
-            describe('ModuleName', () => {
-              describe('functionName', () => {
-                it('should handle success case', () => {
-                  // arrange
-                  // act
-                  // assert
-                });
-
-                it('should handle error case', () => {
-                  // test code
-                });
-              });
-            });
-            ]
-            ```
-
-            **Patterns:**
-            - [Setup: e.g., "beforeEach for shared setup, avoid beforeAll"]
-            - [Teardown: e.g., "afterEach to clean up, restore mocks"]
-            - [Structure: e.g., "arrange/act/assert pattern required"]
-        </test-structure>
-
-        <mocking>
-            ## Mocking
-
-            **Framework:**
-            - [Tool: e.g., "Jest built-in mocking", "Vitest vi", "Sinon"]
-            - [Import mocking: e.g., "vi.mock() at top of file"]
-
-            **Patterns:**
-            ```typescript
-            [Show actual mocking pattern, e.g.:
-
-            // Mock external dependency
-            vi.mock('./external-service', () => ({
-              fetchData: vi.fn()
-            }));
-
-            // Mock in test
-            const mockFetch = vi.mocked(fetchData);
-            mockFetch.mockResolvedValue({ data: 'test' });
-            ]
-            ```
-
-            **What to Mock:**
-            - [e.g., "External APIs, file system, database"]
-            - [e.g., "Time/dates (use vi.useFakeTimers)"]
-            - [e.g., "Network calls (use mock fetch)"]
-
-            **What NOT to Mock:**
-            - [e.g., "Pure functions, utilities"]
-            - [e.g., "Internal business logic"]
-        </mocking>
-
-        <fixtures-and-factories>
-            ## Fixtures and Factories
-
-            **Test Data:**
-            ```typescript
-            [Show pattern for creating test data, e.g.:
-
-            // Factory pattern
-            function createTestUser(overrides?: Partial&lt;User&gt;): User {
-              return {
-                id: 'test-id',
-                name: 'Test User',
-                email: 'test@example.com',
-                ...overrides
-              };
-            }
-
-            // Fixture file
-            // tests/fixtures/users.ts
-            export const mockUsers = [/* ... */];
-            ]
-            ```
-
-            **Location:**
-            - [e.g., "tests/fixtures/ for shared fixtures"]
-            - [e.g., "factory functions in test file or tests/factories/"]
-        </fixtures-and-factories>
-
-        <coverage>
-            ## Coverage
-
-            **Requirements:**
-            - [Target: e.g., "80% line coverage", "no specific target"]
-            - [Enforcement: e.g., "CI blocks &lt;80%", "coverage for awareness only"]
-
-            **Configuration:**
-            - [Tool: e.g., "built-in coverage via --coverage flag"]
-            - [Exclusions: e.g., "exclude *.test.ts, config files"]
-
-            **View Coverage:**
-            ```bash
-            [e.g., "npm run test:coverage"]
-            [e.g., "open coverage/index.html"]
-            ```
-        </coverage>
-
-        <test-types>
-            ## Test Types
-
-            **Unit Tests:**
-            - [Scope: e.g., "test single function/class in isolation"]
-            - [Mocking: e.g., "mock all external dependencies"]
-            - [Speed: e.g., "must run in &lt;1s per test"]
-
-            **Integration Tests:**
-            - [Scope: e.g., "test multiple modules together"]
-            - [Mocking: e.g., "mock external services, use real internal modules"]
-            - [Setup: e.g., "use test database, seed data"]
-
-            **E2E Tests:**
-            - [Framework: e.g., "Playwright for E2E"]
-            - [Scope: e.g., "test full user flows"]
-            - [Location: e.g., "e2e/ directory separate from unit tests"]
-        </test-types>
-
-        <common-patterns>
-            ## Common Patterns
-
-            **Async Testing:**
-            ```typescript
-            [Show pattern, e.g.:
-
-            it('should handle async operation', async () => {
-              const result = await asyncFunction();
-              expect(result).toBe('expected');
-            });
-            ]
-            ```
-
-            **Error Testing:**
-            ```typescript
-            [Show pattern, e.g.:
-
-            it('should throw on invalid input', () => {
-              expect(() => functionCall()).toThrow('error message');
-            });
-
-            // Async error
-            it('should reject on failure', async () => {
-              await expect(asyncCall()).rejects.toThrow('error message');
-            });
-            ]
-            ```
-
-            **Snapshot Testing:**
-            - [Usage: e.g., "for React components only" or "not used"]
-            - [Location: e.g., "__snapshots__/ directory"]
-        </common-patterns>
-    </template>
-
-    <guidelines>
-
-        **What belongs in testing-framework.md:**
-        - Test framework and runner configuration
-        - Test file location and naming patterns
-        - Test structure (describe/it, beforeEach patterns)
-        - Mocking approach and examples
-        - Fixture/factory patterns
-        - Coverage requirements
-        - How to run tests (commands)
-        - Common testing patterns in actual code
-
-        **What does NOT belong here:**
-        - Specific test cases (defer to actual test files)
-        - Technology choices (that's system-architecture.md)
-        - CI/CD setup (that's deployment docs)
-
-        **When filling this template:**
-        - Check package.json scripts for test commands
-        - Find test config file (jest.config.js, vitest.config.ts)
-        - Read 3-5 existing test files to identify patterns
-        - Look for test utilities in tests/ or test-utils/
-        - Check for coverage configuration
-        - Document actual patterns used, not ideal patterns
-
-        **Useful for story planning when:**
-        - Adding new features (write matching tests)
-        - Refactoring (maintain test patterns)
-        - Fixing bugs (add regression tests)
-        - Understanding verification approach
-        - Setting up test infrastructure
-
-        **Analysis approach:**
-        - Check package.json for test framework and scripts
-        - Read test config file for coverage, setup
-        - Examine test file organization (collocated vs separate)
-        - Review 5 test files for patterns (mocking, structure, assertions)
-        - Look for test utilities, fixtures, factories
-        - Note any test types (unit, integration, e2e)
-        - Document commands for running tests
-
-    </guidelines>
-
-    <evolution>
-
-        Update when testing patterns or framework changes.
-
-        **Update triggers:**
-        - Test framework or runner changed (e.g., Jest to Vitest)
-        - Mocking approach changed
-        - New test type introduced (e.g., adding E2E tests)
-        - Coverage requirements changed
-        - Test file organization restructured
-        - New test utilities or factories added
-
-        **NOT an update trigger:**
-        - New test files added following existing patterns
-        - Individual test case additions
-        - Bug fixes in test code
-
-    </evolution>
-
-</testing-framework>
+<!-- Credits: Testing template content adapted from GSD (Get Shit Done) by @raisiqueira -->
+<!-- Original source: .gsd/get-shit-done/templates/codebase/testing.md -->
+
+<testing-framework>
+    <purpose>
+        Template for `.docs/wiki/testing-framework.md` — captures test framework, patterns, and
+        conventions for the project. Answers "How do I write and run tests that match existing patterns?"
+
+        **Purpose:** Document how tests are written and run. Guide for adding tests that match
+        existing patterns.
+    </purpose>
+
+    <template>
+        <test-framework>
+            ## Test Framework
+
+            **Runner:**
+            - [Framework: e.g., "Jest 29.x", "Vitest 1.x"]
+            - [Config: e.g., "jest.config.js in project root"]
+
+            **Assertion Library:**
+            - [Library: e.g., "built-in expect", "chai"]
+            - [Matchers: e.g., "toBe, toEqual, toThrow"]
+
+            **Run Commands:**
+            ```bash
+            [e.g., "npm test" or "npm run test"]              # Run all tests
+            [e.g., "npm test -- --watch"]                     # Watch mode
+            [e.g., "npm test -- path/to/file.test.ts"]       # Single file
+            [e.g., "npm run test:coverage"]                   # Coverage report
+            ```
+        </test-framework>
+
+        <test-file-organization>
+            ## Test File Organization
+
+            **Location:**
+            - [Pattern: e.g., "*.test.ts alongside source files"]
+            - [Alternative: e.g., "__tests__/ directory" or "separate tests/ tree"]
+
+            **Naming:**
+            - [Unit tests: e.g., "module-name.test.ts"]
+            - [Integration: e.g., "feature-name.integration.test.ts"]
+            - [E2E: e.g., "user-flow.e2e.test.ts"]
+
+            **Structure:**
+            ```
+            [Show actual directory pattern, e.g.:
+            src/
+              lib/
+                utils.ts
+                utils.test.ts
+              services/
+                user-service.ts
+                user-service.test.ts
+            ]
+            ```
+        </test-file-organization>
+
+        <test-structure>
+            ## Test Structure
+
+            **Suite Organization:**
+            ```typescript
+            [Show actual pattern used, e.g.:
+
+            describe('ModuleName', () => {
+              describe('functionName', () => {
+                it('should handle success case', () => {
+                  // arrange
+                  // act
+                  // assert
+                });
+
+                it('should handle error case', () => {
+                  // test code
+                });
+              });
+            });
+            ]
+            ```
+
+            **Patterns:**
+            - [Setup: e.g., "beforeEach for shared setup, avoid beforeAll"]
+            - [Teardown: e.g., "afterEach to clean up, restore mocks"]
+            - [Structure: e.g., "arrange/act/assert pattern required"]
+        </test-structure>
+
+        <mocking>
+            ## Mocking
+
+            **Framework:**
+            - [Tool: e.g., "Jest built-in mocking", "Vitest vi", "Sinon"]
+            - [Import mocking: e.g., "vi.mock() at top of file"]
+
+            **Patterns:**
+            ```typescript
+            [Show actual mocking pattern, e.g.:
+
+            // Mock external dependency
+            vi.mock('./external-service', () => ({
+              fetchData: vi.fn()
+            }));
+
+            // Mock in test
+            const mockFetch = vi.mocked(fetchData);
+            mockFetch.mockResolvedValue({ data: 'test' });
+            ]
+            ```
+
+            **What to Mock:**
+            - [e.g., "External APIs, file system, database"]
+            - [e.g., "Time/dates (use vi.useFakeTimers)"]
+            - [e.g., "Network calls (use mock fetch)"]
+
+            **What NOT to Mock:**
+            - [e.g., "Pure functions, utilities"]
+            - [e.g., "Internal business logic"]
+        </mocking>
+
+        <fixtures-and-factories>
+            ## Fixtures and Factories
+
+            **Test Data:**
+            ```typescript
+            [Show pattern for creating test data, e.g.:
+
+            // Factory pattern
+            function createTestUser(overrides?: Partial&lt;User&gt;): User {
+              return {
+                id: 'test-id',
+                name: 'Test User',
+                email: 'test@example.com',
+                ...overrides
+              };
+            }
+
+            // Fixture file
+            // tests/fixtures/users.ts
+            export const mockUsers = [/* ... */];
+            ]
+            ```
+
+            **Location:**
+            - [e.g., "tests/fixtures/ for shared fixtures"]
+            - [e.g., "factory functions in test file or tests/factories/"]
+        </fixtures-and-factories>
+
+        <coverage>
+            ## Coverage
+
+            **Requirements:**
+            - [Target: e.g., "80% line coverage", "no specific target"]
+            - [Enforcement: e.g., "CI blocks &lt;80%", "coverage for awareness only"]
+
+            **Configuration:**
+            - [Tool: e.g., "built-in coverage via --coverage flag"]
+            - [Exclusions: e.g., "exclude *.test.ts, config files"]
+
+            **View Coverage:**
+            ```bash
+            [e.g., "npm run test:coverage"]
+            [e.g., "open coverage/index.html"]
+            ```
+        </coverage>
+
+        <test-types>
+            ## Test Types
+
+            **Unit Tests:**
+            - [Scope: e.g., "test single function/class in isolation"]
+            - [Mocking: e.g., "mock all external dependencies"]
+            - [Speed: e.g., "must run in &lt;1s per test"]
+
+            **Integration Tests:**
+            - [Scope: e.g., "test multiple modules together"]
+            - [Mocking: e.g., "mock external services, use real internal modules"]
+            - [Setup: e.g., "use test database, seed data"]
+
+            **E2E Tests:**
+            - [Framework: e.g., "Playwright for E2E"]
+            - [Scope: e.g., "test full user flows"]
+            - [Location: e.g., "e2e/ directory separate from unit tests"]
+        </test-types>
+
+        <common-patterns>
+            ## Common Patterns
+
+            **Async Testing:**
+            ```typescript
+            [Show pattern, e.g.:
+
+            it('should handle async operation', async () => {
+              const result = await asyncFunction();
+              expect(result).toBe('expected');
+            });
+            ]
+            ```
+
+            **Error Testing:**
+            ```typescript
+            [Show pattern, e.g.:
+
+            it('should throw on invalid input', () => {
+              expect(() => functionCall()).toThrow('error message');
+            });
+
+            // Async error
+            it('should reject on failure', async () => {
+              await expect(asyncCall()).rejects.toThrow('error message');
+            });
+            ]
+            ```
+
+            **Snapshot Testing:**
+            - [Usage: e.g., "for React components only" or "not used"]
+            - [Location: e.g., "__snapshots__/ directory"]
+        </common-patterns>
+    </template>
+
+    <guidelines>
+
+        **What belongs in testing-framework.md:**
+        - Test framework and runner configuration
+        - Test file location and naming patterns
+        - Test structure (describe/it, beforeEach patterns)
+        - Mocking approach and examples
+        - Fixture/factory patterns
+        - Coverage requirements
+        - How to run tests (commands)
+        - Common testing patterns in actual code
+
+        **What does NOT belong here:**
+        - Specific test cases (defer to actual test files)
+        - Technology choices (that's system-architecture.md)
+        - CI/CD setup (that's deployment docs)
+
+        **When filling this template:**
+        - Check package.json scripts for test commands
+        - Find test config file (jest.config.js, vitest.config.ts)
+        - Read 3-5 existing test files to identify patterns
+        - Look for test utilities in tests/ or test-utils/
+        - Check for coverage configuration
+        - Document actual patterns used, not ideal patterns
+
+        **Useful for story planning when:**
+        - Adding new features (write matching tests)
+        - Refactoring (maintain test patterns)
+        - Fixing bugs (add regression tests)
+        - Understanding verification approach
+        - Setting up test infrastructure
+
+        **Analysis approach:**
+        - Check package.json for test framework and scripts
+        - Read test config file for coverage, setup
+        - Examine test file organization (collocated vs separate)
+        - Review 5 test files for patterns (mocking, structure, assertions)
+        - Look for test utilities, fixtures, factories
+        - Note any test types (unit, integration, e2e)
+        - Document commands for running tests
+
+    </guidelines>
+
+    <evolution>
+
+        Update when testing patterns or framework changes.
+
+        **Update triggers:**
+        - Test framework or runner changed (e.g., Jest to Vitest)
+        - Mocking approach changed
+        - New test type introduced (e.g., adding E2E tests)
+        - Coverage requirements changed
+        - Test file organization restructured
+        - New test utilities or factories added
+
+        **NOT an update trigger:**
+        - New test files added following existing patterns
+        - Individual test case additions
+        - Bug fixes in test code
+
+    </evolution>
+
+</testing-framework>