Depot Local

Test your schemas with a local Depot server running as a Docker container.

note

Requires Docker to be installed

Depot local is provided as a Docker image.

Link

Depot local instances can be started up manually as Docker containers with a standard Docker (or Docker compliant tool) CLI, with tools such as docker-compose, or programmatically by leveraging the depot-local npm package in a TypeScript project. For example:

const depot = new DepotLocal({
  depot: {
    port: 8089
  },
  dynamodb: {
    port: 8000
  }
});

beforeAll(async () => {
  await depot.start();
});

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

Once started, you can deploy a new Environment to your Depot local instance, using depot.deploy(). Use a helper method to easily construct an environment, for example from a namespace.

const namespace = Schemas.fromYamlFiles("test/schema/pet.yml");
const env = depot.deploy(Environment.fromNamespace(namespace));

Client mode

DepotLocalClient is a lightweight alternative to DepotLocal that connects to an already-running Depot Local instance without managing containers. Its main use case is when you want to instantiate Depot Local containers globally (e.g. via Jest's globalSetup/globalTeardown) and then access the functionality to deploy environments and seed data in individual tests. This helps work around Jest's limitation where the globalThis provided to globalSetup cannot be accessed in tests.

The workflow has two parts:

1. Global setup — create and start a DepotLocal instance, then persist its connection config to an environment variable.
2. Tests — create a DepotLocalClient from that environment variable and use it to deploy environments and seed data.

Jest example

globalSetup.ts

import { DepotLocal } from "@stage-tech/depot-local";

export default async function globalSetup() {
  const depot = new DepotLocal({
    depot: { port: 8089 },
    dynamodb: { port: 8000 },
  });

  await depot.start();

  // Serialize connection config to an env variable so tests can
  // create a DepotLocalClient without a reference to this instance.
  depot.setClientConfigToEnv();

  // Keep the instance on globalThis so globalTeardown can stop it.
  globalThis.__DEPOT_LOCAL__ = depot;
}

globalTeardown.ts

export default async function globalTeardown() {
  await globalThis.__DEPOT_LOCAL__?.stop();
}

Test file

import { DepotLocalClient, Environment, Schemas } from "@stage-tech/depot-local";

// Reads connection details from the env variable set in globalSetup.
const depot = DepotLocalClient.fromEnvConfig();

const namespace = Schemas.fromYamlFiles("test/schema/pet.yml");
const env = depot.deploy(Environment.fromNamespace(namespace));

fromEnvConfig() reads the DEPOT_LOCAL_CONFIG environment variable by default. You can use a custom variable name by passing it to both setClientConfigToEnv(name) and fromEnvConfig(name).

warning

Environments deployed through a DepotLocalClient are not tracked by the original DepotLocal instance. Calling depotLocal.stop() in globalTeardown will not clean up those environments. You must clean up environments created via the client yourself — for example by calling env.api(0).cleanup() in an afterAll or afterEach block within your tests.

Refer to the npm package page for further details and configuration options.