Local Service Testing

Overview

Test against real services locally before pushing. CI validates—it doesn't discover.

Core principle: If you mock what you can run locally, you're hiding bugs.

Announce at start: "I'm using local-service-testing to verify changes against real services."

The Iron Law

CI DISCOVERS NOTHING.
IF CI FINDS A BUG, YOUR LOCAL TESTING FAILED.

Local services exist for a reason. Use them.

Critical Clarification

Unit tests with mocks: REQUIRED (for TDD cycle) Integration tests with real services: ALSO REQUIRED

This skill does NOT replace mocking in unit tests. It ADDS the requirement for integration tests against real services. Both are mandatory.

When This Skill Applies

If your change touches any of these, you MUST test against the real service.

Service Detection

At session start, the

session-start.sh

Checking development services...
  ✓ Found docker-compose.yml

  Available services:
    ✓ postgres (running)
    ○ redis (not running)

  Tip: Start services with: docker-compose up -d

Starting Services

# Start all services
docker-compose up -d

# Start specific service
docker-compose up -d postgres

# Check status
docker-compose ps

Service Connection Strings

postgresql://localhost:5432/dev

redis://localhost:6379

amqp://localhost:5672

Check your project's

.env.example

Testing Protocol

Step 1: Identify Service Dependencies

Before testing, identify which services your changes require:

# Check what files you've changed
git diff --name-only HEAD~1

# Map to services:
# *.sql, *migration*, *model*, *entity*, *repository* → postgres
# *cache*, *redis*, *session*, *queue*, *pub*, *sub* → redis
# *worker*, *job*, *consumer* → queue service

Step 2: Ensure Services Running

# Start required services
docker-compose up -d postgres redis

# Verify they're ready
docker-compose ps

# Test connectivity
# Postgres
psql postgresql://localhost:5432/dev -c "SELECT 1"

# Redis
redis-cli ping

Step 3: Run Integration Tests

# Run integration tests (not unit tests with mocks)
pnpm test:integration

# Or run specific integration test suite
pnpm test --grep "integration"

# For Python projects
pytest tests/integration/

# For Go projects
go test -tags=integration ./...

Step 4: Verify Locally Before Pushing

Before

git push

# Full verification
pnpm build
pnpm lint
pnpm typecheck
pnpm test              # Unit tests
pnpm test:integration  # Integration tests against real services

Two-Layer Testing Requirement

Both Are Required

Why Both?

• Unit tests with mocks: Fast, enable RED-GREEN-REFACTOR, isolate logic
• Integration tests with services: Catch real-world failures mocks miss

We've experienced 80% failure rates with ORM migrations because unit tests with mocks passed but real databases rejected the changes.

What Mocks Miss

// Mock says this works
const mockDb = {
  query: jest.fn().mockResolvedValue([{ id: 1 }])
};

// But real postgres throws:
// ERROR: relation "users" does not exist
// ERROR: column "email" cannot be null
// ERROR: duplicate key violates unique constraint

Real services reveal:

• Schema mismatches
• Constraint violations
• Connection issues
• Transaction behavior
• Performance problems

Artifact Requirement

Before creating a PR, you must post local testing evidence to the issue.

Required Artifact Format

<!-- LOCAL-TESTING:START -->
## Local Service Testing

| Service | Status | Verification |
|---------|--------|--------------|
| postgres | ✅ Running | Migrations applied, queries executed |
| redis | ✅ Running | Cache operations verified |

**Tests Run:**
- `pnpm test:integration` - PASSED
- Manual verification of [specific feature]

**Tested At:** 2025-01-15T10:30:00Z
<!-- LOCAL-TESTING:END -->

Where to Post

Post as a comment on the GitHub issue you're working on. This is checked by the

validate-local-testing.sh

When Artifact is Required

The hook checks:

1. Does docker-compose.yml exist?
2. Do changed files match service patterns?
3. If yes to both → artifact required

If no services are relevant to your changes, no artifact is needed.

Common Patterns

Database Testing

// GOOD: Test against real postgres
describe('UserRepository (integration)', () => {
  beforeAll(async () => {
    await db.migrate.latest();
  });

  afterAll(async () => {
    await db.destroy();
  });

  it('creates user with unique email constraint', async () => {
    await userRepo.create({ email: 'test@example.com' });

    // Real postgres will throw on duplicate
    await expect(
      userRepo.create({ email: 'test@example.com' })
    ).rejects.toThrow(/unique constraint/);
  });
});

Cache Testing

// GOOD: Test against real redis
describe('CacheService (integration)', () => {
  beforeEach(async () => {
    await redis.flushdb();
  });

  it('expires keys after TTL', async () => {
    await cache.set('key', 'value', { ttl: 1 });

    expect(await cache.get('key')).toBe('value');

    await sleep(1100);

    expect(await cache.get('key')).toBeNull();
  });
});

API Testing

// GOOD: Test against real services
describe('POST /users (integration)', () => {
  it('creates user and caches result', async () => {
    const response = await request(app)
      .post('/users')
      .send({ email: 'new@example.com' });

    expect(response.status).toBe(201);

    // Verify in real database
    const user = await db('users').where({ email: 'new@example.com' }).first();
    expect(user).toBeDefined();

    // Verify in real cache
    const cached = await redis.get(`user:${user.id}`);
    expect(cached).toBeDefined();
  });
});

Troubleshooting

docker-compose logs [service]

pnpm migrate

.env

Checklist

Before creating PR:

• Identified all service dependencies for changes
• All required services are running locally
• Integration tests pass against real services
• Posted local testing artifact to issue
• Did not rely on mocks for service-dependent code

Integration

This skill is called by:

• tdd-full-coverage

  - For integration testing requirements

• issue-driven-development

  - Before PR creation

• verification-before-merge

  - As a merge gate

This skill is enforced by:

• validate-local-testing.sh

  - PreToolUse hook blocks PR without artifact

This skill references:

• environment-bootstrap

  - For service startup patterns

• session-start

  - For service detection at session start