integration-testing-standards

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.