jettypod 4.1.2 → 4.1.4

package/docs/TESTING-FOR-NON-ENGINEERS.md

@@ -0,0 +1,1588 @@
+# Testing Strategy for Non-Engineers: JettyPod Methodology
+
+**Date**: 2025-11-14
+**Audience**: Non-engineers building software with AI + JettyPod
+**Purpose**: Tests as documentation, AI guidance, and quality assurance
+**Coverage Target**: 100% (tests replace traditional documentation)
+
+---
+
+## Philosophy: Tests Are Your Documentation
+
+### Why 100% Coverage Makes Sense Here
+
+**Traditional software development:**
+- Tests = quality assurance
+- Docs = separate markdown files
+- 80% coverage = good enough
+
+**JettyPod methodology:**
+- Tests = documentation + quality + AI guidance
+- No separate docs (except work item notes)
+- 100% coverage = necessary for AI to understand system
+
+### What This Means
+
+**Every piece of functionality has:**
+1. BDD scenario (readable by humans)
+2. Step definitions (executable by AI)
+3. Unit tests (detailed documentation of behavior)
+
+**AI assistants read tests to understand:**
+- How does login work? → Read `features/login.feature`
+- What validation exists? → Read `lib/validators.test.js`
+- What errors are handled? → Read error scenarios in BDD
+
+**Users read tests to understand:**
+- What does this feature do? → Read BDD scenario
+- How do I use this? → Read Given/When/Then steps
+- What can go wrong? → Read error scenarios
+
+---
+
+## Test Types in JettyPod
+
+### 1. BDD Scenarios (Primary Documentation)
+
+**Purpose**: Human-readable documentation of features
+
+**Written in**: Plain English (Gherkin syntax)
+
+**Example:**
+```gherkin
+Feature: User Login
+  As a user
+  I want to log in with email and password
+  So that I can access my account
+
+Scenario: Successful login
+  Given I am on the login page
+  And I have an account with email "user@example.com"
+  When I enter my email and password
+  And I click the "Login" button
+  Then I am redirected to the dashboard
+  And I see a welcome message "Welcome back!"
+
+Scenario: Login with wrong password
+  Given I am on the login page
+  And I have an account with email "user@example.com"
+  When I enter my email and wrong password
+  And I click the "Login" button
+  Then I remain on the login page
+  And I see an error message "Invalid password"
+  And my password field is cleared
+
+Scenario: Login with unregistered email
+  Given I am on the login page
+  When I enter email "unknown@example.com" and any password
+  And I click the "Login" button
+  Then I see an error message "No account found with that email"
+  And I see a link to "Create an account"
+```
+
+**Who reads this:**
+- ✅ Users (understand what feature does)
+- ✅ AI assistants (understand behavior to implement)
+- ✅ Future developers (onboarding)
+
+---
+
+### 2. Step Definitions (AI Implementation Guide)
+
+**Purpose**: Executable code that AI can reference
+
+**Written in**: JavaScript (with detailed comments)
+
+**Example:**
+```javascript
+// features/step_definitions/login.steps.js
+
+const { Given, When, Then } = require('@cucumber/cucumber');
+
+/**
+ * Sets up a user account for testing login
+ * Creates user in test database with hashed password
+ */
+Given('I have an account with email {string}', async function(email) {
+  // AI reads this to understand user creation flow
+  const hashedPassword = await hashPassword('correct-password');
+
+  this.testUser = await createUser({
+    email: email,
+    password: hashedPassword,
+    name: 'Test User'
+  });
+
+  // Track for cleanup
+  this.createdUsers.push(this.testUser.id);
+});
+
+/**
+ * Simulates user entering credentials in login form
+ * Sets form values without actually rendering UI
+ */
+When('I enter my email and password', async function() {
+  // AI reads this to understand login form structure
+  this.loginForm = {
+    email: this.testUser.email,
+    password: 'correct-password',
+    rememberMe: false
+  };
+});
+
+/**
+ * Executes login logic and captures result
+ * This is the core login implementation
+ */
+When('I click the {string} button', async function(buttonText) {
+  if (buttonText === 'Login') {
+    // AI reads this to understand login flow
+    try {
+      this.loginResult = await login(
+        this.loginForm.email,
+        this.loginForm.password
+      );
+
+      // Store session for subsequent steps
+      this.session = this.loginResult.session;
+    } catch (error) {
+      this.loginError = error;
+    }
+  }
+});
+
+/**
+ * Verifies successful login redirects to dashboard
+ * Confirms session is established
+ */
+Then('I am redirected to the dashboard', function() {
+  // AI reads this to understand success criteria
+  expect(this.loginResult.redirectTo).toBe('/dashboard');
+  expect(this.session).toBeDefined();
+  expect(this.session.userId).toBe(this.testUser.id);
+});
+```
+
+**Who reads this:**
+- ✅ AI assistants (detailed implementation guidance)
+- ✅ Advanced users (debugging)
+- ⚠️ Non-technical users (too complex)
+
+---
+
+### 3. Unit Tests (Detailed Behavior Documentation)
+
+**Purpose**: Document edge cases and implementation details
+
+**Written in**: JavaScript (with descriptive test names)
+
+**Example:**
+```javascript
+// lib/auth.test.js
+
+describe('login(email, password)', () => {
+  describe('successful login', () => {
+    it('returns user data when credentials are correct', async () => {
+      const user = await createTestUser('user@example.com', 'password123');
+
+      const result = await login('user@example.com', 'password123');
+
+      expect(result.success).toBe(true);
+      expect(result.user.email).toBe('user@example.com');
+      expect(result.session).toBeDefined();
+    });
+
+    it('creates a session that expires in 24 hours', async () => {
+      const user = await createTestUser('user@example.com', 'password123');
+
+      const result = await login('user@example.com', 'password123');
+
+      const expiresAt = new Date(result.session.expiresAt);
+      const expectedExpiry = new Date(Date.now() + 24 * 60 * 60 * 1000);
+
+      expect(expiresAt.getTime()).toBeCloseTo(expectedExpiry.getTime(), -3);
+    });
+
+    it('updates last_login timestamp on user record', async () => {
+      const user = await createTestUser('user@example.com', 'password123');
+
+      await login('user@example.com', 'password123');
+
+      const updatedUser = await getUserById(user.id);
+      expect(updatedUser.lastLogin).toBeDefined();
+      expect(new Date(updatedUser.lastLogin).getTime())
+        .toBeCloseTo(Date.now(), -3);
+    });
+  });
+
+  describe('failed login attempts', () => {
+    it('returns error when email does not exist', async () => {
+      const result = await login('unknown@example.com', 'password123');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('No account found with that email');
+    });
+
+    it('returns error when password is incorrect', async () => {
+      await createTestUser('user@example.com', 'correct-password');
+
+      const result = await login('user@example.com', 'wrong-password');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Invalid password');
+    });
+
+    it('does not reveal whether email exists (security)', async () => {
+      // Test that error messages don't leak information
+      const noEmailResult = await login('unknown@example.com', 'password');
+      const wrongPassResult = await login('real@example.com', 'wrong');
+
+      // Both should have similar response structure
+      expect(noEmailResult.error).toContain('Invalid');
+      expect(wrongPassResult.error).toContain('Invalid');
+    });
+
+    it('increments failed login counter on wrong password', async () => {
+      const user = await createTestUser('user@example.com', 'correct');
+
+      await login('user@example.com', 'wrong');
+      await login('user@example.com', 'wrong');
+
+      const updatedUser = await getUserById(user.id);
+      expect(updatedUser.failedLoginAttempts).toBe(2);
+    });
+
+    it('locks account after 5 failed attempts', async () => {
+      const user = await createTestUser('user@example.com', 'correct');
+
+      // Fail 5 times
+      for (let i = 0; i < 5; i++) {
+        await login('user@example.com', 'wrong');
+      }
+
+      // 6th attempt should be blocked
+      const result = await login('user@example.com', 'correct');
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Account locked due to too many failed attempts');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles null email', async () => {
+      const result = await login(null, 'password');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Email is required');
+    });
+
+    it('handles empty password', async () => {
+      const result = await login('user@example.com', '');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Password is required');
+    });
+
+    it('handles extremely long email (buffer overflow test)', async () => {
+      const longEmail = 'a'.repeat(10000) + '@example.com';
+
+      const result = await login(longEmail, 'password');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Email too long');
+    });
+
+    it('handles SQL injection attempt in email', async () => {
+      const maliciousEmail = "'; DROP TABLE users; --";
+
+      const result = await login(maliciousEmail, 'password');
+
+      // Should not crash or execute SQL
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+});
+```
+
+**Who reads this:**
+- ✅ AI assistants (understand edge cases and security)
+- ✅ Advanced users (detailed behavior)
+- ❌ Non-technical users (too detailed)
+
+---
+
+## JettyPod's Role in Testing
+
+### What JettyPod Provides Automatically
+
+**1. Test Infrastructure Setup**
+
+When user runs `jettypod init`:
+```javascript
+// JettyPod creates:
+project/
+├── features/                    ← BDD scenarios directory
+│   ├── support/
+│   │   ├── hooks.js            ← Cleanup patterns
+│   │   └── world.js            ← Shared test context
+│   └── step_definitions/       ← Step implementations
+├── test/                       ← Unit tests directory
+├── .git/hooks/                 ← Smart git hooks
+│   ├── pre-commit
+│   ├── pre-push
+│   └── post-merge
+├── jest.config.js              ← Jest configuration
+├── cucumber.js                 ← Cucumber configuration
+└── .jettypod/
+    ├── test-config.json        ← Testing strategy config
+    └── coverage-targets.json   ← Coverage requirements
+```
+
+**2. Test Templates**
+
+JettyPod provides templates for common patterns:
+```javascript
+// .jettypod/templates/bdd-scenario.template
+Feature: {{featureName}}
+  {{featureDescription}}
+
+Scenario: {{happyPathScenario}}
+  Given {{initialState}}
+  When {{userAction}}
+  Then {{expectedOutcome}}
+```
+
+**3. Git Hooks (Context-Aware)**
+
+JettyPod installs smart hooks that understand workflow phase:
+```javascript
+// .git/hooks/pre-commit (installed by JettyPod)
+#!/usr/bin/env node
+
+const { getCurrentWork } = require('.jettypod/current-work');
+
+const currentWork = getCurrentWork();
+const mode = currentWork?.mode; // speed, stable, production
+
+if (mode === 'speed') {
+  // Speed mode: Fast smoke test only
+  console.log('🚀 Speed mode: Running quick validation...');
+  execSync('npm run test:smoke', { stdio: 'inherit' });
+
+} else if (mode === 'stable') {
+  // Stable mode: Run tests for current feature
+  console.log('🧪 Stable mode: Running feature tests...');
+  const featureFile = getFeatureFile(currentWork.parent_id);
+  execSync(`npx cucumber-js ${featureFile}`, { stdio: 'inherit' });
+
+} else if (mode === 'production') {
+  // Production mode: Comprehensive validation
+  console.log('🛡️ Production mode: Running full test suite...');
+  execSync('npm test', { stdio: 'inherit' });
+}
+```
+
+---
+
+## Testing in Each Workflow Phase
+
+### Feature-Planning Phase
+
+**JettyPod's Role:**
+
+1. **Guides user to write BDD scenarios**
+```
+Claude (via skill): "Let's write scenarios for your login feature.
+
+I'll help you write them in plain English. Here's the template:
+
+Feature: What this feature does
+
+Scenario: What happens in the happy path
+  Given [starting situation]
+  When [user takes action]
+  Then [what they see/experience]
+
+Let's start with the happy path. When a user successfully logs in,
+what should happen?"
+
+User: "They should see their dashboard with a welcome message"
+
+Claude: "Great! Here's the scenario:
+
+Scenario: User logs in successfully
+  Given I am registered with email 'user@example.com'
+  When I enter my email and password
+  And I click 'Login'
+  Then I am redirected to my dashboard
+  And I see 'Welcome back!'
+
+Does this capture it? Any other details?"
+```
+
+2. **Generates step definitions automatically**
+```javascript
+// JettyPod auto-generates:
+Given('I am registered with email {string}', async function(email) {
+  // TODO: Implement user creation
+  this.testUser = await createUser({ email });
+});
+
+When('I enter my email and password', async function() {
+  // TODO: Implement form interaction
+  this.loginData = {
+    email: this.testUser.email,
+    password: 'test-password'
+  };
+});
+
+Then('I am redirected to my dashboard', function() {
+  // TODO: Implement redirect check
+  expect(this.response.redirect).toBe('/dashboard');
+});
+```
+
+3. **Validates test infrastructure**
+```bash
+# JettyPod runs automatically:
+npx cucumber-js --dry-run features/login.feature
+
+# Output:
+✅ 3 scenarios (3 undefined)
+✅ 12 steps (12 undefined)
+⚠️  You need to implement these step definitions
+```
+
+**User Experience:**
+```
+You: "I want to add a login feature"
+
+Claude: "Let's plan it! First, how should login work?"
+
+You: "User enters email and password, clicks login, goes to dashboard"
+
+Claude: "Perfect! I've created the BDD scenario in features/login.feature.
+Let me show you:
+
+Feature: User Login
+  Scenario: User logs in successfully
+    Given I am on the login page
+    When I enter valid credentials
+    Then I am redirected to dashboard
+
+✅ Scenario created
+✅ Step definitions scaffolded
+🔄 Ready for speed mode implementation
+
+Next: jettypod work start [chore-id]"
+```
+
+---
+
+### Speed-Mode Phase
+
+**JettyPod's Role:**
+
+1. **Guides implementation with TDD**
+```
+Claude: "Let's implement the login feature. I'll use TDD:
+
+Step 1: Make the first scenario step pass
+  Given I am on the login page
+
+I need to implement:
+  - Login page route
+  - Basic form rendering
+
+Writing the step definition first..."
+
+[Claude writes step definition]
+
+Claude: "Now implementing the route and form...
+
+[Claude writes code]
+
+Running test: npx cucumber-js features/login.feature
+
+✅ Step 1 passing
+🔄 Moving to Step 2: 'When I enter valid credentials'..."
+```
+
+2. **Runs tests continuously**
+```javascript
+// Inside speed-mode skill loop:
+while (!scenarioPasses) {
+  // 1. Implement next piece
+  await implementNextStep();
+
+  // 2. Run BDD test
+  const result = execSync(`npx cucumber-js ${featureFile}`);
+
+  // 3. Show progress to user
+  console.log(`
+  Progress:
+    ✅ Given I am on the login page
+    ✅ When I enter valid credentials
+    🔄 Then I am redirected to dashboard (working on this)
+  `);
+
+  // 4. Iterate until passing
+  if (allStepsPass(result)) {
+    scenarioPasses = true;
+  }
+}
+```
+
+3. **Generates unit tests for new functions**
+```javascript
+// Claude (via skill): "I created a validateEmail() function.
+// Let me write unit tests to document its behavior..."
+
+describe('validateEmail', () => {
+  it('accepts valid email addresses', () => {
+    expect(validateEmail('user@example.com')).toBe(true);
+  });
+
+  it('rejects emails without @', () => {
+    expect(validateEmail('userexample.com')).toBe(false);
+  });
+
+  // etc...
+});
+```
+
+**User Experience:**
+```
+You: "Start implementing login"
+
+Claude: "I'll implement the login feature to pass the scenario we wrote.
+
+🔄 Iteration 1:
+  ✍️  Creating login form component...
+  🧪 Testing... 1 of 3 steps passing
+
+🔄 Iteration 2:
+  ✍️  Adding authentication logic...
+  🧪 Testing... 2 of 3 steps passing
+
+🔄 Iteration 3:
+  ✍️  Adding dashboard redirect...
+  🧪 Testing... ✅ All steps passing!
+
+✅ Login feature works (happy path)
+
+Next: Should I create stable mode chores to add error handling?"
+```
+
+---
+
+### Stable-Mode Phase
+
+**JettyPod's Role:**
+
+1. **Guides user to identify error scenarios**
+```
+Claude: "The happy path works! Now let's think about what can go wrong.
+
+What should happen if:
+  1. User enters wrong password?
+  2. User's email doesn't exist?
+  3. User is already logged in?
+  4. Login fails due to server error?
+
+For each one, we'll:
+  - Add a BDD scenario (human-readable)
+  - Implement error handling (code)
+  - Add unit tests (edge cases)
+
+Let's start with #1: Wrong password..."
+```
+
+2. **Adds error scenarios to feature file**
+```gherkin
+# JettyPod appends to features/login.feature:
+
+Scenario: Login with wrong password
+  Given I am registered with email 'user@example.com'
+  When I enter my email and wrong password
+  And I click 'Login'
+  Then I remain on the login page
+  And I see error "Invalid password"
+  And my password field is cleared
+
+Scenario: Login with unregistered email
+  Given no user exists with email 'unknown@example.com'
+  When I enter email 'unknown@example.com' and any password
+  And I click 'Login'
+  Then I see error "No account found"
+  And I see a link to "Create account"
+```
+
+3. **Implements error handling with tests first**
+```javascript
+// TDD cycle for error handling:
+
+// 1. RED: Add test for error case
+it('returns error when password is wrong', async () => {
+  await createUser('user@example.com', 'correct-password');
+
+  const result = await login('user@example.com', 'wrong-password');
+
+  expect(result.success).toBe(false);
+  expect(result.error).toBe('Invalid password');
+});
+
+// 2. GREEN: Implement error handling
+async function login(email, password) {
+  const user = await findUser(email);
+
+  if (!user) {
+    return { success: false, error: 'No account found' };
+  }
+
+  const validPassword = await verifyPassword(password, user.passwordHash);
+
+  if (!validPassword) {
+    return { success: false, error: 'Invalid password' };
+  }
+
+  return { success: true, session: createSession(user) };
+}
+
+// 3. REFACTOR: Extract validation
+```
+
+4. **Tracks coverage and gaps**
+```javascript
+// JettyPod runs coverage after each iteration:
+npx jest --coverage
+
+// Shows user:
+File          | % Stmts | % Branch | % Funcs | % Lines |
+lib/auth.js   |   95.2  |   89.5   |   100   |   94.8  |
+
+Uncovered lines:
+  auth.js:45-47 (rare edge case: database connection lost)
+
+Claude: "We have 95% coverage. The uncovered lines handle database
+connection loss. Should we test that edge case or is it handled elsewhere?"
+```
+
+**User Experience:**
+```
+You: "Add error handling to login"
+
+Claude: "Let's think about what can go wrong:
+  1. Wrong password
+  2. Email doesn't exist
+  3. Account locked
+  4. Server error
+
+I'll add scenarios for each and implement error handling.
+
+🔄 Adding 'Wrong password' scenario...
+  ✍️  Writing BDD scenario
+  ✍️  Writing unit tests (TDD)
+  ✍️  Implementing error handling
+  🧪 Testing... ✅ Scenario passes
+
+🔄 Adding 'Email doesn't exist' scenario...
+  [repeat]
+
+✅ All error scenarios pass
+📊 Coverage: 98% (2 lines in rare edge case not covered)
+
+Login feature is now robust with error handling!"
+```
+
+---
+
+### Production-Mode Phase
+
+**JettyPod's Role:**
+
+1. **Adds security/performance/scale scenarios**
+```gherkin
+# JettyPod appends production scenarios:
+
+@production @security
+Scenario: Login is protected against brute force attacks
+  Given I have an account with email 'user@example.com'
+  When I attempt to login with wrong password 10 times
+  Then my account is temporarily locked
+  And I see "Too many failed attempts. Try again in 15 minutes"
+
+@production @performance
+Scenario: Login completes within 200ms
+  Given I have an account
+  When I login with valid credentials
+  Then the response time is under 200ms
+  And the session is created
+
+@production @security
+Scenario: Login protects against SQL injection
+  When I attempt to login with email "'; DROP TABLE users; --"
+  Then no SQL is executed
+  And I see "Invalid email format"
+```
+
+2. **Implements production hardening**
+```javascript
+// Claude adds:
+// - Rate limiting
+// - Brute force protection
+// - SQL injection prevention
+// - XSS prevention
+// - Performance monitoring
+
+async function login(email, password) {
+  // Production: Rate limiting
+  await checkRateLimit(email);
+
+  // Production: Input sanitization
+  const sanitizedEmail = sanitizeInput(email);
+
+  // Production: SQL injection prevention (parameterized queries)
+  const user = await db.query(
+    'SELECT * FROM users WHERE email = $1',
+    [sanitizedEmail]
+  );
+
+  // Production: Timing attack prevention
+  await constantTimeCompare(password, user.passwordHash);
+
+  // Production: Brute force protection
+  await checkFailedAttempts(user);
+
+  // Rest of logic...
+}
+```
+
+3. **Validates all scenarios still pass**
+```bash
+# JettyPod runs full suite:
+npx cucumber-js --tags "not @wip"
+
+# Output:
+✅ 15 scenarios (15 passed)
+✅ 87 steps (87 passed)
+📊 Coverage: 100%
+
+Production scenarios:
+  ✅ Brute force protection
+  ✅ SQL injection prevention
+  ✅ Performance under 200ms
+  ✅ XSS prevention
+  ✅ Rate limiting
+```
+
+**User Experience:**
+```
+You: "Make login production-ready"
+
+Claude: "I'll harden login for production with:
+  1. Security (brute force, injection protection)
+  2. Performance (response time under 200ms)
+  3. Monitoring (error tracking, metrics)
+
+🔄 Adding security scenarios...
+  ✍️  Rate limiting
+  ✍️  Brute force protection
+  🧪 Testing... ✅ Security tests pass
+
+🔄 Adding performance scenarios...
+  ✍️  Response time monitoring
+  ✍️  Database query optimization
+  🧪 Testing... ✅ Performance tests pass (avg 145ms)
+
+✅ Login is production-ready!
+📊 Coverage: 100%
+🛡️  All security tests pass
+⚡ Performance: 145ms avg (target: 200ms)
+
+Login feature is complete and ready for real users."
+```
+
+---
+
+## The Complete Testing Experience
+
+### From User's Perspective
+
+**Day 1: Feature Planning**
+```
+You: "I want users to be able to log in"
+
+JettyPod: "Let's write scenarios describing how login should work."
+
+[Collaborative scenario writing in plain English]
+
+✅ Scenarios written (readable documentation)
+✅ Test infrastructure ready
+🎯 Ready to implement
+```
+
+**Day 2-3: Speed Mode**
+```
+You: "Build the login feature"
+
+JettyPod: "I'll implement it step by step, running tests as I go."
+
+[TDD implementation with continuous feedback]
+
+✅ Happy path works
+📖 Tests document how login works
+🔄 Ready for error handling
+```
+
+**Day 4-5: Stable Mode**
+```
+You: "Add error handling"
+
+JettyPod: "Let's think about what can go wrong and handle each case."
+
+[Error scenarios + TDD implementation]
+
+✅ All error cases handled
+📖 Tests document all edge cases
+🛡️  Ready for production hardening
+```
+
+**Day 6: Production Mode**
+```
+You: "Make it production-ready"
+
+JettyPod: "I'll add security, performance, and monitoring."
+
+[Production scenarios + hardening]
+
+✅ Production-ready
+📖 Tests document security measures
+🚀 Ready to deploy
+```
+
+---
+
+## Coverage: Why 100% Makes Sense
+
+### Traditional Software: 80% Coverage Goal
+
+**Why 80% is common:**
+- Diminishing returns on last 20%
+- Some code is hard to test (UI, third-party integration)
+- Docs explain the system
+- Developers understand the codebase
+
+**What 80% means:**
+- Core logic: 100% covered
+- Edge cases: Mostly covered
+- Trivial code: Not covered
+- Acceptable because docs supplement tests
+
+### JettyPod Methodology: 100% Coverage Goal
+
+**Why 100% makes sense here:**
+- Tests ARE the documentation (no separate docs)
+- AI needs complete understanding of system
+- Non-engineers read tests to understand features
+- Tests explain every edge case and error condition
+
+**What 100% means:**
+- Every function has unit tests documenting behavior
+- Every user workflow has BDD scenario
+- Every error condition has test explaining how it's handled
+- Every edge case is documented via test
+
+**The uncovered 0%:**
+```javascript
+// Even trivial code gets documented via tests:
+
+// lib/formatters.js
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// lib/formatters.test.js
+describe('capitalize', () => {
+  it('capitalizes first letter of a word', () => {
+    expect(capitalize('hello')).toBe('Hello');
+  });
+
+  it('leaves already capitalized words unchanged', () => {
+    expect(capitalize('Hello')).toBe('Hello');
+  });
+
+  it('handles empty string', () => {
+    expect(capitalize('')).toBe('');
+  });
+
+  it('handles single character', () => {
+    expect(capitalize('a')).toBe('A');
+  });
+});
+```
+
+**Why test trivial code?**
+- AI reads these tests to understand string formatting
+- Non-engineers see examples of edge cases
+- Future changes won't break assumptions
+- Tests are the documentation
+
+---
+
+## How AI Uses Tests
+
+### AI Reading Tests as Documentation
+
+**Scenario: User asks AI to add password reset**
+
+```
+User: "Add a password reset feature"
+
+AI (Claude): "Let me understand how authentication works first..."
+
+[AI reads features/login.feature]
+
+AI: "I see login uses email and password. Let me check password storage..."
+
+[AI reads lib/auth.test.js]
+
+AI: "I understand:
+  - Passwords are hashed with bcrypt
+  - Failed attempts are tracked
+  - Account lockout after 5 attempts
+  - Sessions expire after 24 hours
+
+For password reset, I should:
+  1. Generate reset token (similar to session token)
+  2. Send email with reset link
+  3. Verify token on reset page
+  4. Allow new password (hash with bcrypt like login)
+  5. Clear failed attempts on successful reset
+
+Let me write the scenarios first..."
+```
+
+**Without tests as documentation:**
+```
+AI: "I'll add password reset functionality."
+[Makes assumptions, might conflict with existing auth logic]
+```
+
+**With tests as documentation:**
+```
+AI: "Based on the auth tests, I'll integrate password reset properly:
+  - Use same hashing as login (bcrypt with cost 10)
+  - Clear failed attempts on reset (prevents lockout)
+  - Generate token with 1-hour expiry (like sessions but shorter)
+
+Let me write scenarios that explain the reset flow..."
+```
+
+---
+
+## JettyPod's Testing Automation
+
+### What JettyPod Does Automatically
+
+**1. Test Infrastructure Setup**
+```javascript
+// When user runs: jettypod init
+
+async function initializeProject() {
+  // Create test directories
+  fs.mkdirSync('features', { recursive: true });
+  fs.mkdirSync('features/step_definitions', { recursive: true });
+  fs.mkdirSync('features/support', { recursive: true });
+  fs.mkdirSync('test', { recursive: true });
+
+  // Install test dependencies
+  execSync('npm install --save-dev jest @cucumber/cucumber chai');
+
+  // Create configuration files
+  createJestConfig();
+  createCucumberConfig();
+
+  // Create support files with safety patterns
+  createHooksFile(); // Before/After cleanup
+  createWorldFile(); // Shared test context
+
+  // Install git hooks
+  installSmartGitHooks();
+
+  console.log('✅ Test infrastructure ready');
+  console.log('📖 Tests will serve as your documentation');
+  console.log('🤖 AI will read tests to understand your system');
+}
+```
+
+**2. Scenario Generation**
+```javascript
+// In feature-planning skill:
+
+async function generateScenarios(featureDescription) {
+  // Use AI to generate scenarios from user's description
+  const scenarios = await aiGenerateScenarios({
+    feature: featureDescription,
+    context: readExistingScenarios(), // Learn from existing patterns
+    style: 'non-technical' // Plain English
+  });
+
+  // Write to feature file
+  const featureFile = `features/${slugify(featureDescription)}.feature`;
+  fs.writeFileSync(featureFile, scenarios);
+
+  // Generate step definitions
+  const steps = extractSteps(scenarios);
+  const stepDefinitions = generateStepDefinitions(steps);
+
+  const stepsFile = `features/step_definitions/${slugify(featureDescription)}.steps.js`;
+  fs.writeFileSync(stepsFile, stepDefinitions);
+
+  // Validate infrastructure
+  execSync(`npx cucumber-js --dry-run ${featureFile}`);
+
+  console.log('✅ Scenarios created and validated');
+}
+```
+
+**3. Test Execution During Implementation**
+```javascript
+// In speed-mode skill:
+
+async function implementFeature(featureId) {
+  const feature = getFeature(featureId);
+  const scenarios = readScenarios(feature.scenarioFile);
+
+  for (const scenario of scenarios) {
+    console.log(`\n🔄 Implementing: ${scenario.title}`);
+
+    // TDD loop
+    let passing = false;
+    let iteration = 0;
+
+    while (!passing && iteration < 10) {
+      iteration++;
+
+      // 1. Implement next piece
+      await aiImplementNextStep(scenario, iteration);
+
+      // 2. Run tests
+      console.log('🧪 Running tests...');
+      const result = execSync(
+        `npx cucumber-js ${feature.scenarioFile}`,
+        { encoding: 'utf-8' }
+      );
+
+      // 3. Check progress
+      const progress = parseTestProgress(result);
+      console.log(`
+      Progress (${progress.passed}/${progress.total} steps):
+      ${formatProgressSteps(progress)}
+      `);
+
+      // 4. Check if scenario passes
+      if (progress.passed === progress.total) {
+        console.log('✅ Scenario passes!');
+        passing = true;
+      } else {
+        console.log('🔄 Iterating...');
+      }
+    }
+  }
+
+  // Generate unit tests for any new functions
+  await generateUnitTestsForNewCode();
+
+  console.log('\n✅ Feature implementation complete');
+  console.log('📖 All scenarios pass (tests document behavior)');
+  console.log('📊 Running coverage...');
+
+  const coverage = execSync('npx jest --coverage', { encoding: 'utf-8' });
+  console.log(coverage);
+}
+```
+
+**4. Coverage Tracking**
+```javascript
+// After each phase:
+
+function checkCoverage(phase) {
+  const coverage = getCoverageReport();
+  const target = getCoverageTarget(phase);
+
+  console.log(`\n📊 Coverage Report (${phase}):`);
+  console.log(`Current: ${coverage.lines}%`);
+  console.log(`Target:  ${target.lines}%`);
+
+  if (coverage.lines < target.lines) {
+    console.log(`\n⚠️  Coverage below target`);
+    console.log(`Missing coverage in:`);
+
+    // Show which files need more tests
+    const gaps = findCoverageGaps(coverage);
+    gaps.forEach(gap => {
+      console.log(`  - ${gap.file}: ${gap.uncoveredLines.length} uncovered lines`);
+    });
+
+    console.log(`\nShould I write tests to cover these gaps?`);
+  } else {
+    console.log(`\n✅ Coverage target met!`);
+  }
+}
+```
+
+**5. Documentation Generation from Tests**
+```javascript
+// JettyPod generates human-readable docs from tests:
+
+function generateDocumentation() {
+  console.log('📚 Generating documentation from tests...');
+
+  // Parse BDD scenarios
+  const features = parseAllFeatures();
+
+  // Generate markdown documentation
+  const docs = [];
+
+  features.forEach(feature => {
+    docs.push(`# ${feature.title}\n`);
+    docs.push(`${feature.description}\n\n`);
+
+    feature.scenarios.forEach(scenario => {
+      docs.push(`## ${scenario.title}\n\n`);
+      docs.push('**What happens:**\n');
+
+      scenario.steps.forEach(step => {
+        docs.push(`- ${step.type} ${step.text}\n`);
+      });
+
+      docs.push('\n');
+    });
+  });
+
+  fs.writeFileSync('FEATURES.md', docs.join(''));
+
+  console.log('✅ Documentation generated from tests');
+  console.log('📖 See FEATURES.md for human-readable feature list');
+}
+```
+
+---
+
+## Test Execution Optimization
+
+### The Performance Problem (Solved)
+
+**Initial implementation challenge:**
+- Test execution was slow during TDD iterations
+- Running entire feature files when only testing single scenarios
+- 5-10 minute iteration cycles
+- Poor developer experience
+
+**Root cause:**
+```javascript
+// Original approach: Run entire feature file every iteration
+const result = execSync(`npm run test:bdd -- ${featureFile}`);
+// Problem: Tests ALL scenarios when we only care about one
+```
+
+**Solution: Scenario-specific execution:**
+```javascript
+// Optimized: Run only the target scenario during iteration
+const happyPathLine = getFirstScenarioLine(featureFile);
+const result = runBddScenarioWithTimeout(featureFile, happyPathLine);
+// Result: 20-30x faster (10-30 seconds vs 5-10 minutes)
+```
+
+### How It Works: Context-Aware Testing
+
+**During iteration (speed/stable/production modes):**
+- Run ONLY the target scenario being implemented
+- Fast feedback loop (10-30 seconds)
+- Focus on the specific functionality being built
+
+**After GREEN is achieved:**
+- Run full feature file for regression detection
+- Ensures new code doesn't break existing scenarios
+- Comprehensive validation before marking work complete
+
+**On git commit (pre-commit hook):**
+- Context-aware test execution based on workflow phase
+- Speed mode: Happy path only (10-30 seconds)
+- Stable mode: All current feature scenarios (30-60 seconds)
+- Production mode: Full test suite (1-2 minutes)
+
+### Test Execution Functions
+
+**1. runBddScenarioWithTimeout()**
+```javascript
+// Run a specific scenario by line number
+const result = await runBddScenarioWithTimeout(
+  'features/login.feature',
+  13,  // Line number of "Scenario:" keyword
+  60000 // 60-second timeout
+);
+
+// Or by scenario name
+const result = await runBddScenarioWithTimeout(
+  'features/login.feature',
+  'User logs in successfully', // Scenario name
+  60000
+);
+```
+
+**2. runBddTestWithTimeout()**
+```javascript
+// Run entire feature file (for full verification)
+const result = await runBddTestWithTimeout(
+  'features/login.feature',
+  120000 // 120-second timeout
+);
+```
+
+**3. Timeout Protection**
+```javascript
+// All test execution protected by timeout with graceful termination
+if (result.timedOut) {
+  console.log('⚠️  Tests timed out - may have infinite loop');
+  // Continue implementation, don't block
+}
+```
+
+### Performance Comparison
+
+**Before optimization:**
+```
+Speed mode iteration:
+  🔄 Iteration 1: Running tests... 5-10 minutes
+  🔄 Iteration 2: Running tests... 5-10 minutes
+  🔄 Iteration 3: Running tests... 5-10 minutes
+  Total: 15-30 minutes for 3 iterations
+```
+
+**After optimization:**
+```
+Speed mode iteration:
+  🔄 Iteration 1: Running target scenario... 10-30 seconds
+  🔄 Iteration 2: Running target scenario... 10-30 seconds
+  🔄 Iteration 3: Running target scenario... 10-30 seconds
+  ✅ GREEN: Running full verification... 1-2 minutes
+  Total: 2-3 minutes for 3 iterations + verification
+```
+
+**20-30x speedup in iteration cycles**
+
+### Pre-commit Hook Intelligence
+
+**Context detection:**
+```javascript
+// Reads CLAUDE.md and database to determine current work
+const context = detectWorkContext();
+// Returns: {mode: 'speed'|'stable'|'production', feature_id, scenario_file}
+```
+
+**Adaptive test execution:**
+```javascript
+switch (context.mode) {
+  case 'speed':
+    // Fast smoke test: Happy path scenario only
+    const happyPathLine = getFirstScenarioLine(context.scenario_file);
+    result = runBddScenarioWithTimeout(context.scenario_file, happyPathLine, 30000);
+    break;
+
+  case 'stable':
+    // Feature-specific: All scenarios in current feature
+    result = runBddTestWithTimeout(context.scenario_file, 60000);
+    break;
+
+  case 'production':
+    // Comprehensive: Entire test suite
+    result = runBddTestWithTimeout(context.scenario_file, 120000);
+    break;
+}
+```
+
+**Non-blocking failures:**
+- Infrastructure failures allow commit to proceed
+- Test failures block commit (as expected)
+- Prevents git hook issues from blocking development
+
+### Automatic Unit Test Generation
+
+**Problem solved:**
+- "I'll add tests later" syndrome
+- Missing unit test coverage
+- Inconsistent test patterns
+
+**Three-phase approach:**
+
+**Phase 1: Feature Planning (Scaffolding)**
+```javascript
+// After BDD validation passes, scaffold empty test files
+const { scaffoldUnitTestFile } = require('../../lib/unit-test-generator');
+
+for (const implementationFile of inferredFiles) {
+  if (implementationFile.endsWith('.js') && !implementationFile.includes('test')) {
+    const testFile = scaffoldUnitTestFile(implementationFile);
+    console.log(`  ✅ Created ${testFile}`);
+  }
+}
+```
+
+**Phase 2: Speed Mode (Generation)**
+```javascript
+// After GREEN achieved, generate tests for new functions
+const { generateTestsAfterGreen } = require('../../lib/unit-test-generator');
+
+for (const modifiedFile of getModifiedFiles()) {
+  const result = generateTestsAfterGreen(modifiedFile);
+
+  if (result.functionsAdded > 0) {
+    console.log(`  ✅ Generated tests for ${result.functionsAdded} functions`);
+    console.log(`     ${result.testFile}`);
+  }
+}
+```
+
+**Phase 3: Stable Mode (Edge Cases)**
+```javascript
+// Human review and enhancement of generated tests
+// Add edge case tests, error condition tests, security tests
+// Fill in TODO placeholders with actual assertions
+```
+
+### Coverage Tracking
+
+**After stable mode completion:**
+```javascript
+const { trackFeatureCoverage } = require('../../lib/coverage-tracker');
+
+const coverageResult = trackFeatureCoverage(implementationFiles, {
+  coverageThreshold: 80,
+  verbose: false
+});
+
+console.log(coverageResult.report);
+// Output:
+// 📊 Unit Test Coverage Report
+// ─────────────────────────────
+// Statements: ✅ 85.23%
+// Branches:   ✅ 82.15%
+// Functions:  ✅ 88.50%
+// Lines:      ✅ 84.90%
+// ─────────────────────────────
+// ✅ All coverage metrics meet 80% threshold
+```
+
+**What it does:**
+- Identifies test files for modified implementation files
+- Runs Jest with coverage for those specific tests
+- Reports coverage metrics with threshold comparison
+- Highlights gaps needing additional tests
+
+### The Complete Optimized Experience
+
+**Feature planning:**
+```
+You: "Add login feature"
+Claude: "Writing scenarios..."
+✅ Scenarios validated (dry-run: 10 seconds)
+✅ Test files scaffolded
+```
+
+**Speed mode (optimized):**
+```
+🔄 Iteration 1: Implementing first step...
+  🧪 Running happy path scenario... 15 seconds
+  📊 1 of 3 steps passing
+
+🔄 Iteration 2: Implementing auth logic...
+  🧪 Running happy path scenario... 12 seconds
+  📊 2 of 3 steps passing
+
+🔄 Iteration 3: Adding redirect...
+  🧪 Running happy path scenario... 10 seconds
+  ✅ Happy path passes!
+
+🔍 Running full verification... 45 seconds
+✅ All scenarios passing
+
+📝 Generating unit tests... 5 seconds
+✅ Generated tests for 4 functions
+
+Total time: ~1.5 minutes (vs 15-30 minutes before)
+```
+
+**Stable mode (optimized):**
+```
+🔄 Iteration 1: Adding error handling...
+  🧪 Running error scenario... 18 seconds
+  📊 Target scenario passing
+
+🔍 Running full verification... 45 seconds
+✅ All scenarios still passing (no regressions)
+
+📊 Running coverage... 10 seconds
+✅ 85% coverage
+
+Total time per chore: ~1.2 minutes
+```
+
+**Git commit (optimized):**
+```
+git commit -m "feat: Add login validation"
+
+🧪 Pre-commit: Speed mode context detected
+  Running happy path scenario... 12 seconds
+  ✅ Tests pass
+
+✅ Commit allowed
+```
+
+---
+
+## Configuration: Test Strategy Settings
+
+### .jettypod/test-config.json
+
+```json
+{
+  "coverage": {
+    "target": 100,
+    "enforce": true,
+    "excludePatterns": [
+      "**/node_modules/**",
+      "**/test/**",
+      "**/*.test.js",
+      "**/*.spec.js"
+    ]
+  },
+
+  "testing": {
+    "framework": {
+      "bdd": "cucumber",
+      "unit": "jest"
+    },
+
+    "runOn": {
+      "featurePlanning": "dry-run",
+      "speedMode": "continuous",
+      "stableMode": "continuous",
+      "productionMode": "comprehensive"
+    },
+
+    "gitHooks": {
+      "preCommit": {
+        "enabled": true,
+        "runTests": true,
+        "contextAware": true
+      },
+      "prePush": {
+        "enabled": true,
+        "runTests": true,
+        "requirePassing": true
+      }
+    }
+  },
+
+  "documentation": {
+    "testsAreDocumentation": true,
+    "generateMarkdownDocs": true,
+    "autoUpdateOnTest": true
+  },
+
+  "ai": {
+    "readTestsForContext": true,
+    "generateTestsFromScenarios": true,
+    "suggestMissingTests": true
+  }
+}
+```
+
+---
+
+## Summary: Testing for Non-Engineers
+
+### The JettyPod Testing Philosophy
+
+**1. Tests = Documentation**
+- No separate docs needed
+- Tests explain how everything works
+- AI reads tests to understand system
+- Users read BDD scenarios to understand features
+
+**2. 100% Coverage Goal**
+- Every function documented via unit tests
+- Every workflow documented via BDD scenarios
+- Every error case explained via tests
+- No undocumented behavior
+
+**3. JettyPod Facilitates Everything**
+- Auto-generates test infrastructure
+- Guides scenario writing (plain English)
+- Runs tests continuously during implementation
+- Tracks coverage and identifies gaps
+- Generates documentation from tests
+
+**4. User Experience**
+- Write scenarios in plain English
+- AI implements with TDD
+- Tests run automatically
+- Coverage tracked automatically
+- Documentation generated automatically
+
+### What Users See
+
+**Feature planning:**
+```
+You: "Add login"
+JettyPod: "Let's write scenarios..."
+[Collaborative scenario writing]
+✅ Scenarios created (your documentation)
+```
+
+**Speed mode:**
+```
+You: "Implement login"
+JettyPod: "Implementing with tests..."
+[TDD implementation with progress]
+✅ Happy path works (tests show how)
+```
+
+**Stable mode:**
+```
+You: "Add error handling"
+JettyPod: "Adding error scenarios..."
+[Error cases + tests]
+✅ All cases handled (tests document errors)
+```
+
+**Production mode:**
+```
+You: "Make it production-ready"
+JettyPod: "Adding security/performance..."
+[Production hardening + tests]
+✅ Production-ready (tests prove it)
+```
+
+### The Result
+
+**For users:**
+- Features explained in plain English (BDD scenarios)
+- No need to understand code
+- Clear documentation of what works and what doesn't
+
+**For AI assistants:**
+- Complete understanding of system (unit tests)
+- All edge cases documented (test cases)
+- Implementation patterns clear (step definitions)
+
+**For future developers:**
+- Onboard by reading tests
+- Understand behavior from scenarios
+- See examples of every pattern
+
+**100% coverage = Complete documentation of the system**
+
+This is the JettyPod way: Tests aren't overhead, they're the deliverable.