Depot-Local

Depot supports running its Connector component locally, in order to perform tests in isolation with any deployed database (on locations where feasible). And by using lambda or GQL apis, operations can be run on it. To run depot locally, you need to have Docker installed and running.

Setup

To run depot-local install @stage-tech/depot-local as dependency in your project.

Depot-local can be configured with the following options:

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

const depot = new DepotLocal({
    depot: {}, //required and is used to pass additional configuration to depot
    dynamodb: {}, //required and is used to pass additional configuration to dynamodb
    postgres: {}, //Optional and is used to pass additional configuration to postgres
    snowflake: {}, //Optional and is used to pass additional configuration to snowflake
    fakesnow: {} //Optional, serves Snowflake locations from a fakesnow container instead of an account
});

after configuring depot-local, you can start it with depot.start() and stop it with depot.stop()

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

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

Pull the Docker images before the tests

A container start that has to pull its image does so inside its start timeout, and a cold pull fails as a flaky timeout. Pull the images first, in the global setup of the test runner. Each package ships global setups for Vitest and Jest:

// vitest.config.ts
export default defineConfig({
    test: {globalSetup: ['@stage-tech/depot-local/global-setup-docker-core']},
});

Package	Global setup	Pulls
@stage-tech/depot-local	global-setup-docker-core	The depot-local container, DynamoDB and the Testcontainers reaper
@stage-tech/depot-local	global-setup-docker-postgres	The core images and Postgres
@stage-tech/depot-local	global-setup-docker-fakesnow	The core images and fakesnow
@stage-tech/depot-test	global-setup-docker-fakesnow	fakesnow, the reaper and the tiny image of Java Testcontainers, for FAKESNOW locations
@stage-tech/depot-test	global-setup-docker-postgres	Postgres, the reaper and the tiny image, for AURORA locations
@stage-tech/depot-test	global-setup-docker-all	Both

For another set of depot-local services (elasticsearch, fakesnow, postgres), write a global setup of your own. Vitest resolves a relative globalSetup path against the root of each project, so a shared config needs an absolute path.

// test/global-setup-docker.ts
import {dockerGlobalSetup} from "@stage-tech/depot-local";

export default dockerGlobalSetup(["fakesnow", "postgres"]);

In a CI step or a script, each package has a bin that pulls the images of the services named; --print writes their names instead. The two packages pull different images for the same service, so pull with the bin of each harness the tests use:

Tests run with	CI step	With no service named
Depot Local	depot-local-pull-docker-images [elasticsearch] [fakesnow] [postgres]	The core images only
Depot Test, for FAKESNOW and AURORA locations	depot-test-pull-docker-images [fakesnow] [postgres]	Both services

postgres is the Postgres build with plv8 that the Depot platform publishes, public.ecr.aws/i2t0z4e9/depot-postgres. Images already in the local Docker cache are left alone, so an image both bins name is pulled once.

# Depot Local only
npx depot-local-pull-docker-images fakesnow postgres
npx depot-local-pull-docker-images --print fakesnow

# Depot Test only
npx depot-test-pull-docker-images fakesnow

# Depot Local and Depot Test in the same job
npx depot-local-pull-docker-images fakesnow postgres
npx depot-test-pull-docker-images fakesnow postgres

The depot-test reaper and tiny image come from ghcr.io and public.ecr.aws. The depot-local reaper is testcontainers/ryuk from Docker Hub, unless RYUK_CONTAINER_IMAGE names another.

Variable	Effect	Default
DEPOT_LOCAL_SKIP_IMAGE_PREPARE, DEPOT_TEST_SKIP_IMAGE_PREPARE	true: the global setup pulls nothing, for a runner that pulls in its own step	unset
DEPOT_LOCAL_QUIET_IMAGE_PULL, DEPOT_TEST_QUIET_IMAGE_PULL	true: no progress lines during a pull	unset
DEPOT_LOCAL_IMAGE_PULL_TIMEOUT_MS, DEPOT_TEST_IMAGE_PULL_TIMEOUT_MS	The time limit of each pull, in milliseconds	10 minutes
DEBUG=testcontainers:pull	Every Docker event of a pull, to debug one that stalls	unset

Usage

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

const namespace = Schemas.fromYamlFiles("test/schema/pet.yml");// Usually this is done in depot package and imported from there
const environment = new EnvironmentBuilder(namespace)
    .location(LocationBuilder.postgresDb(depotLocal))
    .build();
const deployedEnv = depot.deploy(environment);

APIs

Depot local supports two types of APIs, lambda and GQL.

lambda API

To get lambda api you need to call const api = deployedEnv.api(0)

when you have the api you can use it to make requests to your environment either by unstructured request

const create = await api.create({
    schema: "pet",
    table: "pet",
    data: {
        name: "dog",
        age: 1
    }
});

or by using depot lambda client

GQL API

To get GQL api you need to call const gqlApi = deployedEnv.gqlApi(0)

when you have the api you can use it to make requests to your environment by using Apollo client

const create = await gqlApi.mutate<PetStore, PetStore>({
    mutation: gql`
        mutation createPet($name: String!, $age: Int!) {
            createPetPet(id: "0987", data: { name: $name, age: $age }, expressions: {}) {
                id
                created
                updated
                schema
                version
                hash
                name
            }
        }
    `,
    variables: {
        name: "ren",
        age: 2
    },
    context: {
        headers: {Authorization: "Bearer token1"}
    }
});

FIXME: complete this with samples showcasing the "borrow pattern" + update the admonitions in the leaf pages