/integration-testing-standards

name: integration-testing-standards
description: Integration testing patterns - database setup/teardown, API testing, contract testing, and Testkube execution.
user-invocable: false

Integration Testing Skill

> **Dynamic path:** All paths below use `components/<testing-component>/` as a placeholder. The actual directory depends on the testing component defined in `sdd/sdd-settings.yaml`. Delegate to the `techpack-settings` skill for directory path resolution — it maps component type (`testing`) + name to a filesystem path (e.g., `type=testing, name=integration` → `components/testing-integration/`).

Tests that verify multiple components working together with real infrastructure. Integration tests run in Kubernetes via Testkube for environment parity.

---

Overview

| Aspect | Details | |--------|---------| | Location | `components/<testing-component>/tests/integration/` | | Framework | Vitest | | Executor | Testkube | | Runs In | Kubernetes cluster | | Written By | Tester agent |

---

Test Structure

Directory Organization

components/<testing-component>/
├── tests/
│   └── integration/
│       ├── api/
│       │   ├── users.test.ts
│       │   ├── auth.test.ts
│       │   └── plans.test.ts
│       ├── db/
│       │   └── migrations.test.ts
│       └── helpers/
│           ├── client.ts
│           ├── database.ts
│           └── seed.ts
├── testsuites/
│   └── integration-suite.yaml
└── fixtures/
    └── seed-data.sql

---

Resource Files

For detailed guidance, read these on-demand:

• [database-strategies.md](resources/database-strategies.md) — Transaction rollback, truncate, cleanup
• [api-testing.md](resources/api-testing.md) — HTTP client, test patterns, examples
• [authentication.md](resources/authentication.md) — Login helpers, protected endpoint tests
• [testkube.md](resources/testkube.md) — Test definition YAML, suites, running tests

---

Contract Testing

Request/Response Validation

import { describe, it, expect } from 'vitest';
import Ajv2020 from 'ajv/dist/2020.js';
import openApiSpec from '../../../../contract/openapi.json';

const ajv = new Ajv2020({ allErrors: true });

describe('API Contract Compliance', () => {
  describe('POST /api/users', () => {
    it('response matches OpenAPI schema', async () => {
      const response = await client.post('/api/users', validUserData);

      const schema = openApiSpec.paths['/api/users'].post.responses['201'].content['application/json'].schema;
      const validate = ajv.compile(schema);
      const valid = validate(response.data);

      expect(valid).toBe(true);
      if (!valid) {
        console.error('Schema validation errors:', validate.errors);
      }
    });
  });
});

---

Rules

• **Real infrastructure** - Use actual database, no mocks for I/O
• **Environment parity** - Tests run in Kubernetes like production
• **Cleanup after each test** - Leave database in clean state
• **Independent tests** - Tests must not depend on each other
• **Idempotent tests** - Running twice produces same result
• **Reference spec and issue** - Use `@spec` and `@issue` JSDoc tags
• **Given/When/Then structure** - Clear test organization
• **Handle async properly** - Await all database and HTTP operations
• **Reasonable timeouts** - Set appropriate timeouts for network operations

---

Summary Checklist

Before committing integration tests, verify:

• [ ] Tests use real database (not mocked)
• [ ] Database cleanup happens after each test
• [ ] `@spec` and `@issue` tags present in file header
• [ ] Each acceptance criterion has corresponding tests
• [ ] Tests follow Given/When/Then structure
• [ ] HTTP client properly configured for test environment
• [ ] Authentication helpers used for protected endpoints
• [ ] Error scenarios tested (400, 401, 403, 404, 409, 500)
• [ ] Testkube YAML definition created/updated
• [ ] Tests run successfully via `testkube run test`

---

Input / Output

This skill defines no input parameters or structured output.