--- title: "typescript-e2e-testing by bmad-labs · skilld" canonical_url: "https://skilld.dev/gh/bmad-labs/skills" meta: description: "Writes E2E and integration tests for NestJS projects using Jest and supertest against real Docker infrastructure (Kafka, PostgreSQL, MongoDB, Redis) following the… From bmad-labs/skills." "og:description": "Writes E2E and integration tests for NestJS projects using Jest and supertest against real Docker infrastructure (Kafka, PostgreSQL, MongoDB, Redis) following the… From bmad-labs/skills." "og:title": "typescript-e2e-testing by bmad-labs" "twitter:description": "Writes E2E and integration tests for NestJS projects using Jest and supertest against real Docker infrastructure (Kafka, PostgreSQL, MongoDB, Redis) following the… From bmad-labs/skills." "twitter:title": "typescript-e2e-testing by bmad-labs" --- ` [All skills](https://skilld.dev/skills) [![bmad-labs avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fbmad-labs.png%3Fsize%3D96)](https://skilld.dev/gh/bmad-labs) # **/typescript-e2e-testing** [@3bcc7a6](https://github.com/bmad-labs/skills/commit/3bcc7a62918c37eb96e431d654b6c9541aa19d0c "Your agent reads SKILL.md at commit 3bcc7a6") by [bmad-labs](https://skilld.dev/gh/bmad-labs)· [bmad-labs](https://skilld.dev/gh/bmad-labs)/ [skills](https://skilld.dev/gh/bmad-labs/skills)·15 stars 4 E2E and integration testing for TypeScript/NestJS projects using Jest, supertest, and real infrastructure via Docker (Kafka, PostgreSQL, MongoDB, Redis) with the Given-When-Then pattern. Use whenever the user is working on \`.e2e-spec.ts\` files or anything under \`test/e2e/\`, or asks to set up, write, review, run, debug, or optimize E2E or integration tests — including flaky tests, docker-compose for tests, Kafka/Redpanda consumers, test isolation, or GWT compliance. - 102 files - 406 KB - Updated 5 months ago - [GitHub](https://github.com/bmad-labs/skills/blob/3bcc7a62918c37eb96e431d654b6c9541aa19d0c/skills/typescript-e2e-testing/SKILL.md "View SKILL.md on GitHub") - [1 alert](#third-party-checks "Third-party checks: 1 alert · 5 checks · Risk SAFE") ## SKILL.md 14.8 KB **≈124** tokens always: the name and description. **≈3.7k** when used: this file. **≈100k** more on demand in 101 files. ## E2E Testing Skill E2E testing validates complete workflows from user perspective, using real infrastructure via Docker. --- ### Workflows For comprehensive step-by-step guidance, use the appropriate workflow: | Workflow | When to Use | | --- | --- | | [Setup E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/setup/workflow.md) | Setting up E2E infrastructure for a new or existing project | | [Writing E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/writing/workflow.md) | Creating new E2E test cases with proper GWT pattern | | [Review E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/review/workflow.md) | Reviewing existing tests for quality and correctness | | [Running E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/running/workflow.md) | Executing tests with proper verification | | [Debugging E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/debugging/workflow.md) | Systematically fixing failing tests | | [Optimize E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/optimize/workflow.md) | Improving test suite performance | ### 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 1. **ALWAYS load the workflow file first** - Read the full workflow before taking action 2. **Follow each step in order** - Complete checkpoints before proceeding 3. **Load knowledge files as directed** - Each workflow specifies which `references/` files to read 4. **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](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/setup/workflow.md) 1. Read `references/common/knowledge.md` - Understand E2E fundamentals 2. Read `references/common/nestjs-setup.md` - Project setup 3. Read technology-specific `docker-setup.md` files as needed #### Write Test Cases **Workflow**: [Writing E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/writing/workflow.md) 1. **MANDATORY**: Read `references/common/rules.md` - GWT pattern, timeouts 2. Read `references/common/test-case-creation-guide.md` - Templates 3. 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](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/review/workflow.md) 1. Read `references/common/rules.md` - Check against mandatory patterns 2. Read `references/common/best-practices.md` - Quality standards 3. Read technology-specific `rules.md` files #### Run E2E Tests **Workflow**: [Running E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/running/workflow.md) 1. Verify Docker infrastructure is running 2. Run tests sequentially with `npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1` 3. Follow failure protocol if tests fail #### Debug Failing Tests **Workflow**: [Debugging E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/debugging/workflow.md) 1. Read `references/common/debugging.md` 2. Create `/tmp/e2e-${E2E_SESSION}-failures.md` tracking file 3. Fix ONE test at a time #### Optimize Test Performance **Workflow**: [Optimize E2E Test](https://skilld.dev/gh/bmad-labs/skills/typescript-e2e-testing/-/workflows/optimize/workflow.md) 1. Read `references/common/best-practices.md` - Performance patterns 2. Read `references/kafka/performance.md` for Kafka tests 3. 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: 1. **Initialize session** (once at start): ``` export E2E_SESSION=$(date +%s)-$$ ``` 2. **Create tracking file**: `/tmp/e2e-${E2E_SESSION}-failures.md` with all failing tests 3. **Select ONE failing test** - work on only this test 4. **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 ``` 5. **Fix the issue** - analyze error, make targeted fix 6. **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 ``` 7. **Mark as FIXED** in tracking file 8. **Move to next failing test** - repeat steps 3-7 9. **Run full suite ONLY ONCE** after ALL individual tests pass 10. **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 1. **Multiple WHEN actions** - Split into separate tests 2. **Conditional assertions** - Create deterministic test cases 3. **Shared state between tests** - Clean in beforeEach 4. **Mocking databases** - Use real connections 5. **Skipping cleanup** - Always clean before AND after 6. **Fixing multiple tests at once** - Fix one at a time 7. **Generic assertions** - Assert specific values 8. **fromBeginning: true for Kafka** - Use pre-subscription + buffer clearing Source: [SKILL.md on GitHub](https://github.com/bmad-labs/skills/blob/3bcc7a62918c37eb96e431d654b6c9541aa19d0c/skills/typescript-e2e-testing/SKILL.md) ## Third-party checks
1 alert16d5 checks · Risk SAFE - Gen Agent Trust Hub16d This skill provides comprehensive workflows and reference materials for E2E testing in TypeScript/NestJS projects. It uses standard development tools like Jest, Docker, and shell commands. No malicious patterns or security risks were detected. - Socket16d No alerts - Snyk16d Risk: LOW · No issues - Runlayer7mo 30/103 files flagged - ZeroLeaks5mo Score: 93/100 · 2 sections analyzed
## Provenance [Signed by skilld at 3bcc7a6.](https://github.com/bmad-labs/skills/commit/3bcc7a62918c37eb96e431d654b6c9541aa19d0c "3bcc7a62918c37eb96e431d654b6c9541aa19d0c") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions. Last checked against GitHub 2 days ago. Activeupdated 5 months ago ## Topics - [TypeScript](https://skilld.dev/skills/tag/typescript "Type-heavy workflows, generics, type audits") - jest - nestjs - e2e-testing - supertest - docker - kafka - postgres - mongodb - redis - integration-testing - gwt-pattern ## README badge ![README badge for bmad-labs/skills](https://skilld.dev/b/bmad-labs/skills?theme=light&label=0) ## What it does Writes E2E and integration tests for NestJS projects using Jest and supertest against real Docker infrastructure (Kafka, PostgreSQL, MongoDB, Redis) following the Given-When-Then pattern. Covers test setup, writing, review, debugging, and optimization workflows with technology-specific helpers and isolation strategies for each service. Generated from the current SKILL.md. ## Frequently asked
Does this skill work with NestJS only? The skill is built for NestJS projects using Jest and supertest, but the patterns and workflows apply to any TypeScript backend with HTTP endpoints. Technology-specific helpers exist for Kafka, PostgreSQL, MongoDB, and Redis.
Do I need Docker running to use this skill? Yes. The skill assumes real infrastructure via Docker (Kafka, PostgreSQL, MongoDB, Redis). Tests execute against actual services, not mocks.
What if my E2E tests are flaky or failing? The Debugging E2E Test workflow provides a systematic protocol: fix one test at a time using isolated test runs, verify with 3-5 consecutive runs before moving to the next failure, then run the full suite only once all tests pass individually.
Does this skill cover GraphQL or gRPC testing? Yes. The API testing reference includes examples for REST, GraphQL, and gRPC, plus external API mocking with MSW and Nock.
What is the Given-When-Then pattern and is it mandatory? GWT is the mandatory test structure: Given describes setup state, When describes the action under test, Then describes expected outcomes. All E2E tests in this skill must follow this pattern.
Generated from the current SKILL.md. These answers refresh after source changes. ## Related skills - - - - - -