@floci/testcontainers

Node.js Testcontainers module for Floci — the open-source, drop-in replacement for LocalStack Community Edition.

Floci emulates 41 AWS services in a single container with:

• ~24 ms startup time (native image)
• ~13 MiB idle memory
• ~90 MB Docker image
• No auth tokens, no feature gates, MIT license

Installation

# npm
npm install --save-dev @floci/testcontainers

# yarn
yarn add --dev @floci/testcontainers

# pnpm
pnpm add --save-dev @floci/testcontainers

Quick start

import { S3Client, CreateBucketCommand, ListBucketsCommand } from '@aws-sdk/client-s3';
import { FlociContainer } from '@floci/testcontainers';

describe('S3', () => {
  let floci: Awaited<ReturnType<FlociContainer['start']>>;

  beforeAll(async () => {
    floci = await new FlociContainer().start();
  });

  afterAll(async () => {
    await floci.stop();
  });

  it('creates and lists a bucket', async () => {
    const s3 = new S3Client({
      endpoint: floci.getEndpoint(),
      region: floci.getRegion(),
      credentials: {
        accessKeyId: floci.getAccessKey(),
        secretAccessKey: floci.getSecretKey(),
      },
      forcePathStyle: true,
    });

    await s3.send(new CreateBucketCommand({ Bucket: 'my-bucket' }));
    const { Buckets } = await s3.send(new ListBucketsCommand({}));
    expect(Buckets?.map((b) => b.Name)).toContain('my-bucket');
  });
});

Sharing a container across tests

import { FlociContainer, StartedFlociContainer } from '@floci/testcontainers';

let floci: StartedFlociContainer;

beforeAll(async () => {
  floci = await new FlociContainer().start();
});

afterAll(async () => {
  await floci.stop();
});

Service configuration

Each of Floci's 41 services can be configured individually using typed config classes.

S3

import { FlociContainer, S3Config } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withS3Config(new S3Config(true, 7200))
  .start();

SQS

import { SqsConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withSqsConfig(new SqsConfig(true, 60, 262144))
  .start();

DynamoDB

import { DynamoDbConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withDynamoDbConfig(new DynamoDbConfig(true))
  .start();

Lambda

import { LambdaConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withLambdaConfig(new LambdaConfig(
    true,   // enabled
    256,    // defaultMemoryMb
    30,     // defaultTimeoutSeconds
    false,  // ephemeral
    true,   // hotReloadEnabled
  ))
  .start();

RDS (PostgreSQL / MySQL / MariaDB)

import { RdsConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withRdsConfig(new RdsConfig(true, 7001, 99, 'postgres:16-alpine'))
  .start();

ElastiCache (Redis / Valkey)

import { ElastiCacheConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withElastiCacheConfig(new ElastiCacheConfig(true, 'valkey/valkey:8'))
  .start();

OpenSearch

import { OpenSearchConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withOpenSearchConfig(new OpenSearchConfig(true, false))
  .start();

MSK (Kafka via Redpanda)

import { MskConfig } from '@floci/testcontainers';

const floci = await new FlociContainer()
  .withMskConfig(new MskConfig(true, false, 'redpandadata/redpanda:latest'))
  .start();

All available config classes

| Config class | AWS service | |---|---| | AcmConfig | AWS Certificate Manager | | ApiGatewayConfig | API Gateway (v1) | | ApiGatewayV2Config | API Gateway (v2) | | AppConfigConfig | AppConfig | | AppConfigDataConfig | AppConfig Data | | AthenaConfig | Athena | | BedrockRuntimeConfig | Bedrock Runtime | | CloudFormationConfig | CloudFormation | | CloudWatchLogsConfig | CloudWatch Logs | | CloudWatchMetricsConfig | CloudWatch Metrics | | CodeBuildConfig | CodeBuild | | CodeDeployConfig | CodeDeploy | | CognitoConfig | Cognito | | DynamoDbConfig | DynamoDB | | Ec2Config | EC2 | | EcrConfig | ECR | | EcsConfig | ECS | | EksConfig | EKS | | ElastiCacheConfig | ElastiCache | | ElbV2Config | ELB v2 | | EventBridgeConfig | EventBridge | | FirehoseConfig | Kinesis Firehose | | GlueConfig | Glue | | IamConfig | IAM | | KinesisConfig | Kinesis | | KmsConfig | KMS | | LambdaConfig | Lambda | | MskConfig | MSK (Kafka) | | OpenSearchConfig | OpenSearch | | PipesConfig | EventBridge Pipes | | RdsConfig | RDS | | ResourceGroupsTaggingConfig | Resource Groups Tagging | | S3Config | S3 | | SchedulerConfig | EventBridge Scheduler | | SecretsManagerConfig | Secrets Manager | | SesConfig | SES | | SesV2Config | SES v2 | | SnsConfig | SNS | | SqsConfig | SQS | | SsmConfig | SSM Parameter Store | | StepFunctionsConfig | Step Functions |

Container options

const floci = await new FlociContainer('floci/floci:latest')  // pin a specific tag
  .withRegion('eu-west-1')
  .withAccountId('111122223333')
  .withAvailabilityZone('eu-west-1a')
  .withDedicatedNetwork()   // isolated Docker network for stateful services
  .start();

Connection details

| Method | Returns | |---|---| | getEndpoint() | http://host:port — pass as endpoint to AWS SDK clients | | getRegion() | AWS region string | | getAccessKey() | Access key ("test" by default) | | getSecretKey() | Secret key ("test" by default) | | getAccountId() | AWS account ID | | getMappedPort(port) | Host port mapped from the given container port |

Docker image variants

| Tag | Description | |---|---| | floci/floci:latest | Native image — sub-second startup (recommended) | | floci/floci:x.y.z | Pinned release (native) |

Requirements

• Node.js 18+
• Docker (running locally or in CI)
• testcontainers >= 10.0.0

Related projects

• Floci — the emulator itself
• testcontainers-floci — Java / Spring Boot module
• testcontainers-floci-python — Python module
• Testcontainers for Node.js

License

MIT