@SoapJS/Integr8

Framework-agnostic integration testing with real services, databases, and containers.

Test your APIs against real PostgreSQL, Redis, Kafka, and more - without mocking. Built on Testcontainers for reliable, reproducible tests.

⚠️ Beta: Currently in active development. API is stable but new features are being added.

Why Integr8?

• Real Environment Testing - Spin up actual databases and services with Docker
• Deterministic Tests - Smart database isolation strategies (savepoints, schemas, snapshots)
• Framework Agnostic - Works with Express, NestJS, Fastify, or vanilla Node.js
• Coverage Analysis - Track which endpoints are tested and enforce thresholds
• Auto-Discovery - Scan decorators or routes to generate tests automatically
• Fast Execution - Parallel testing with isolated environments per worker
• Dynamic Overrides - Mock external services without touching your code

Installation

Local Installation (Project-specific)

npm install --save-dev @soapjs/integr8

Use with npx:

npx integr8 init

Global Installation (Recommended)

Install globally to use integr8 command directly:

npm install -g @soapjs/integr8

Then use directly:

integr8 init
integr8 up
integr8 test

Framework Adapters (Optional)

For better integration with your framework:

# NestJS
npm install --save-dev @soapjs/integr8-nestjs

# Express
npm install --save-dev @soapjs/integr8-express

Quick Start

1. Initialize

npx integr8 init --interactive

This creates:

• integr8.api.config.js - Configuration file
• .gitignore entries

2. Write Your First Test

import { setupEnvironment, teardownEnvironment, getEnvironmentContext } from '@soapjs/integr8';

beforeAll(async () => {
  await setupEnvironment(require('../../integr8.api.config.js'));
});

afterAll(async () => {
  await teardownEnvironment();
});

describe('GET /users', () => {
  it('should return list of users', async () => {
    const ctx = getEnvironmentContext();
    
    const response = await ctx.getHttp().get('/users');
    
    expect(response.status).toBe(200);
    expect(response.data).toBeInstanceOf(Array);
  });
});

3. Start Environment & Run Tests

# Start all services (app, databases, etc.)
npx integr8 up

# Run tests
npx integr8 test

# Stop environment
npx integr8 down

Documentation

Getting Started

• Configuration Guide - How to configure services, databases, and more
• Writing Tests - Test patterns and best practices
• CLI Commands - Complete command reference

Advanced Features

• Database Strategies - Isolation strategies (savepoint, schema, snapshot)
• Seeding - Database seeding strategies
• Coverage Analysis - Track endpoint test coverage
• Scanning & Discovery - Auto-discover endpoints
• Override System - Mock services and dependencies
• Logging - Configure logging levels

Integration Guides

• NestJS Integration - Using with NestJS
• Express Integration - Using with Express
• Decorator Scanning - Auto-scan NestJS controllers

Core Concepts

Test Types

Integr8 supports multiple test levels:

• API Tests - Test HTTP endpoints with real services
• Component Tests - Test individual components with dependencies (coming soon)
• E2E Tests - Full end-to-end user flows (coming soon)
• Inter-Service Tests - Multi-service communication testing (coming soon)

Database Isolation

Choose the right strategy for your tests:

• Savepoint - Fast rollbacks (default)
• Schema - Isolated schemas per test
• Database - Separate database per test
• Snapshot - Filesystem-level snapshots

Learn more →

Seeding Strategies

• Once - Seed once at startup
• Per-File - Seed before each test file
• Per-Test - Seed before each test

Learn more →

🛠️ CLI Commands

Environment Management

integr8 up              # Start test environment
integr8 down            # Stop test environment
integr8 cleanup         # Clean up orphaned containers

Testing

integr8 test            # Run integration tests
integr8 test --watch    # Run in watch mode
integr8 ci              # Run in CI mode (up → test → down)

Code Generation

integr8 scan  # Discover endpoints
integr8 scan --decorators --generate-tests  # Auto-generate tests
integr8 create --url /users --method GET  # Create test for endpoint

Analysis

integr8 coverage   # Analyze endpoint coverage
integr8 coverage --threshold 80   # Enforce coverage threshold

Full command reference →

Example Configuration

module.exports = {
  testType: "api",
  testDir: "integr8/tests/api",
  services: [
    {
      name: "app",
      mode: "local",
      framework: "nestjs",
      http: {
        port: 3000,
        prefix: "/api"
      },
      local: {
        command: "npm start"
      }
    }
  ],
  databases: [
    {
      name: "main-db",
      category: "database",
      type: "postgresql",
      mode: "container",
      isolation: "savepoint",
      seeding: {
        strategy: "once",
        command: "npm run seed",
        file: undefined
      },
      local: undefined,
      container: {
        image: "postgres:15-alpine",
        containerName: "test-db",
        ports: [
          {
            host: 5432,
            container: 5432
          }
        ],
        environment: {
          POSTGRES_USER: "postgres",
          POSTGRES_PASSWORD: "password",
          POSTGRES_DB: "testdb"
        },
        envMapping: {
          host: "DB_HOST",
          port: "DB_PORT",
          username: "DB_USERNAME",
          password: "DB_PASSWORD",
          database: "DB_NAME",
          url: "DATABASE_URL"
        }
      }
    }
  ],
  scan: {
    decorators: {
      enabled: true,
      framework: 'nestjs',
      decorators: {
        controllers: ['@Controller', '@RestController'],
        routes: ['@Get', '@Post', '@Put', '@Delete', '@Patch'],
        statusCodes: ['@HttpCode'],
        apiDocs: ['@ApiResponse', '@ApiOperation']
      },
      paths: ['src'],
      // paths: ['src/controllers', 'src/modules'],
      exclude: ['**/*.spec.ts', '**/*.test.ts']
    },
    output: 'lista.json'
  }
};

Current Features

Supported Services

• HTTP/REST APIs (Express, NestJS, Fastify)
• PostgreSQL, MySQL, MongoDB
• Redis, Memcached
• RabbitMQ, Kafka
• Local processes or Docker containers

Testing Features

• API endpoint testing
• Database state management
• Parallel test execution
• Service health checks
• Environment isolation
• Auto-discovery (decorators & routes)
• Coverage analysis
• Test generation

Developer Experience

• Interactive CLI setup
• Colored terminal output
• Watch mode for tests
• CI/CD ready
• TypeScript support

Roadmap

(Near Future)

• [ ] WebSocket support
• [ ] gRPC client integration
• [ ] GraphQL endpoint testing
• [ ] Component-level tests (intra-service)
• [ ] Enhanced seeding with fixtures
• [ ] Inter-service testing
• [ ] Contract testing
• [ ] Service mesh support
• [ ] Performance/Load testing

v1.0.0

• [ ] Scenario DSL
• [ ] Advanced chaos testing
• [ ] Full E2E with browser automation
• [ ] Multi-protocol support (HTTP, WS, gRPC, GraphQL)

See full roadmap →

License

MIT © SoapJS

Related Packages

• @soapjs/integr8-nestjs - NestJS adapter with decorator scanning
• @soapjs/integr8-express - Express adapter with route discovery

Support

• Documentation
• Issue Tracker
• Discussions
• SoapJS Docs

Author

Radosław Kamysz

• Email: [email protected]
• GitHub: @soapjs
• Website: soapjs.com

Made with ❤️ by the SoapJS team