Part 3: Development, Testing, and Code Quality

Introduction

This is where planning meets reality. In this part, I'll walk through my actual development workflow—from writing the first line of code to ensuring quality through testing and code review.

Let's build that webhook handler from Part 2.

Actually Writing Code

The Development Flow

Step 1: Write the Test First

Here's my actual first test for the webhook handler:

// tests/unit/webhookHandler.test.ts
import { describe, it, expect, vi } from 'vitest';
import { WebhookHandler } from '../../src/services/webhookHandler';
import crypto from 'crypto';

describe('WebhookHandler', () => {
  const handler = new WebhookHandler({
    secret: 'whsec_test_secret',
  });

  describe('verifySignature', () => {
    it('should accept valid Stripe signature', () => {
      const payload = JSON.stringify({ type: 'payment_intent.succeeded' });
      const timestamp = Math.floor(Date.now() / 1000);
      
      // Create valid signature
      const signedPayload = `${timestamp}.${payload}`;
      const signature = crypto
        .createHmac('sha256', 'whsec_test_secret')
        .update(signedPayload)
        .digest('hex');
      
      const headers = {
        'stripe-signature': `t=${timestamp},v1=${signature}`,
      };

      expect(() => handler.verifySignature(payload, headers)).not.toThrow();
    });

    it('should reject invalid signature', () => {
      const payload = JSON.stringify({ type: 'payment_intent.succeeded' });
      const headers = {
        'stripe-signature': 't=123456789,v1=invalidsignature',
      };

      expect(() => handler.verifySignature(payload, headers))
        .toThrow('Invalid signature');
    });

    it('should reject expired timestamps (>5 min old)', () => {
      const payload = JSON.stringify({ type: 'payment_intent.succeeded' });
      const oldTimestamp = Math.floor(Date.now() / 1000) - 400; // 6 mins ago
      
      const signedPayload = `${oldTimestamp}.${payload}`;
      const signature = crypto
        .createHmac('sha256', 'whsec_test_secret')
        .update(signedPayload)
        .digest('hex');
      
      const headers = {
        'stripe-signature': `t=${oldTimestamp},v1=${signature}`,
      };

      expect(() => handler.verifySignature(payload, headers))
        .toThrow('Timestamp too old');
    });
  });
});

Why test first?

1. Forces me to think about the API

2. Documents expected behavior

3. Prevents over-engineering

4. Gives me confidence to refactor

Step 2: Implement Minimum Code

Now I write just enough to make tests pass:

// src/services/webhookHandler.ts
import crypto from 'crypto';

interface WebhookConfig {
  secret: string;
  toleranceSeconds?: number;
}

export class WebhookHandler {
  private secret: string;
  private tolerance: number;

  constructor(config: WebhookConfig) {
    this.secret = config.secret;
    this.tolerance = config.toleranceSeconds ?? 300; // 5 minutes default
  }

  verifySignature(payload: string, headers: Record<string, string>): void {
    const signature = headers['stripe-signature'];
    if (!signature) {
      throw new Error('Missing stripe-signature header');
    }

    // Parse signature header: "t=timestamp,v1=signature"
    const parts = signature.split(',');
    const timestamp = parts.find(p => p.startsWith('t='))?.split('=')[1];
    const sig = parts.find(p => p.startsWith('v1='))?.split('=')[1];

    if (!timestamp || !sig) {
      throw new Error('Invalid signature format');
    }

    // Check timestamp age
    const now = Math.floor(Date.now() / 1000);
    if (parseInt(timestamp) < now - this.tolerance) {
      throw new Error('Timestamp too old');
    }

    // Verify signature
    const signedPayload = `${timestamp}.${payload}`;
    const expectedSig = crypto
      .createHmac('sha256', this.secret)
      .update(signedPayload)
      .digest('hex');

    if (sig !== expectedSig) {
      throw new Error('Invalid signature');
    }
  }

  async handleEvent(payload: string, headers: Record<string, string>): Promise<void> {
    // Verify first
    this.verifySignature(payload, headers);

    // Parse event
    const event = JSON.parse(payload);

    // Log for monitoring
    console.log('Processing webhook:', event.type);

    // Enqueue for processing
    // TODO: Add to Redis queue
  }
}

Tests pass! But code isn't great yet. That's okay—refactor next.

Step 3: Refactor

Now I improve code quality without changing behavior:

// src/services/webhookHandler.ts
import crypto from 'crypto';
import { logger } from '../utils/logger';
import { metrics } from '../utils/metrics';
import { RedisQueue } from '../queue/redisQueue';

interface WebhookConfig {
  secret: string;
  toleranceSeconds?: number;
  queue: RedisQueue;
}

interface StripeEvent {
  id: string;
  type: string;
  created: number;
  data: {
    object: Record<string, unknown>;
  };
}

export class WebhookHandler {
  private secret: string;
  private tolerance: number;
  private queue: RedisQueue;

  constructor(config: WebhookConfig) {
    this.secret = config.secret;
    this.tolerance = config.toleranceSeconds ?? 300;
    this.queue = config.queue;
  }

  /**
   * Verifies Stripe webhook signature using HMAC-SHA256
   * @throws Error if signature is invalid or timestamp is too old
   */
  verifySignature(payload: string, headers: Record<string, string>): void {
    const signatureHeader = this.extractSignatureHeader(headers);
    const { timestamp, signature } = this.parseSignatureHeader(signatureHeader);
    
    this.validateTimestamp(timestamp);
    this.validateSignature(payload, timestamp, signature);
  }

  private extractSignatureHeader(headers: Record<string, string>): string {
    const signature = headers['stripe-signature'];
    if (!signature) {
      metrics.increment('webhook.signature_missing');
      throw new Error('Missing stripe-signature header');
    }
    return signature;
  }

  private parseSignatureHeader(header: string): { timestamp: string; signature: string } {
    const parts = header.split(',');
    const timestamp = parts.find(p => p.startsWith('t='))?.split('=')[1];
    const signature = parts.find(p => p.startsWith('v1='))?.split('=')[1];

    if (!timestamp || !signature) {
      metrics.increment('webhook.signature_invalid_format');
      throw new Error('Invalid signature format');
    }

    return { timestamp, signature };
  }

  private validateTimestamp(timestamp: string): void {
    const now = Math.floor(Date.now() / 1000);
    const age = now - parseInt(timestamp);

    if (age > this.tolerance) {
      metrics.increment('webhook.timestamp_expired');
      logger.warn('Webhook timestamp expired', { age, tolerance: this.tolerance });
      throw new Error('Timestamp too old');
    }
  }

  private validateSignature(payload: string, timestamp: string, providedSig: string): void {
    const signedPayload = `${timestamp}.${payload}`;
    const expectedSig = crypto
      .createHmac('sha256', this.secret)
      .update(signedPayload)
      .digest('hex');

    // Constant-time comparison to prevent timing attacks
    const valid = crypto.timingSafeEqual(
      Buffer.from(providedSig),
      Buffer.from(expectedSig)
    );

    if (!valid) {
      metrics.increment('webhook.signature_mismatch');
      logger.warn('Webhook signature mismatch');
      throw new Error('Invalid signature');
    }

    metrics.increment('webhook.signature_valid');
  }

  async handleEvent(payload: string, headers: Record<string, string>): Promise<void> {
    const startTime = Date.now();

    try {
      // Verify signature
      this.verifySignature(payload, headers);

      // Parse event
      const event: StripeEvent = JSON.parse(payload);

      // Check for duplicate (idempotency)
      const isDuplicate = await this.queue.isDuplicate(event.id);
      if (isDuplicate) {
        logger.info('Skipping duplicate event', { eventId: event.id });
        metrics.increment('webhook.duplicate_event');
        return;
      }

      // Enqueue for processing
      await this.queue.enqueue({
        eventId: event.id,
        eventType: event.type,
        payload: payload,
        receivedAt: new Date().toISOString(),
      });

      logger.info('Webhook enqueued', {
        eventId: event.id,
        eventType: event.type,
      });

      metrics.increment('webhook.processed');
      metrics.timing('webhook.processing_time', Date.now() - startTime);
    } catch (error) {
      logger.error('Failed to process webhook', {
        error: error instanceof Error ? error.message : 'Unknown error',
      });
      metrics.increment('webhook.error');
      throw error;
    }
  }
}

What improved?

• ✅ Extracted methods (easier to test and understand)

• ✅ Added logging and metrics

• ✅ Timing-safe comparison (security)

• ✅ Idempotency check

• ✅ Better error handling

• ✅ Type safety with interfaces

Tests still pass! This is the power of TDD.

The Fastify Route Handler

Now connect it to HTTP:

// src/api/webhookRoutes.ts
import { FastifyInstance } from 'fastify';
import { WebhookHandler } from '../services/webhookHandler';

export async function webhookRoutes(app: FastifyInstance) {
  const webhookHandler = new WebhookHandler({
    secret: process.env.STRIPE_WEBHOOK_SECRET!,
    queue: app.queue, // Injected dependency
  });

  app.post('/webhooks/stripe', {
    schema: {
      headers: {
        type: 'object',
        required: ['stripe-signature'],
        properties: {
          'stripe-signature': { type: 'string' },
        },
      },
    },
    handler: async (request, reply) => {
      try {
        // Get raw body (important for signature verification)
        const payload = JSON.stringify(request.body);
        const headers = request.headers as Record<string, string>;

        await webhookHandler.handleEvent(payload, headers);

        return reply.code(200).send({ received: true });
      } catch (error) {
        if (error instanceof Error) {
          if (error.message.includes('signature')) {
            return reply.code(401).send({ error: 'Invalid signature' });
          }
          if (error.message.includes('timestamp')) {
            return reply.code(400).send({ error: 'Expired timestamp' });
          }
        }
        
        return reply.code(500).send({ error: 'Internal server error' });
      }
    },
  });
}

Testing & Debugging

Testing Strategy

Unit Tests (Continued)

Testing error scenarios:

// tests/unit/webhookHandler.test.ts
describe('handleEvent', () => {
  it('should enqueue valid event', async () => {
    const queue = createMockQueue();
    const handler = new WebhookHandler({
      secret: 'whsec_test',
      queue,
    });

    const payload = createValidPayload();
    const headers = createValidHeaders(payload);

    await handler.handleEvent(payload, headers);

    expect(queue.enqueue).toHaveBeenCalledWith(
      expect.objectContaining({
        eventType: 'payment_intent.succeeded',
      })
    );
  });

  it('should reject duplicate events', async () => {
    const queue = createMockQueue({ isDuplicate: true });
    const handler = new WebhookHandler({ secret: 'whsec_test', queue });

    const payload = createValidPayload();
    const headers = createValidHeaders(payload);

    await handler.handleEvent(payload, headers);

    // Should NOT enqueue duplicate
    expect(queue.enqueue).not.toHaveBeenCalled();
  });
});

Integration Tests

Testing with real Redis:

// tests/integration/webhook.test.ts
import { FastifyInstance } from 'fastify';
import { createApp } from '../../src/app';
import { Redis } from 'ioredis';

describe('Webhook Integration', () => {
  let app: FastifyInstance;
  let redis: Redis;

  beforeAll(async () => {
    redis = new Redis(process.env.REDIS_URL);
    app = await createApp({ redis });
  });

  afterAll(async () => {
    await redis.quit();
    await app.close();
  });

  afterEach(async () => {
    await redis.flushdb(); // Clean test data
  });

  it('should accept and enqueue webhook', async () => {
    const payload = {
      id: 'evt_test_123',
      type: 'payment_intent.succeeded',
      data: { object: { id: 'pi_123' } },
    };

    const response = await app.inject({
      method: 'POST',
      url: '/webhooks/stripe',
      payload,
      headers: createValidSignature(payload),
    });

    expect(response.statusCode).toBe(200);

    // Verify event in queue
    const queueLength = await redis.llen('webhooks:queue');
    expect(queueLength).toBe(1);
  });

  it('should reject tampered payload', async () => {
    const payload = { id: 'evt_test_123', type: 'payment_intent.succeeded' };
    const headers = createValidSignature(payload);

    // Tamper with payload after signature creation
    payload.id = 'evt_tampered_999';

    const response = await app.inject({
      method: 'POST',
      url: '/webhooks/stripe',
      payload,
      headers,
    });

    expect(response.statusCode).toBe(401);
  });
});

Debugging Techniques

1. Strategic Console Logging

// Debug webhook signature verification
verifySignature(payload: string, headers: Record<string, string>): void {
  console.log('=== Signature Verification Debug ===');
  console.log('Payload length:', payload.length);
  console.log('Headers:', JSON.stringify(headers, null, 2));
  
  const signatureHeader = this.extractSignatureHeader(headers);
  console.log('Signature header:', signatureHeader);
  
  const { timestamp, signature } = this.parseSignatureHeader(signatureHeader);
  console.log('Timestamp:', timestamp, '(age:', Date.now() / 1000 - parseInt(timestamp), 'sec)');
  console.log('Provided signature:', signature);
  
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSig = crypto
    .createHmac('sha256', this.secret)
    .update(signedPayload)
    .digest('hex');
  console.log('Expected signature:', expectedSig);
  console.log('Match:', signature === expectedSig);
  console.log('===================================');
}

2. VS Code Debugger

Set breakpoint in VS Code, start debug mode (F5), make request:

// Breakpoint here
const expectedSig = crypto
  .createHmac('sha256', this.secret)
  .update(signedPayload)
  .digest('hex');

// In Debug Console:
// > signedPayload
// "16767890.{\"id\":\"evt_123\"}"
// > expectedSig
// "abc123..."
// > providedSig
// "xyz789..."

3. Request Replay Debugging

Save failing requests for replay:

// Middleware to capture requests
app.addHook('preHandler', async (request, reply) => {
  if (process.env.NODE_ENV === 'development') {
    const timestamp = Date.now();
    await fs.promises.writeFile(
      `./debug/requests/${timestamp}.json`,
      JSON.stringify({
        method: request.method,
        url: request.url,
        headers: request.headers,
        body: request.body,
      }, null, 2)
    );
  }
});

Later, replay exact request:

# Replay saved request
curl -X POST http://localhost:3000/webhooks/stripe \
  -H "$(cat debug/requests/1676789012345.json | jq -r '.headers | to_entries[] | "\(.key): \(.value)"')" \
  -d "$(cat debug/requests/1676789012345.json | jq -r '.body')"

4. Error Tracking with Sentry

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1, // 10% of transactions
});

// In error handler
catch (error) {
  Sentry.captureException(error, {
    contexts: {
      webhook: {
        eventId: event.id,
        eventType: event.type,
      },
    },
  });
  throw error;
}

When production error occurs, Sentry shows:

• Full stack trace

• Request context

• Breadcrumbs (recent logs)

• User session replay

Browser Automation

For E2E testing, I use Playwright:

Setup

// tests/e2e/payment-flow.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Payment Flow', () => {
  test('should process payment and trigger webhook', async ({ page, request }) => {
    // 1. Start app and Stripe webhook forwarding
    const stripeForwarder = await startStripeForwarding();

    // 2. Navigate to checkout
    await page.goto('http://localhost:3000/checkout');

    // 3. Fill payment form
    await page.fill('[data-testid="card-number"]', '4242424242424242');
    await page.fill('[data-testid="card-expiry"]', '12/25');
    await page.fill('[data-testid="card-cvc"]', '123');

    // 4. Submit payment
    await page.click('[data-testid="submit-payment"]');

    // 5. Wait for success message
    await expect(page.locator('[data-testid="payment-success"]')).toBeVisible({
      timeout: 10000,
    });

    // 6. Verify webhook was received
    await page.waitForTimeout(2000); // Give webhook time to process
    
    const webhookLogs = await request.get('http://localhost:3000/admin/webhook-logs');
    const logs = await webhookLogs.json();
    
    expect(logs).toContainEqual(
      expect.objectContaining({
        type: 'payment_intent.succeeded',
      })
    );

    // Cleanup
    await stripeForwarder.close();
  });
});

Visual Regression Testing

// tests/e2e/visual.spec.ts
import { test, expect } from '@playwright/test';

test('checkout page visual regression', async ({ page }) => {
  await page.goto('http://localhost:3000/checkout');
  
  // Take screenshot and compare with baseline
  await expect(page).toHaveScreenshot('checkout-empty.png', {
    maxDiffPixels: 100, // Allow small differences
  });

  // Fill form
  await page.fill('[data-testid="email"]', '[email protected]');
  
  // Screenshot with data
  await expect(page).toHaveScreenshot('checkout-filled.png');
});

Run tests:

# First time - creates baseline images
npx playwright test --update-snapshots

# Subsequent runs - compares against baseline
npx playwright test

# If UI changed intentionally, update baselines:
npx playwright test --update-snapshots

Code Review

My Code Review Checklist

What I Look For

1. Correctness

// ❌ Bad: Missing error handling
async function processPayment(orderId: string) {
  const order = await db.orders.findOne({ id: orderId });
  return stripe.charges.create({
    amount: order.total, // What if order is null?
    currency: 'usd',
  });
}

// ✅ Good: Proper error handling
async function processPayment(orderId: string): Promise<Stripe.Charge> {
  const order = await db.orders.findOne({ id: orderId });
  
  if (!order) {
    throw new NotFoundError(`Order ${orderId} not found`);
  }
  
  if (order.status !== 'pending') {
    throw new InvalidStateError('Order is not in pending state');
  }
  
  return stripe.charges.create({
    amount: order.total,
    currency: 'usd',
    idempotencyKey: `order_${orderId}`, // Prevent duplicate charges
  });
}

2. Test Coverage

# My standard: >80% coverage, 100% for critical paths
npm run test:coverage

# Output should show:
# Statements   : 85.23% ( 1234/1448 )
# Branches     : 82.15% ( 234/285 )
# Functions    : 88.45% ( 189/214 )
# Lines        : 85.67% ( 1198/1398 )

3. Security

// ❌ Bad: SQL injection vulnerability
app.get('/users', async (req, res) => {
  const name = req.query.name;
  const users = await db.query(`SELECT * FROM users WHERE name = '${name}'`);
  // Vulnerability: name = "' OR '1'='1" returns all users!
  res.json(users);
});

// ✅ Good: Parameterized query
app.get('/users', async (req, res) => {
  const name = req.query.name as string;
  const users = await db.query('SELECT * FROM users WHERE name = $1', [name]);
  res.json(users);
});

4. Performance

// ❌ Bad: N+1 query problem
async function getUsersWithOrders() {
  const users = await db.users.findMany();
  
  for (const user of users) {
    user.orders = await db.orders.findMany({ userId: user.id });
    // This runs a query for EACH user! 100 users = 101 queries
  }
  
  return users;
}

// ✅ Good: Single query with join
async function getUsersWithOrders() {
  return db.users.findMany({
    include: {
      orders: true, // Fetches orders in single query
    },
  });
}

My Code Review Comments (Examples)

Style: Nitpick (optional changes)

// Suggestion: Use early return for cleaner code
function processOrder(order: Order) {
  if (order.status === 'pending') {
    if (order.items.length > 0) {
      // ... 20 lines of logic
    }
  }
}

// Better:
function processOrder(order: Order) {
  if (order.status !== 'pending') return;
  if (order.items.length === 0) return;
  
  // ... 20 lines of logic (less nested)
}

Must Fix: Correctness issue

// ⚠️ Bug: Race condition!
let requestCount = 0;

app.get('/count', (req, res) => {
  requestCount++; // Not thread-safe
  res.json({ count: requestCount });
});

// Fix: Use atomic increment in Redis
app.get('/count', async (req, res) => {
  const count = await redis.incr('request_count');
  res.json({ count });
});

Question: Understanding needed

// Question: Why bypass validation here?
async function createUser(data: any) {
  // @ts-ignore
  return db.users.create(data); // Why ts-ignore?
}

// Expected response: "Legacy API, adding proper types in follow-up PR #123"

Key Takeaways

1. Write tests first: TDD prevents over-engineering and gives confidence

2. Refactor ruthlessly: Make code readable for your future self

3. Debug systematically: Logging, breakpoints, request replay

4. Automate E2E tests: Catches integration issues early

5. Review with intent: Look for correctness, security, performance

What's Next

In Part 4, we'll build APIs and integrate MCP:

• RESTful API design

• GraphQL considerations

• Model Context Protocol (MCP) integration

• API documentation and versioning

---

Code quality isn't just about working—it's about working well. See you in Part 4.