typescript-e2e-testing

$2b

Workflow Selection Guide

IMPORTANT: Before starting any E2E testing task, identify the user's intent and load the appropriate workflow.

Detect User Intent → Select Workflow

User Says / Wants

Workflow to Load

File

"Set up E2E tests", "configure docker-compose", "add E2E to project", "create test helpers"

Setup

workflows/setup/workflow.md

"Write E2E tests", "add integration tests", "test this endpoint", "create e2e-spec"

Writing

workflows/writing/workflow.md

"Review E2E tests", "check test quality", "audit tests", "is this test correct?"

Reviewing

workflows/review/workflow.md

"Run E2E tests", "execute tests", "start docker and test", "check if tests pass"

Running

workflows/running/workflow.md

"Fix E2E tests", "debug tests", "tests are failing", "flaky test", "connection error"

Debugging

workflows/debugging/workflow.md

"Speed up E2E tests", "optimize tests", "tests are slow", "reduce test time"

Optimizing

workflows/optimize/workflow.md

Workflow Execution Protocol

• ALWAYS load the workflow file first - Read the full workflow before taking action

• Follow each step in order - Complete checkpoints before proceeding

• Load knowledge files as directed - Each workflow specifies which references/ files to read

• Verify compliance after completion - Re-read relevant reference files to ensure quality

Important: Each workflow includes instructions to load relevant knowledge from the references/ folder before and after completing tasks.

Knowledge Base Structure

references/

├── common/              # Shared testing fundamentals

│   ├── knowledge.md     # Core E2E concepts and test pyramid

│   ├── rules.md         # Mandatory testing rules (GWT, timeouts, logging)

│   ├── best-practices.md # Test design and cleanup patterns

│   ├── test-case-creation-guide.md # GWT templates for all scenarios

│   ├── nestjs-setup.md  # NestJS app bootstrap and Jest config

│   ├── debugging.md     # VS Code config and log analysis

│   └── examples.md      # Comprehensive examples by category

│

├── kafka/               # Kafka-specific testing

│   ├── knowledge.md     # Why common approaches fail, architecture

│   ├── rules.md         # Kafka-specific testing rules

│   ├── test-helper.md   # KafkaTestHelper implementation

│   ├── docker-setup.md  # Redpanda/Kafka Docker configs

│   ├── performance.md   # Optimization techniques

│   ├── isolation.md     # Pre-subscription pattern details

│   └── examples.md      # Kafka test examples

│

├── postgres/            # PostgreSQL-specific testing

│   ├── knowledge.md     # PostgreSQL testing concepts

│   ├── rules.md         # Cleanup, transaction, assertion rules

│   ├── test-helper.md   # PostgresTestHelper implementation

│   └── examples.md      # CRUD, transaction, constraint examples

│

├── mongodb/             # MongoDB-specific testing

│   ├── knowledge.md     # MongoDB testing concepts

│   ├── rules.md         # Document cleanup and assertion rules

│   ├── test-helper.md   # MongoDbTestHelper implementation

│   ├── docker-setup.md  # Docker and Memory Server setup

│   └── examples.md      # Document and aggregation examples

│

├── redis/               # Redis-specific testing

│   ├── knowledge.md     # Redis testing concepts

│   ├── rules.md         # TTL and pub/sub rules

│   ├── test-helper.md   # RedisTestHelper implementation

│   ├── docker-setup.md  # Docker configuration

│   └── examples.md      # Cache, session, rate limit examples

│

└── api/                 # API testing (REST, GraphQL, gRPC)

    ├── knowledge.md     # API testing concepts

    ├── rules.md         # Request/response assertion rules

    ├── test-helper.md   # Auth and Supertest helpers

    ├── examples.md      # REST, GraphQL, validation examples

    └── mocking.md       # MSW and Nock external API mocking

Quick Reference by Task

Tip: For detailed step-by-step guidance, use the [Workflows](#workflows) section above.

Setup New E2E Structure

Workflow: Setup E2E Test

• Read references/common/knowledge.md - Understand E2E fundamentals

• Read references/common/nestjs-setup.md - Project setup

• Read technology-specific docker-setup.md files as needed

Write Test Cases

Workflow: Writing E2E Test

• MANDATORY: Read references/common/rules.md - GWT pattern, timeouts

• Read references/common/test-case-creation-guide.md - Templates

• Read technology-specific files:

• Kafka: references/kafka/knowledge.md → test-helper.md → isolation.md

• PostgreSQL: references/postgres/rules.md → test-helper.md

• MongoDB: references/mongodb/rules.md → test-helper.md

• Redis: references/redis/rules.md → test-helper.md

• API: references/api/rules.md → test-helper.md

Review Test Quality

Workflow: Review E2E Test

• Read references/common/rules.md - Check against mandatory patterns

• Read references/common/best-practices.md - Quality standards

• Read technology-specific rules.md files

Run E2E Tests

Workflow: Running E2E Test

• Verify Docker infrastructure is running

• Run tests sequentially with npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1

• Follow failure protocol if tests fail

Debug Failing Tests

Workflow: Debugging E2E Test

• Read references/common/debugging.md

• Create /tmp/e2e-${E2E_SESSION}-failures.md tracking file

• Fix ONE test at a time

Optimize Test Performance

Workflow: Optimize E2E Test

• Read references/common/best-practices.md - Performance patterns

• Read references/kafka/performance.md for Kafka tests

• Measure baseline before making changes

Examples

• Read references/common/examples.md for general patterns

• Read technology-specific examples.md for detailed scenarios

Core Principles

0. Context Efficiency (Temp File Output)

ALWAYS redirect E2E test output to temp files, NOT console. E2E output is verbose and bloats agent context.

IMPORTANT: Redirect output to temp files only (NO console output). Use unique session ID to prevent conflicts.

# Generate unique session ID at start of debugging session

export E2E_SESSION=$(date +%s)-$$

# Standard pattern - redirect to file only (no console output)

npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1

# Read summary only (last 50 lines)

tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Get failure details

grep -B 2 -A 15 "FAIL\|✕" /tmp/e2e-${E2E_SESSION}-output.log

# Cleanup when done

rm -f /tmp/e2e-${E2E_SESSION}-*.log /tmp/e2e-${E2E_SESSION}-*.md

Temp Files (with ${E2E_SESSION} unique per agent):

• /tmp/e2e-${E2E_SESSION}-output.log - Full test output

• /tmp/e2e-${E2E_SESSION}-failures.log - Filtered failure output

• /tmp/e2e-${E2E_SESSION}-failures.md - Tracking file for one-by-one fixing

• /tmp/e2e-${E2E_SESSION}-debug.log - Debug runs

• /tmp/e2e-${E2E_SESSION}-verify.log - Verification runs

1. Real Infrastructure

Test against actual services via Docker. Never mock databases or message brokers for E2E tests.

2. GWT Pattern (Mandatory)

ALL E2E tests MUST follow Given-When-Then:

it('should create user and return 201', async () => {

  // GIVEN: Valid user data

  const userData = { email: 'test@example.com', name: 'Test' };

  // WHEN: Creating user

  const response = await request(httpServer)

    .post('/users')

    .send(userData)

    .expect(201);

  // THEN: User created with correct data

  expect(response.body.data.email).toBe('test@example.com');

});

3. Test Isolation

Each test MUST be independent:

• Clean database state in beforeEach

• Use unique identifiers (consumer groups, topics)

• Wait for async operations to complete

4. Specific Assertions

Assert exact values, not just existence:

// WRONG

expect(response.body.data).toBeDefined();

// CORRECT

expect(response.body).toMatchObject({

  code: 'SUCCESS',

  data: { email: 'test@example.com', name: 'Test' }

});

Project Structure

project-root/

├── src/

├── test/

│   ├── e2e/

│   │   ├── feature.e2e-spec.ts

│   │   ├── setup.ts

│   │   └── helpers/

│   │       ├── test-app.helper.ts

│   │       ├── postgres.helper.ts

│   │       ├── mongodb.helper.ts

│   │       ├── redis.helper.ts

│   │       └── kafka.helper.ts

│   └── jest-e2e.config.ts

├── docker-compose.e2e.yml

├── .env.e2e

└── package.json

Essential Jest Configuration

// test/jest-e2e.config.ts

const config: Config = {

  preset: 'ts-jest',

  testEnvironment: 'node',

  testMatch: ['**/*.e2e-spec.ts'],

  testTimeout: 25000,

  maxWorkers: 1,           // CRITICAL: Sequential execution

  clearMocks: true,

  forceExit: true,

  detectOpenHandles: true,

};

Technology-Specific Timeouts

Technology

Wait Time

Strategy

Kafka

10-20s max (polling)

Smart polling with 50ms intervals

PostgreSQL

<1s

Direct queries

MongoDB

<1s

Direct queries

Redis

<100ms

In-memory operations

External API

1-5s

Network latency

Failure Resolution Protocol

CRITICAL: Fix ONE test at a time. NEVER run full suite repeatedly while fixing.

When E2E tests fail:

• Initialize session (once at start):

export E2E_SESSION=$(date +%s)-$$

• Create tracking file: /tmp/e2e-${E2E_SESSION}-failures.md with all failing tests

• Select ONE failing test - work on only this test

• Run ONLY that test (never full suite):

npm run test:e2e -- -t "test name" > /tmp/e2e-${E2E_SESSION}-debug.log 2>&1

tail -50 /tmp/e2e-${E2E_SESSION}-debug.log

• Fix the issue - analyze error, make targeted fix

• Verify fix - run same test 3-5 times:

for i in {1..5}; do npm run test:e2e -- -t "test name" > /tmp/e2e-${E2E_SESSION}-run$i.log 2>&1 && echo "Run $i: PASS" || echo "Run $i: FAIL"; done

• Mark as FIXED in tracking file

• Move to next failing test - repeat steps 3-7

• Run full suite ONLY ONCE after ALL individual tests pass

• Cleanup: rm -f /tmp/e2e-${E2E_SESSION}-*.log /tmp/e2e-${E2E_SESSION}-*.md

WHY: Running full suite wastes time and context. Each failing test pollutes output, making debugging harder.

Common Patterns

Database Cleanup (PostgreSQL/MongoDB)

beforeEach(async () => {

  await new Promise(r => setTimeout(r, 500)); // Wait for in-flight

  await repository.clear();  // PostgreSQL

  // OR

  await model.deleteMany({}); // MongoDB

});

Kafka Test Helper Pattern

// Use pre-subscription + buffer clearing (NOT fromBeginning: true)

const kafkaHelper = new KafkaTestHelper();

await kafkaHelper.subscribeToTopic(outputTopic, false);

// In beforeEach: kafkaHelper.clearMessages(outputTopic);

Redis Cleanup

beforeEach(async () => {

  await redis.flushdb();

});

External API Mock (MSW)

mockServer.use(

  http.post('https://api.external.com/endpoint', () => {

    return HttpResponse.json({ status: 'success' });

  })

);

Async Event Verification (Kafka)

// Use smart polling instead of fixed waits

await kafkaHelper.publishEvent(inputTopic, event, event.id);

const messages = await kafkaHelper.waitForMessages(outputTopic, 1, 20000);

expect(messages[0].value).toMatchObject({ id: event.id });

Debugging Commands

All commands redirect output to temp files only (no console output).

# Initialize session (once at start)

export E2E_SESSION=$(date +%s)-$$

# Run specific test (no console output)

npm run test:e2e -- -t "should create user" > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 && tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Run specific file

npm run test:e2e -- test/e2e/user.e2e-spec.ts > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 && tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Run full suite

npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 && tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Get failure details from last run

grep -B 2 -A 15 "FAIL\|✕" /tmp/e2e-${E2E_SESSION}-output.log

# Debug with breakpoints (requires console for interactive debugging)

node --inspect-brk node_modules/.bin/jest --config test/jest-e2e.config.ts --runInBand

# View application logs (limited)

tail -100 logs/e2e-test.log

grep -i error logs/e2e-test.log | tail -50

# Cleanup session files

rm -f /tmp/e2e-${E2E_SESSION}-*.log /tmp/e2e-${E2E_SESSION}-*.md

Anti-Patterns to Avoid

• Multiple WHEN actions - Split into separate tests

• Conditional assertions - Create deterministic test cases

• Shared state between tests - Clean in beforeEach

• Mocking databases - Use real connections

• Skipping cleanup - Always clean before AND after

• Fixing multiple tests at once - Fix one at a time

• Generic assertions - Assert specific values

• fromBeginning: true for Kafka - Use pre-subscription + buffer clearing