Tap Test

Tap Test - Real API Integration Test Generator

Generate production-grade HTTP-level integration/e2e tests that simulate real client behavior against a live API + real database.

What is a Tap Test?

A "tap test" taps into your API exactly like a real client would:

• Real HTTP requests (not function calls)
• Real database (not mocks)
• Real server (lightweight Fastify instance)
• Real responses captured via EventEmitter or HTTP endpoints
• Real cleanup after each test

Pattern

1. beforeAll: cleanup DB → seed test data → start Fastify server
2. beforeEach: reset test users + clear captured responses
3. test: POST to API → wait for responses → verify via HTTP state endpoint + DB queries
4. afterAll: cleanup DB → stop server

Architecture

Test File
  ├── Fastify test server (port 3999)
  │   ├── POST /api/send          → simulate incoming message
  │   ├── GET  /api/state/:id     → read user/session state
  │   ├── GET  /api/chat/:id      → read conversation history
  │   └── DELETE /api/user/:id    → reset user for next test
  ├── EventEmitter capture        → collect outgoing responses
  ├── Direct DB queries           → verify transactions, records
  └── Cleanup helpers             → isolated test data (prefix/marker pattern)

Step-by-Step Process

1. Explore the project

• Find the main message processing function (router, handler, engine)
• Find the gateway/provider layer (WhatsApp, Slack, etc.)
• Find existing test setup (cleanup, seed functions)
• Identify the DB client and tables

2. Create test data isolation

• Use a phone prefix or unique marker for test data (e.g., 97259900%)
• Use a category/area marker for content data (e.g., area='test')
• Create cleanupTestData() that deletes ALL test data across all tables
• Create seedTestData() that inserts minimal required test content

3. Build the test server

import Fastify from 'fastify';

const app = Fastify({ logger: false });
const TEST_PORT = 3999;

// Capture responses via provider's EventEmitter
const captured: Response[] = [];
provider.onResponse((r) => captured.push(r));

// POST endpoint - simulate incoming messages
app.post('/api/send', async (req, reply) => {
  const msg = provider.parseWebhook(req.body);
  await engine.handleMessage(msg);
  return { success: true };
});

// GET endpoint - read state
app.get('/api/state/:phone', async (req) => {
  const user = await getUser(req.params.phone);
  const session = await getSession(user.id);
  return { user, session };
});

// DELETE endpoint - reset user
app.delete('/api/user/:phone', async (req) => {
  // cascade delete all user data
});

await app.listen({ port: TEST_PORT, host: '127.0.0.1' });

4. Write HTTP helper functions

async function sendText(phone: string, text: string) {
  return fetch(`${BASE}/api/send`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone, type: 'text', text }),
  });
}

async function waitForResponses(n: number, timeout = 15000) {
  const start = Date.now();
  while (captured.length < n && Date.now() - start < timeout) {
    await new Promise(r => setTimeout(r, 100));
  }
  return captured;
}

async function getState(phone: string) {
  const res = await fetch(`${BASE}/api/state/${phone}`);
  return res.json();
}

5. Write test cases

Each test should:

• clearCaptured() before sending
• Send via HTTP (not direct function call)
• waitForResponses(n) for async processing
• Verify response content
• Verify state via HTTP GET
• Verify DB records via direct Supabase queries

6. Test categories to cover

• Happy path flows (full user journey start to finish)
• Error handling (invalid input, missing data)
• State transitions (verify session state after each step)
• DB verification (transactions, records created)
• Multi-user concurrent (parallel requests)
• Chat history (conversation recorded correctly)

Key Principles

• No mocks for core logic - the whole point is testing the real stack
• Mock only external services (WhatsApp API, LLM) via provider pattern
• Isolated test data - unique prefixes, cleanup before AND after
• Sequential execution - use singleFork: true in vitest for DB consistency
• Generous timeouts - real DB operations take time (10-30s per test)
• Wait, don't assume - use waitForResponses() pattern for async processing

Vitest Config

// vitest.config.ts
export default defineConfig({
  test: {
    pool: 'forks',
    poolOptions: { forks: { singleFork: true } },
    env: { WHATSAPP_PROVIDER: 'mock' }, // or equivalent
  },
});

Example Test

it('should onboard new user via HTTP', async () => {
  clearCaptured();
  await sendText(PHONE, 'hello');
  const responses = await waitForResponses(1);

  expect(responses[0].content).toContain('Welcome');

  const state = await getState(PHONE);
  expect(state.session.state).toBe('onboarding');
  expect(state.user).not.toBeNull();
});

Tap Test - Real API Integration Tests for AI-Era Development

## 🚨 DANGER: AI Agents Can Damage Your Database

>

When tests fail, AI agents try to remove obstacles. Your database is the obstacle. Agents can and will: disable RLS policies, delete real data, drop tables, widen DELETE statements, or grant themselves permissions - whatever it takes to make tests green.

>

This skill is a prompt. A prompt cannot prevent this. It works well in happy-path scenarios, but when things get hard, no amount of instructions guarantees safe behavior.

>

### Protect Yourself

>

- Use read-only DB credentials. You can run against production if the agent has no write access. Many devs already work with a read-only user - that's safe.

- Or use a separate test database if tests need write access.

- Add [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) to block destructive commands (DROP, TRUNCATE, ALTER, GRANT).

- Lock down RLS so the agent can't disable it.

- Review generated tests before running them.

>

Bottom line: Don't give the agent write access to data you care about.

The Problem: AI-Generated Tests Are Often Useless

When you ask an AI coding agent to "write tests", you typically get:

• Mock-heavy tests that test nothing real - they verify your mocks work, not your code
• Unit tests for internal functions that pass even when the actual API is broken
• Snapshot tests that just freeze current behavior without understanding it
• Tests that check implementation details instead of actual user-facing behavior

The result? A green test suite that gives you false confidence. Your tests pass, but your API is broken in production because no test ever sent a real HTTP request to a real server with a real database.

"100% test coverage, 0% confidence." - Every team that relied on mocked integration tests

The Solution: Tap Tests

A Tap Test "taps" into your API exactly like a real client would:

What Makes This Different

Traditional test:                    Tap test:

mock(db.query) → return fake data    Client → HTTP POST → Real Server → Real DB
call handler(fakeReq)                         ← HTTP Response ←
assert handler returned something              + verify DB state
                                               + verify side effects

Architecture

Test File
  |
  ├── Fastify test server (port 3999)
  │   ├── POST /api/send          → simulate incoming message
  │   ├── GET  /api/state/:id     → read user/session state
  │   ├── GET  /api/chat/:id      → read conversation history
  │   └── DELETE /api/user/:id    → reset user for next test
  │
  ├── EventEmitter capture        → collect outgoing responses
  ├── Direct DB queries           → verify transactions, records
  └── Cleanup helpers             → isolated test data (prefix/marker)

Who Is This For?

Any application with a server that has an API layer - which is the most popular architecture in modern development:

• REST APIs (Express, Fastify, Hono, etc.)
• WhatsApp/Telegram bots with webhook handlers
• SaaS backends with CRUD operations
• Microservices with HTTP communication
• Any system where clients talk to your server via HTTP

If your app has routes that handle requests and interact with a database, tap tests are for you.

Quick Start

1. Install the Skill

Copy the SKILL.md to your Claude Code skills directory:

# Personal (available in all projects)
mkdir -p ~/.claude/skills/tap-test
cp SKILL.md ~/.claude/skills/tap-test/SKILL.md

# Or project-level (available only in this project)
mkdir -p .claude/skills/tap-test
cp SKILL.md .claude/skills/tap-test/SKILL.md

2. Use It

In Claude Code, just say:

/tap-test

Or describe what you want naturally:

"Write real integration tests for my API"
"Create tap tests for the user registration flow"
"Test my WhatsApp bot with real HTTP requests"

Claude will automatically: 1. Explore your project structure 2. Find your routes, handlers, and DB client 3. Create a test server that mirrors your API 4. Write tests that send real HTTP requests 5. Verify both responses AND database state 6. Set up proper cleanup for test isolation

The Pattern

1. beforeAll:  cleanup DB → seed test data → start Fastify server
2. beforeEach: reset test users → clear captured responses
3. test:       POST to API → wait for responses → verify HTTP state + DB
4. afterAll:   cleanup DB → stop server

Example Test

import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
import Fastify from 'fastify';

const TEST_PORT = 3999;
const BASE = `http://127.0.0.1:${TEST_PORT}`;
const captured: Response[] = [];

// Helper: send a message like a real client
async function sendText(phone: string, text: string) {
  return fetch(`${BASE}/api/send`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone, type: 'text', text }),
  });
}

// Helper: wait for async responses
async function waitForResponses(n: number, timeout = 15000) {
  const start = Date.now();
  while (captured.length < n && Date.now() - start < timeout) {
    await new Promise(r => setTimeout(r, 100));
  }
  return captured;
}

// Helper: check state via HTTP (like a real client would)
async function getState(phone: string) {
  const res = await fetch(`${BASE}/api/state/${phone}`);
  return res.json();
}

describe('User Onboarding Flow', () => {
  beforeAll(async () => {
    await cleanupTestData();
    await seedTestData();
    await startTestServer();
  });

  beforeEach(() => {
    captured.length = 0;
  });

  afterAll(async () => {
    await cleanupTestData();
    await stopTestServer();
  });

  it('should onboard new user via HTTP', async () => {
    await sendText('972599001234', 'hello');
    const responses = await waitForResponses(1);

    // Verify response content
    expect(responses[0].content).toContain('Welcome');

    // Verify state via HTTP
    const state = await getState('972599001234');
    expect(state.session.state).toBe('onboarding');

    // Verify database directly
    const { data } = await supabase
      .from('users')
      .select()
      .eq('phone', '972599001234')
      .single();
    expect(data).not.toBeNull();
    expect(data.created_at).toBeDefined();
  });
});

Key Principles

Vitest Configuration

// vitest.config.ts
export default defineConfig({
  test: {
    pool: 'forks',
    poolOptions: { forks: { singleFork: true } },
    testTimeout: 30000,
    env: { WHATSAPP_PROVIDER: 'mock' },
  },
});

Test Data Isolation

const TEST_PHONE_PREFIX = '97259900';

async function cleanupTestData() {
  // Delete ALL test data across all tables
  await supabase.from('messages').delete().like('phone', `${TEST_PHONE_PREFIX}%`);
  await supabase.from('sessions').delete().like('phone', `${TEST_PHONE_PREFIX}%`);
  await supabase.from('users').delete().like('phone', `${TEST_PHONE_PREFIX}%`);
  // Also clean content test data
  await supabase.from('content').delete().eq('area', 'test');
}

async function seedTestData() {
  await supabase.from('content').insert([
    { area: 'test', title: 'Test Item 1', body: 'Test content' },
    { area: 'test', title: 'Test Item 2', body: 'More test content' },
  ]);
}

What Tests Should Cover

1. Happy path flows - Full user journey from start to finish 2. Error handling - Invalid input, missing data, edge cases 3. State transitions - Verify session state after each step 4. DB verification - Transactions created, records updated 5. Multi-user concurrent - Parallel requests don't interfere 6. Chat history - Conversations recorded correctly

---

Using Skills in Claude Code & Coding Agents

What Are Skills?

Skills are modular, filesystem-based capabilities that extend Claude Code's functionality. They package instructions, metadata, and optional resources that Claude uses automatically when relevant to your task.

How Skills Work

Skills operate on a progressive disclosure model:

This means you can bundle comprehensive documentation and examples without paying context cost for unused content.

Skill File Structure

my-skill/
├── SKILL.md              # Required: instructions + metadata
├── reference.md          # Optional: detailed guidance
├── examples.md           # Optional: sample outputs
├── templates/            # Optional: templates
└── scripts/              # Optional: executable code

SKILL.md Anatomy

---
name: my-skill
description: "What it does. When to use it."
disable-model-invocation: false   # true = only /command triggers it
user-invocable: true              # true = user can type /my-skill
allowed-tools: Read, Grep, Bash   # tools the skill can use
---

# Instructions for Claude to follow when skill is active

Installing Skills

# Personal (all projects)
cp -r my-skill ~/.claude/skills/

# Project-level (one project)
cp -r my-skill .claude/skills/

# As a plugin
claude plugin install https://github.com/user/my-skills

Implementing Skills in Your Coding Agent

If you're building a coding agent (with Claude Code, Agent SDK, or API), skills let you:

1. Encapsulate domain knowledge - Package testing strategies, deployment procedures, code review checklists 2. Standardize workflows - Every team member's agent follows the same patterns 3. Share across projects - Personal skills work everywhere, project skills travel with the repo 4. Progressive loading - Only load what's needed, keeping context lean

Best Practices for Skill Authors

1. Single Responsibility - One skill = one focused capability 2. Clear Descriptions - Include keywords users would naturally say 3. Progressive Disclosure - Core in SKILL.md, details in supporting files 4. Include Examples - Show concrete inputs and expected outputs 5. Test Isolation - Skills shouldn't depend on global state

---

Why Tap Tests Matter for AI Development

As AI coding agents write more of our tests, the quality of test instructions matters more than ever. Without clear guidance, AI agents default to:

• Mocking everything (path of least resistance)
• Testing implementation details (fragile, breaks on refactor)
• Generating high coverage with low value (vanity metrics)

Tap Test as a skill solves this by giving the AI agent a clear, opinionated framework for writing tests that actually verify your system works.

When you say /tap-test, the agent doesn't guess - it follows a proven pattern that produces tests you can trust.

---

License

MIT

Author

Created by Aviz - Building tools for the AI-native developer workflow.