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:
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:
Install cargo-nextest
cargo install cargo-nextest
Build tests
cargo nextest run --no-run --profile ci
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:
CI testing workflow
The project uses GitHub Actions for continuous integration testing.
Rust CI pipeline
The build and test workflow for Rust:
Check dependencies
Verify Cargo.lock is up-to-date: 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
Build Rust tests
cargo nextest run --no-run --profile ci
Run Rust tests
cargo nextest run --profile ci
TypeScript CI pipeline
The test and lint workflow for TypeScript packages:
Format check
Check formatting with dprint: 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
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:
Write the test
Create or modify test functions in your package.
Run the test
For Rust:cargo test -p <package> "test_name"
cd npm-packages/<package>/
npm run test -- <file>
Iterate and fix
Make changes based on test results and re-run until tests pass.
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:
# 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.