Running Tests

This page covers how to run Lombok’s test suites while contributing. It assumes you already have a working dev environment — if not, start with Local Development with dx.

Everything below is driven through the ./dx CLI from the repo root. Run ./dx help at any time to see the authoritative list of commands.

Prerequisites

Docker is required for all test types. Unit tests run inside the dev container; end-to-end tests spin up their own dedicated test container.
For unit tests, the dev container must already be running (./dx up, see the local development guide). ./dx unit execs into it.
For end-to-end tests, you do not need the dev environment running. The e2e commands build and run a separate, self-contained container.

Test types at a glance

Type	Command	Runs in	Needs `./dx up`?
Unit	`./dx unit <package>`	The running dev container	Yes
API e2e	`./dx e2e api`	A dedicated test container	No
UI e2e	`./dx e2e ui`	A dedicated test container	No

Unit tests

Run a package’s unit tests with:

./dx unit <package>

<package> is a directory name under packages/ such as api, ui, utils, types, or core-worker. The command requires a running dev container and a test:unit script in that package; it will tell you if either is missing.

Examples:

./dx unit api
./dx unit utils

For the API package specifically, unit specs are discovered by the glob ./**/*.unit-spec.ts (see packages/api/test/unit.run.ts). A watch mode is available directly via the package script:

./dx exec bun --cwd packages/api test:unit:watch

Other packages’ test:unit scripts use Bun’s default test runner (bun test), so they pick up Bun’s default spec patterns within that package.

[!NOTE] Not every package currently has unit specs, even when a test:unit script exists. An empty run simply reports no tests.

End-to-end tests

E2E tests run in a dedicated container defined by docker-compose.test.yml (service lomboke2e) and built from docker/app.Dockerfile (target: test). That container is self-contained — its entrypoint (packages/api/cmd/test-entrypoint.sh) starts its own PostgreSQL, MinIO, and NGINX — so it does not touch your normal dev database or storage.

API e2e

./dx e2e api

This runs all API e2e specs (*.e2e-spec.ts, located under packages/api/src/). You can narrow the run by passing a glob as the third argument:

./dx e2e api "./**/auth.e2e-spec.ts"

UI e2e

./dx e2e ui

UI e2e specs are *.ui-e2e-spec.ts files under packages/api/test/ui/. The UI is built first, and each spec file is run in its own preview server so files are isolated from one another. As with the API command, you can pass a glob to run a subset:

./dx e2e ui "./**/navigation.ui-e2e-spec.ts"

Core-worker e2e

./dx e2e core-worker is wired up to run the core-worker e2e suite inside the same test container.

[!NOTE] At the time of writing there are no *.e2e-spec.ts files in packages/core-worker/src, and this subcommand is not listed in ./dx help. Treat it as available-but-unverified until core-worker e2e specs exist, and confirm against ./dx help and the package before relying on it.

Managing the e2e environment

The e2e container can be torn down explicitly:

./dx e2e down
./dx e2e kill
./dx e2e purge

Use ./dx e2e purge if a previous run left state behind or you want a clean rebuild.

Test file conventions

Suite	Pattern	Location
API unit	`*.unit-spec.ts`	within `packages/api/`
API e2e	`*.e2e-spec.ts`	`packages/api/src/`
UI e2e	`*.ui-e2e-spec.ts`	`packages/api/test/ui/`

Naming a file to match the relevant pattern is enough for it to be picked up by the corresponding command.

How this maps to CI

CI mirrors these suites:

Unit tests run on every push except main, executing package-level test:unit scripts directly with Bun.
API e2e and UI e2e build the test image and run it in containers. The UI workflow discovers spec files and runs each one as a separate matrix job.

Because CI runs the same scripts the ./dx commands wrap, reproducing a CI failure locally is usually a matter of running the matching ./dx command.