@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/test-tdd-workflow/SKILL.md

@@ -0,0 +1,185 @@
+# Test TDD Workflow
+
+> Drive design through tests using red-green-refactor cycle and test-first discipline
+
+## When to Use
+
+- Implementing new features or fixing bugs with test-first approach
+- Designing APIs by starting from the consumer's perspective
+- Building confidence in code correctness before shipping
+- Refactoring with a safety net of comprehensive tests
+
+## Instructions
+
+1. **Red** — Write a failing test that describes the desired behavior:
+
+```typescript
+describe('PasswordValidator', () => {
+  it('rejects passwords shorter than 8 characters', () => {
+    const result = validatePassword('short');
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Password must be at least 8 characters');
+  });
+});
+```
+
+Run the test — it should fail (function does not exist or returns wrong value).
+
+2. **Green** — Write the minimum code to make the test pass:
+
+```typescript
+function validatePassword(password: string): ValidationResult {
+  const errors: string[] = [];
+  if (password.length < 8) {
+    errors.push('Password must be at least 8 characters');
+  }
+  return { valid: errors.length === 0, errors };
+}
+```
+
+Run the test — it should pass.
+
+3. **Refactor** — Improve the code while keeping tests green:
+
+```typescript
+// Extract rules into a composable structure
+const rules: PasswordRule[] = [
+  { test: (p) => p.length >= 8, message: 'Password must be at least 8 characters' },
+  { test: (p) => /[A-Z]/.test(p), message: 'Password must contain an uppercase letter' },
+];
+
+function validatePassword(password: string): ValidationResult {
+  const errors = rules.filter((r) => !r.test(password)).map((r) => r.message);
+  return { valid: errors.length === 0, errors };
+}
+```
+
+Run all tests — everything should still pass.
+
+4. **Add the next test** and repeat:
+
+```typescript
+it('rejects passwords without uppercase letters', () => {
+  const result = validatePassword('lowercase123');
+  expect(result.valid).toBe(false);
+  expect(result.errors).toContain('Password must contain an uppercase letter');
+});
+
+it('accepts valid passwords', () => {
+  const result = validatePassword('ValidPass123!');
+  expect(result.valid).toBe(true);
+  expect(result.errors).toHaveLength(0);
+});
+```
+
+5. **Use watch mode** for instant feedback:
+
+```bash
+vitest --watch
+```
+
+Tests re-run on every file save, showing red/green status immediately.
+
+6. **Start from the outside** — test the public API first, then drill into internals:
+
+```typescript
+// First: test the public function
+it('creates an order with total', async () => {
+  const order = await createOrder({ items: [{ sku: 'A', qty: 2, price: 10 }] });
+  expect(order.total).toBe(20);
+});
+
+// Then: test edge cases
+it('applies bulk discount for qty > 10', async () => {
+  /* ... */
+});
+it('throws for empty items array', async () => {
+  /* ... */
+});
+```
+
+7. **Write the test name as a specification:**
+
+```typescript
+// Tests serve as living documentation
+describe('ShippingCalculator', () => {
+  it('charges flat $5 for orders under $50', () => {
+    /* ... */
+  });
+  it('provides free shipping for orders over $50', () => {
+    /* ... */
+  });
+  it('uses express rate when expedited shipping is selected', () => {
+    /* ... */
+  });
+  it('throws for negative order totals', () => {
+    /* ... */
+  });
+});
+```
+
+8. **Do not refactor red tests.** If a test is failing, make it pass first. Never change code structure while tests are red.
+
+## Details
+
+TDD is a design technique that uses tests to drive the shape of the code. The core discipline is: never write production code without a failing test that demands it.
+
+**The three rules of TDD:**
+
+1. Write no production code except to pass a failing test
+2. Write only enough test to demonstrate a failure
+3. Write only enough production code to pass the test
+
+**Benefits of TDD:**
+
+- **Design feedback** — if code is hard to test, it is hard to use. TDD surfaces design problems early
+- **Regression safety** — every behavior has a test before the code exists
+- **Documentation** — test names describe what the code does
+- **Confidence** — refactoring is safe because the test suite catches regressions
+
+**When TDD works best:**
+
+- Pure functions and business logic
+- Service layer operations with clear input/output
+- Data validation and transformation
+- Algorithm implementation
+
+**When TDD is harder:**
+
+- UI rendering (use visual tests instead)
+- Integration with external systems (mock the boundary, test integration separately)
+- Performance optimization (write tests first, then optimize)
+
+**Common TDD mistakes:**
+
+- Writing too many tests before any code — leads to over-design
+- Writing production code before the test — breaks the feedback loop
+- Not refactoring after green — accumulates technical debt
+- Testing implementation details — breaks on refactoring
+
+**Trade-offs:**
+
+- TDD produces well-tested code — but takes longer initially
+- Small steps feel slow — but prevent debugging sessions
+- Test-first drives better API design — but requires discipline to maintain
+- Watch mode gives instant feedback — but can be distracting in complex debugging scenarios
+
+## Source
+
+https://vitest.dev/guide/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/test-tdd-workflow/skill.yaml

@@ -0,0 +1,42 @@
+name: test-tdd-workflow
+version: "1.0.0"
+description: Drive design through tests using red-green-refactor cycle and test-first discipline
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "**/*.test.tsx"
+  - "vitest.config.*"
+  - "jest.config.*"
+  - "playwright.config.*"
+related_skills:
+  - test-unit-patterns
+  - test-mock-patterns
+  - test-coverage-patterns
+stack_signals:
+  - vitest
+  - jest
+  - playwright
+  - testing-library
+keywords:
+  - TDD
+  - red-green-refactor
+  - test-first
+  - design-through-tests
+metadata:
+  author: community
+  upstream: vitest.dev/guide/
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/test-unit-patterns/SKILL.md

@@ -0,0 +1,209 @@
+# Test Unit Patterns
+
+> Write focused, isolated unit tests using AAA pattern with describe/it/expect
+
+## When to Use
+
+- Testing individual functions, classes, or modules in isolation
+- Verifying pure logic, calculations, or data transformations
+- Building a fast test suite that runs in milliseconds
+- Following TDD red-green-refactor workflow
+
+## Instructions
+
+1. **Structure tests with AAA** (Arrange, Act, Assert):
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { calculateDiscount } from './pricing';
+
+describe('calculateDiscount', () => {
+  it('applies 10% discount for orders over $100', () => {
+    // Arrange
+    const orderTotal = 150;
+    const discountRate = 0.1;
+
+    // Act
+    const result = calculateDiscount(orderTotal, discountRate);
+
+    // Assert
+    expect(result).toBe(15);
+  });
+});
+```
+
+2. **One assertion per test** (or one logical assertion group):
+
+```typescript
+it('returns the created user with all fields', () => {
+  const user = createUser({ name: 'Alice', email: 'alice@test.com' });
+
+  expect(user).toMatchObject({
+    name: 'Alice',
+    email: 'alice@test.com',
+  });
+  expect(user.id).toBeDefined();
+  expect(user.createdAt).toBeInstanceOf(Date);
+});
+```
+
+3. **Use `describe` blocks** to group related tests:
+
+```typescript
+describe('UserService', () => {
+  describe('create', () => {
+    it('creates a user with valid input', () => {
+      /* ... */
+    });
+    it('throws on duplicate email', () => {
+      /* ... */
+    });
+    it('normalizes email to lowercase', () => {
+      /* ... */
+    });
+  });
+
+  describe('findById', () => {
+    it('returns the user when found', () => {
+      /* ... */
+    });
+    it('returns null when not found', () => {
+      /* ... */
+    });
+  });
+});
+```
+
+4. **Test edge cases explicitly:**
+
+```typescript
+describe('parseAge', () => {
+  it('parses valid integer strings', () => {
+    expect(parseAge('25')).toBe(25);
+  });
+  it('returns null for empty string', () => {
+    expect(parseAge('')).toBeNull();
+  });
+  it('returns null for non-numeric input', () => {
+    expect(parseAge('abc')).toBeNull();
+  });
+  it('returns null for negative numbers', () => {
+    expect(parseAge('-5')).toBeNull();
+  });
+  it('returns null for floating point', () => {
+    expect(parseAge('25.5')).toBeNull();
+  });
+  it('handles zero', () => {
+    expect(parseAge('0')).toBe(0);
+  });
+});
+```
+
+5. **Test error cases with `toThrow`:**
+
+```typescript
+it('throws on invalid email', () => {
+  expect(() => validateEmail('not-an-email')).toThrow('Invalid email');
+});
+
+it('throws specific error type', () => {
+  expect(() => validateEmail('')).toThrow(ValidationError);
+});
+```
+
+6. **Use `beforeEach`/`afterEach` for shared setup:**
+
+```typescript
+describe('CartService', () => {
+  let cart: CartService;
+
+  beforeEach(() => {
+    cart = new CartService();
+  });
+
+  it('starts empty', () => {
+    expect(cart.items).toHaveLength(0);
+  });
+  it('adds items', () => {
+    cart.add({ id: '1', qty: 2 });
+    expect(cart.items).toHaveLength(1);
+  });
+});
+```
+
+7. **Test async functions:**
+
+```typescript
+it('resolves with user data', async () => {
+  const user = await getUser('123');
+  expect(user.name).toBe('Alice');
+});
+
+it('rejects with not found error', async () => {
+  await expect(getUser('nonexistent')).rejects.toThrow('User not found');
+});
+```
+
+8. **Name tests as behavior specifications** — describe what the code does, not how it does it:
+
+```typescript
+// Good: describes behavior
+it('applies free shipping for orders over $50', () => {
+  /* ... */
+});
+
+// Bad: describes implementation
+it('calls calculateShipping with zero', () => {
+  /* ... */
+});
+```
+
+## Details
+
+Unit tests verify individual units of code (functions, classes, modules) in isolation from external dependencies. They should be fast (< 10ms each), deterministic, and independent of execution order.
+
+**What makes a good unit test:**
+
+- Tests one behavior per test case
+- Does not depend on other tests or external state
+- Fails for exactly one reason
+- Is readable as a specification of the code's behavior
+
+**Test file organization:** Place test files next to the source file (`user.ts` → `user.test.ts`) or in a parallel `__tests__` directory. Co-location makes it easy to find tests and keeps imports short.
+
+**`expect` matcher selection:**
+
+- `toBe` — strict equality (`===`). Use for primitives
+- `toEqual` — deep equality. Use for objects and arrays
+- `toMatchObject` — partial deep equality. Object under test may have extra properties
+- `toContain` — array includes element or string includes substring
+- `toHaveLength` — array or string length
+- `toBeGreaterThan` / `toBeLessThan` — numeric comparisons
+- `toThrow` — function throws. Wrap the call in an arrow function
+
+**Trade-offs:**
+
+- High unit test coverage gives fast feedback — but can over-test implementation details
+- Isolated tests are fast — but may miss integration issues
+- AAA structure is clear — but can feel verbose for simple one-liner tests
+- `toMatchObject` is flexible — but can pass when extra unexpected properties exist
+
+## Source
+
+https://vitest.dev/guide/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/test-unit-patterns/skill.yaml

@@ -0,0 +1,44 @@
+name: test-unit-patterns
+version: "1.0.0"
+description: Write focused, isolated unit tests using AAA pattern with describe/it/expect
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "**/*.test.tsx"
+  - "vitest.config.*"
+  - "jest.config.*"
+  - "playwright.config.*"
+related_skills:
+  - test-mock-patterns
+  - test-tdd-workflow
+  - test-vitest-config
+stack_signals:
+  - vitest
+  - jest
+  - playwright
+  - testing-library
+keywords:
+  - AAA-pattern
+  - unit-tests
+  - describe
+  - it
+  - expect
+  - test-isolation
+metadata:
+  author: community
+  upstream: vitest.dev/guide/
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/test-vitest-config/SKILL.md

@@ -0,0 +1,212 @@
+# Test Vitest Config
+
+> Configure Vitest with workspaces, environments, coverage, and TypeScript integration
+
+## When to Use
+
+- Setting up Vitest in a new or existing project
+- Configuring test environments (node, jsdom, happy-dom)
+- Setting up workspaces for monorepo testing
+- Integrating coverage, globals, and TypeScript paths
+
+## Instructions
+
+1. **Basic configuration:**
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    exclude: ['node_modules', 'dist', 'e2e'],
+    setupFiles: ['./test/setup.ts'],
+    testTimeout: 10_000,
+  },
+});
+```
+
+2. **Share config with Vite** (if already using Vite):
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./test/setup.ts'],
+  },
+});
+```
+
+3. **Environment per file** using comments or config:
+
+```typescript
+// At the top of a test file:
+// @vitest-environment jsdom
+
+// Or in config, per glob pattern:
+test: {
+  environmentMatchGlobs: [
+    ['src/components/**', 'jsdom'],
+    ['src/services/**', 'node'],
+  ],
+},
+```
+
+4. **Workspace configuration** for monorepos:
+
+```typescript
+// vitest.workspace.ts
+export default [
+  'packages/*/vitest.config.ts',
+  // Or inline:
+  {
+    test: {
+      name: 'unit',
+      include: ['src/**/*.test.ts'],
+      environment: 'node',
+    },
+  },
+  {
+    test: {
+      name: 'components',
+      include: ['src/**/*.test.tsx'],
+      environment: 'jsdom',
+    },
+  },
+];
+```
+
+5. **Coverage configuration:**
+
+```typescript
+test: {
+  coverage: {
+    provider: 'v8',
+    reporter: ['text', 'html', 'lcov'],
+    include: ['src/**/*.ts'],
+    exclude: ['src/**/*.test.ts', 'src/**/*.d.ts'],
+    thresholds: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+    },
+  },
+},
+```
+
+6. **Path aliases** — sync with tsconfig:
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  test: {
+    // ...
+  },
+});
+```
+
+7. **Setup files** for global test configuration:
+
+```typescript
+// test/setup.ts
+import '@testing-library/jest-dom';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+afterEach(() => {
+  cleanup();
+});
+```
+
+8. **Type support** — add vitest types to tsconfig:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}
+```
+
+9. **Parallel execution** and pooling:
+
+```typescript
+test: {
+  pool: 'forks',       // 'threads' | 'forks' | 'vmThreads'
+  poolOptions: {
+    forks: { maxForks: 4 },
+  },
+  fileParallelism: true, // Run test files in parallel
+},
+```
+
+10. **Snapshot configuration:**
+
+```typescript
+test: {
+  snapshotFormat: {
+    printBasicPrototype: false,
+  },
+  resolveSnapshotPath: (testPath, snapExtension) =>
+    testPath.replace('src/', '__snapshots__/') + snapExtension,
+},
+```
+
+## Details
+
+Vitest is a Vite-native test framework that shares Vite's configuration, plugins, and transform pipeline. This means your tests use the same module resolution, path aliases, and transforms as your application code.
+
+**Environment options:**
+
+- `node` — Node.js runtime. For services, utilities, API tests
+- `jsdom` — Browser-like DOM via jsdom. For React/Svelte/Vue component tests
+- `happy-dom` — Faster alternative to jsdom with more Web API support
+- `edge-runtime` — Cloudflare Workers/Vercel Edge runtime simulation
+
+**`globals: true`** makes `describe`, `it`, `expect`, `vi` available without imports. Cleaner test files but requires TypeScript types configuration.
+
+**Pool options:**
+
+- `threads` (default) — worker threads, shared memory, fastest for CPU-bound tests
+- `forks` — child processes, full isolation, best for tests with global state leaks
+- `vmThreads` — VM contexts, lighter than forks, good middle ground
+
+**Performance tips:**
+
+- Use `pool: 'threads'` for fastest execution
+- Set `fileParallelism: true` to run files in parallel
+- Use `--reporter=dot` in CI for minimal output
+- Exclude unnecessary files from test discovery
+- Use `--changed` flag to run only tests affected by changed files
+
+## Source
+
+https://vitest.dev/config/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.