Skip to main content

​
Testing Guide

This guide covers how to run tests in the Bark project. All tests are managed using just, which comes preinstalled with the Nix flake.

​
Prerequisites

Before running tests, make sure you have:
  1. Set up your development environment (see Contributing Guide)
  2. Installed just (comes with Nix, or install manually)
  3. PostgreSQL binaries available (initdb, pg_ctl)
  4. For integration tests: bitcoind and lightningd with hold plugin

​
Test Commands

​
Pre-commit Checks

Run all pre-commit checks (style checks + cargo check): 
just checks
This runs:
  • Style prechecks (indentation, whitespace, etc.)
  • cargo check on all packages and tests

​
Individual Prechecks

Run specific style checks: 
just prechecks
This includes:
  • rust_no_spaces_for_indent - Enforce tabs for indentation
  • rust_no_whitespace_on_empty_lines - No trailing whitespace
  • unused_server_logs - Detect unused log statements
  • conflicting_migration_scripts - Check for migration conflicts

​
Unit Tests

Run all unit tests (excludes integration tests): 
just test-unit
# or shorter alias
just unit
Run a specific unit test: 
just unit <test-name>
Example: 
just unit test_vtxo_validation

​
Integration Tests

Never run integration tests with cargo test directly. They require environment variables set by just.
Run all integration tests (uses bitcoind backend by default): 
just test-integration
# or shorter alias
just int
Run a specific integration test: 
just int <test-name>
Example: 
just int test_refresh

​
Client-Only Integration Tests

Run integration tests for bark, movement, exit and lightning test files only: 
just test-integration-client
# or shorter alias
just int-client

​
Esplora Backend Tests

Run integration tests using Esplora as the chain source: 
just test-integration-esplora
# or shorter alias
just int-esplora
Run a specific test with Esplora: 
just int-esplora <test-name>

​
Mempool Backend Tests

Run integration tests using Mempool.space as the chain source: 
just test-integration-mempool
# or shorter alias
just int-mempool
Run a specific test with Mempool: 
just int-mempool <test-name>

​
All Tests

Run the complete test suite (unit + integration with all backends): 
just test
This runs:
  • Unit tests
  • Integration tests (bitcoind)
  • Integration tests (Esplora)
  • Integration tests (Mempool)

​
Code Coverage

​
Build with Coverage

Build the project with code coverage instrumentation: 
just build-codecov

​
Unit Tests with Coverage

just test-unit-codecov

​
Integration Tests with Coverage

just test-integration-codecov
# or shorter alias
just int-cov
With Esplora: 
just test-integration-esplora-codecov
With Mempool: 
just test-integration-mempool-codecov

​
All Tests with Coverage

just test-all-codecov

​
Generate Coverage Report

After running tests with coverage, generate an HTML report: 
just codecov-report
The report will be available at ./target/debug/codecov/index.html.

​
Build Commands

​
Development Build

Build all workspace crates: 
just build

​
Check Without Building

Run cargo check on all packages: 
just check

​
Commit Checks

Verify that all commits individually compile: 
just check-commits

​
Platform-Specific Notes

​
macOS

On macOS, Core Lightning runs inside Docker. Make sure:
  1. Docker is installed and running
  2. “Host networking” feature is enabled in Docker Desktop
  3. Set the Docker image environment variable if not using Nix:
export LIGHTNINGD_DOCKER_IMAGE="second/cln-hold:v25.02.2"

​
Linux

Linux uses native lightningd binaries. Ensure the hold plugin is in your PATH or set: 
export LIGHTNINGD_EXEC="${PATH_TO_LIGHTNINGD}/bin/lightningd"
export HOLD_INVOICE_PLUGIN="/hold/target/debug/hold"

​
Common Test Patterns

​
Running Tests in Watch Mode

While just doesn’t have built-in watch mode, you can use cargo-watch: 
cargo install cargo-watch
cargo watch -x "nextest run --workspace --exclude ark-testing"

​
Running Tests for a Specific Package

cargoNextest run --package bark-wallet

​
Running Tests Matching a Pattern

just unit lightning
This runs all unit tests with “lightning” in the name.

​
Verbose Test Output

For more detailed test output: 
cargo nextest run --no-fail-fast --workspace --exclude ark-testing --nocapture

​
Troubleshooting

​
PostgreSQL Connection Issues

If tests fail with PostgreSQL connection errors:
  1. Using test managed host: Ensure initdb and pg_ctl are in your PATH or set POSTGRES_BINS
  2. Using external host: Verify TEST_POSTGRES_HOST points to a running PostgreSQL instance with correct credentials

​
Lightning Tests Failing

  1. Verify lightningd is in your PATH or LIGHTNINGD_EXEC is set
  2. Check that the hold plugin is available
  3. On macOS, ensure Docker is running

​
Bitcoin Tests Failing

  1. Ensure bitcoind is in your PATH or BITCOIND_EXEC is set
  2. Verify you have enough disk space for test chains

​
Test Timeouts

Integration tests can take time to set up bitcoind and lightningd. If tests timeout:
  1. Run tests individually to isolate the issue
  2. Check system resources (CPU, memory)
  3. Look for test-specific logs in the output

​
Best Practices

  1. Run just checks before committing - Catches style and compilation issues early
  2. Test your changes across all backends - Use just test to ensure compatibility
  3. Write focused tests - Unit tests should be fast and isolated
  4. Integration tests should test real workflows - Set up realistic scenarios
  5. Keep test data minimal - Only include what’s necessary for the test

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us