await page.goto('http://localhost:3000/contact'); await page.type('#email', 'test@example.com'); await page.type('#message', 'Hello'); await page.click('button[type="submit"]');

const successMsg = await page.$eval('.success', el => el.textContent);

expect(successMsg).toBe('Message sent!'); await browser.close(); });

Clear name, tests real browser, one thing
</Good>

<Bad>
```typescript
// ❌ BAD: Mocked DOM, not real browser
test('form submission works', async () => {
  const mockSubmit = jest.fn();
  const { getByRole } = render(<ContactForm onSubmit={mockSubmit} />);

  fireEvent.click(getByRole('button'));

  expect(mockSubmit).toHaveBeenCalled();
});

Uses mocking, tests mock not real system

Shannon requirement: NO MOCKS

Real systems to use:

• ✅ Puppeteer/Playwright for web (await page.goto(...))
• ✅ iOS Simulator MCP for mobile (ios_simulator.launch_app(...))
• ✅ Real database (await db.connect(real_connection_string))
• ✅ Real HTTP (await fetch(actual_url))
• ✅ Real file system (fs.readFile(actual_path))

NOT acceptable:

• ❌ jest.mock('puppeteer')
• ❌ @testing-library/react with mocked DOM
• ❌ unittest.mock.patch(...)
• ❌ sinon.stub(...)
• ❌ In-memory fake database
• ❌ Mocked fetch/HTTP client

Requirements:

• One behavior per test
• Clear name describing behavior
• Real systems (browser, database, HTTP, filesystem)
• No mocks, stubs, or fakes

Verify RED - Watch It Fail (Against Real System)

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)
• Fails against REAL system (not mock)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

Test uses mocks? Delete mocks. Use real systems.

NO MOCKS Verification

Shannon checkpoint: Before proceeding to GREEN phase

Scan test file for mock violations:

# Check for mock imports
grep -r "import.*mock\|from.*mock\|jest.mock" test/file.test.ts

# If violations found → DELETE MOCKS, rewrite with real systems

Common violations and fixes:

Can't use real system? Ask your partner. Mocking is NEVER the answer in Shannon.

GREEN - Minimal Code

Write simplest code to pass the test.

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass (Against Real System)

MANDATORY.

npm test path/to/test.test.ts

Confirm:

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)
• Uses real systems (verified by reading test code)

Test fails? Fix code, not test.

Other tests fail? Fix now.

Uses mocks? You violated NO MOCKS. Start over.

REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Still NO MOCKS: Refactoring cannot introduce mocking.

Repeat

Next failing test for next feature.

Good Tests (Shannon Style)

Shannon Integration: Validation Gates

TDD is part of Shannon's 3-tier validation:

Tier 1: Flow Validation

TDD tests written, code compiles

Tier 2: Artifact Validation

TDD tests pass (RED-GREEN cycle verified)

Tier 3: Functional Validation

TDD tests use REAL systems (NO MOCKS)

Reporting format:

## TDD Verification

✅ RED Phase: Test failed (feature missing)
   Real system used: Puppeteer (Chrome browser)
   Failure: Cannot find element '.success'

✅ GREEN Phase: Test passed (feature implemented)
   Real system used: Puppeteer (Chrome browser)
   Success: Message sent successfully

✅ NO MOCKS: Verified
   Scan result: 0 mock imports found
   Real systems: Puppeteer, PostgreSQL, Real HTTP

**TDD Cycle**: Complete
**Validation Tier**: 3/3 (Functional - Real Systems)

Why Order Matters

"I'll write tests after to verify it works"

Tests written after code pass immediately. Passing immediately proves nothing:

• Might test wrong thing
• Might test implementation, not behavior
• Might miss edge cases you forgot
• You never saw it catch the bug

Test-first forces you to see the test fail, proving it actually tests something.

"I already manually tested all the edge cases"

Manual testing is ad-hoc. You think you tested everything but:

• No record of what you tested
• Can't re-run when code changes
• Easy to forget cases under pressure
• "It worked when I tried it" ≠ comprehensive

Automated tests with real systems are systematic. They run the same way every time.

"Deleting X hours of work is wasteful"

Sunk cost fallacy. The time is already gone. Your choice now:

• Delete and rewrite with TDD + real systems (X more hours, high confidence)
• Keep it and add tests after (30 min, low confidence, likely bugs, probably uses mocks)

The "waste" is keeping code you can't trust. Working code without real tests is technical debt.

Shannon-Specific: Real System Patterns

Web Testing (Puppeteer/Playwright)

Required for: Any web UI, forms, navigation, rendering

Pattern:

describe('User Registration Flow', () => {
  let browser: Browser;
  let page: Page;

  beforeEach(async () => {
    browser = await puppeteer.launch();
    page = await browser.newPage();
  });

  afterEach(async () => {
    await browser.close();
  });

  test('user can register with valid email', async () => {
    await page.goto('http://localhost:3000/register');

    await page.type('#email', 'newuser@example.com');
    await page.type('#password', 'SecurePass123!');
    await page.click('button[type="submit"]');

    await page.waitForSelector('.welcome-message');
    const welcomeText = await page.$eval('.welcome-message', el => el.textContent);

    expect(welcomeText).toContain('Welcome, newuser@example.com');
  });
});

MCP Integration: Use Puppeteer MCP if available for better integration.

Mobile Testing (iOS Simulator)

Required for: iOS/Android apps, mobile-specific behavior

Pattern:

import { iosSimulator } from '@mcp/ios-simulator';

describe('Mobile App Launch', () => {
  test('app launches and shows home screen', async () => {
    const app = await iosSimulator.launch({
      appPath: './build/MyApp.app',
      device: 'iPhone 14'
    });

    const screenshot = await app.screenshot();
    const homeButton = await app.findElement({ id: 'home-tab' });

    expect(homeButton.isDisplayed()).toBe(true);

    await app.terminate();
  });
});

Database Testing (Real Database)

Required for: Database queries, transactions, migrations

Pattern:

import { Client } from 'pg';

describe('User Database Operations', () => {
  let db: Client;

  beforeEach(async () => {
    db = new Client({
      host: 'localhost',
      database: 'myapp_test',  // Real test database
      user: 'testuser',
      password: 'testpass'
    });
    await db.connect();

    // Clean test data
    await db.query('TRUNCATE users CASCADE');
  });

  afterEach(async () => {
    await db.end();
  });

  test('creates user with hashed password', async () => {
    const result = await db.query(
      'INSERT INTO users (email, password_hash) VALUES ($1, $2) RETURNING id',
      ['test@example.com', 'hashed_password_here']
    );

    expect(result.rows[0].id).toBeGreaterThan(0);

    const user = await db.query('SELECT * FROM users WHERE email = $1', ['test@example.com']);
    expect(user.rows[0].email).toBe('test@example.com');
  });
});

NOT acceptable: In-memory SQLite, mocked database, fake database.

API Testing (Real HTTP)

Required for: API endpoints, HTTP clients, external integrations

Pattern:

describe('API Endpoints', () => {
  const baseURL = 'http://localhost:3001';  // Real test server

  test('GET /users returns user list', async () => {
    const response = await fetch(`${baseURL}/users`);
    const data = await response.json();

    expect(response.status).toBe(200);
    expect(Array.isArray(data)).toBe(true);
  });

  test('POST /users creates new user', async () => {
    const response = await fetch(`${baseURL}/users`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'new@example.com' })
    });

    const data = await response.json();

    expect(response.status).toBe(201);
    expect(data.email).toBe('new@example.com');
    expect(data.id).toBeDefined();
  });
});

NOT acceptable: jest.mock('fetch'), nock(), mocked HTTP client.

Common Rationalizations

Red Flags - STOP and Start Over

• Code before test
• Test after implementation
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• Rationalizing "just this once"
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "Keep as reference" or "adapt existing code"
• "Already spent X hours, deleting is wasteful"
• "TDD is dogmatic, I'm being pragmatic"
• "Mocking is faster/easier"
• "Industry uses mocks, why not us?"
• "Can't test real systems"
• "This is different because..."

ALL OF THESE MEAN: Delete code. Start over with TDD using REAL systems.

Example: Bug Fix with Real Systems

Bug: Empty email accepted in registration

RED (Real system test):

test('rejects registration with empty email', async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.goto('http://localhost:3000/register');

  // Leave email empty
  await page.type('#password', 'SecurePass123!');
  await page.click('button[type="submit"]');

  const errorMessage = await page.$eval('.error', el => el.textContent);

  expect(errorMessage).toBe('Email required');

  await browser.close();
});

Verify RED:

$ npm test
FAIL: expected 'Email required', got null (no error shown)

GREEN:

// In registration form component
function handleSubmit() {
  if (!email?.trim()) {
    setError('Email required');
    return;
  }
  // ... rest of registration
}

Verify GREEN:

$ npm test
PASS: All tests passed (using real browser)

Verification Checklist

Before marking work complete:

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not typo)
• Wrote minimal code to pass each test
• All tests pass
• Output pristine (no errors, warnings)
• Tests use REAL systems (NO MOCKS)
• Verified NO mock imports in test files
• Edge cases and errors covered
• Real browser/database/HTTP used

Can't check all boxes? You skipped TDD or used mocks. Start over.

Integration with Other Skills

This skill is prerequisite for:

• systematic-debugging - Phase 4 requires writing failing test first
• verification-before-completion - TDD tests are part of Tier 2 validation
• executing-plans - Plans should specify TDD for each task

This skill requires:

• NO MOCKS - Shannon's foundational testing philosophy

Complementary skills:

• defense-in-depth - TDD at code level, defense-in-depth at validation level
• root-cause-tracing - Both enforce thoroughness

The Bottom Line

Production code → test exists and failed first
Test → uses REAL systems (NO MOCKS)
Otherwise → not TDD, not Shannon-compliant

No exceptions without your human partner's permission.

Shannon difference: Other frameworks allow mocking. Shannon doesn't. Mission-critical domains (Finance, Healthcare, Legal, Security, Aerospace) cannot tolerate tests that don't prove real system behavior.

Mocks don't fail in production. Real systems do. Test what fails.