Running tests

How to run tests for Rust and TypeScript packages

Rust tests

The Convex Backend uses cargo-nextest for running Rust tests in CI, but you can also use standard cargo test commands.

Running all tests

Test a specific package:

cargo test -p <package>

Running specific tests

Test a specific test or test group:

cargo test -p <package> "test_name"

Using cargo-nextest

For faster test execution, install and use cargo-nextest:

1. Install cargo-nextest

   cargo install cargo-nextest
   
2. Build tests

   cargo nextest run --no-run --profile ci
   
3. Run tests

   cargo nextest run --profile ci
   

Test environment variables

Some tests may require environment variables. For example, database tests use:

CI_PGUSER=postgres CI_PGPASSWORD=postgres cargo test

TypeScript tests

Running tests for a specific package

Navigate to the package directory and run tests:

cd npm-packages/<package>/
npm run test

Running a specific test file

Pass the file path to the test command:

cd npm-packages/<package>/
npm run test -- <file>

Running ESM tests

Some packages have separate ESM tests:

npm run test-esm

CI testing workflow

The project uses GitHub Actions for continuous integration testing.

Rust CI pipeline

The build and test workflow for Rust:

1. Check dependencies

   Verify Cargo.lock is up-to-date:

   cargo update -w --locked
   
2. Build JavaScript dependencies

   Build JS packages required by the Rust isolate:

   just rush install
   just rush build -t component-tests -t convex -t system-udfs -t udf-runtime -t udf-tests
   
3. Build Rust tests

   cargo nextest run --no-run --profile ci
   
4. Run Rust tests

   cargo nextest run --profile ci
   

TypeScript CI pipeline

The test and lint workflow for TypeScript packages:

1. Format check

   Check formatting with dprint:

   npx dprint check
   
2. Install dependencies

   npm i
   
3. Run tests

   npm run test
   
4. Run ESM tests

   npm run test-esm
   
5. Run linter

   npm run lint
   

Database tests

Some tests require database services. In CI, these run with Docker containers:

PostgreSQL

docker run -d \
  --name postgres \
  -e POSTGRESQL_PASSWORD=postgres \
  -e POSTGRESQL_MAX_CONNECTIONS=500 \
  -p 5432:5432 \
  public.ecr.aws/bitnami/postgresql:16

Then run tests with:

CI_PGUSER=postgres CI_PGPASSWORD=postgres cargo test

MySQL

docker run -d \
  --name mysql \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=1 \
  -e MYSQL_ROOT_PASSWORD="" \
  -p 3306:3306 \
  public.ecr.aws/docker/library/mysql:8.4.1-oracle

Test development workflow

When developing tests, follow this iterative workflow:

1. Write the test

   Create or modify test functions in your package.

2. Run the test

   For Rust:

   cargo test -p <package> "test_name"
   

   For TypeScript:

   cd npm-packages/<package>/
   npm run test -- <file>
   
3. Iterate and fix

   Make changes based on test results and re-run until tests pass.

4. Run full test suite

   Before submitting, run the full test suite for your package to ensure no regressions.

Environment setup

Ensure you have the correct environment before running tests:

Node version

# Check Node.js version matches .nvmrc
node --version
# Should output: v20.19.5

The Rust nightly version specified in rust-toolchain will be automatically used when you run cargo commands if you installed Rust via rustup.