Delta

Run only the tests affected by your code changes - automatically!

Delta integrates with your git workflow as a pre-commit hook, running only tests that cover the code you've changed. This dramatically speeds up your development cycle while ensuring quality.

Quick Links

• Key Features
• How It Works
• Installation
• Usage
• Commands
• VS Code Extension
• Contributing

Key Features

• Fast: Run only affected tests, not the entire suite
• Safe: Blocks commits if affected tests fail
• Intelligent: Uses SQLite-based test-to-code mapping for instant lookups
• Incremental Coverage: Combines coverage from test runs
• New Test Detection: Always runs newly added tests
• Auto-Discovery: Detects unmapped tests and builds mapping automatically
• Pre-commit Hook: Automatic integration with git workflow
• Status Check: Instantly inspect database mapping stats (both local and cloud via deltatest.dev)
• Delta Cloud Sync: Share test mappings across CI/CD and teams automatically (Powered by deltatest.dev)

Quick Start (Pre-Commit Hook)

cd ~/workspace/myproject

# Install the pre-commit hook
delta install

# That's it! Now every commit will:
# 1. Find tests affected by your changes
# 2. Run only those tests
# 3. Block commit if tests fail
# 4. Combine coverage with existing data

📋 How It Works

Pre-Commit Flow

Developer commits changes
         ↓
Pre-commit hook triggered
         ↓
Compare staged changes vs development branch
         ↓
Query SQLite mapping: "Which tests cover these lines?"
         ↓
Detect unmapped tests (dry-run pytest --collect-only)
         ↓
Run unmapped tests all-at-once (build mapping)
         ↓
Run mapped affected tests with coverage
         ↓
Tests pass? → Combine coverage → Allow commit
Tests fail? → Block commit

Auto-Discovery of Unmapped Tests

The pre-commit hook automatically detects tests that exist in your codebase but aren't in the mapping database yet:

1. Collect all tests: Runs pytest --collect-only to find all available tests
2. Compare with mapping: Queries .delta/test_mapping.db to see which tests are already mapped
3. Find delta: Identifies tests that exist but have never been run with coverage
4. Run all-at-once: Executes all unmapped tests together with --cov-context=test (fastest)
5. Update mapping: After completion, updates the mapping database with new coverage

Why this matters:

• New tests you write are automatically added to the mapping
• Tests added by teammates get mapped when you first commit
• No need to manually regenerate the entire mapping
• Mapping database grows organically over time
• All tests run in a single pytest invocation (fastest possible)

Example:

$ git commit -m "Fix bug in auth.py"

Found 1 changed Python file
Mapping DB: 1234 tests, 567 files, 45678 mappings
Collected 1250 total tests from pytest
Found 16 unmapped test(s)

================================================================================
Building coverage mapping for 16 unmapped test(s)
================================================================================

  Running unmapped test: unit_tests/test_new_feature.py::test_case_1
    ✓ Mapping updated for: unit_tests/test_new_feature.py::test_case_1
  Running unmapped test: unit_tests/test_new_feature.py::test_case_2
    ✓ Mapping updated for: unit_tests/test_new_feature.py::test_case_2
  ...
✓ Successfully mapped 16 test(s)

================================================================================
Running 3 affected test(s)...
================================================================================
...

Mapping Database

The mapping is stored in .delta/test_mapping.db (SQLite) at your repo root:

CREATE TABLE test_coverage_ranges (
    test_name TEXT NOT NULL,
    file_path TEXT NOT NULL,
    ranges TEXT NOT NULL,
    PRIMARY KEY (test_name, file_path)
);

Fast lookups: "Which tests cover file X, line Y?"

Installation

Prerequisites

• Python 3.8+
• pytest >= 7.0
• pytest-cov >= 4.0
• Git repository

Step 1: Install Package

Install via pip:

pip install deltatest-cli

Step 2: Build Mapping Database

cd ~/workspace/myproject

# Build mapping database (resumable)
delta build-mapping --verbose

Step 3: Install Pre-Commit Hook

cd ~/workspace/myproject
delta install

Done! Now every commit will run only affected tests.

Usage

Pre-Commit Hook (Automatic)

Just commit normally:

git add src/my_module.py
git commit -m "Fix bug in authentication"

# Hook runs automatically:
# - Finds tests covering src/my_module.py
# - Runs only those tests
# - Blocks commit if tests fail
# - Combines coverage on success

Manual Test Running

# Show what tests would run
delta run --dry-run --verbose

# Run affected tests manually
delta run

# Compare against different branch
delta run --base-branch develop

# Pass pytest arguments
delta run -- -x --pdb

Check Mapping Status

You can inspect the status and statistics of the local mapping database and the remote mapping service (deltatest.dev):

delta status

Commands

delta run

Run affected tests based on changes.

delta run [OPTIONS] [-- PYTEST_ARGS]

Options:
  --repo-root PATH        Repository root (default: current directory)
  --local, --no-remote    Run locally without connecting to the deltatest.dev remote mapping service
  --base-branch BRANCH    Branch to compare against (default: master)
  --coverage-file PATH    Path to .coverage file
  --dry-run              Show tests without running
  --min-tests N          Minimum tests required
  --explain              Show exactly which tests are affected by which files/lines
  -v, --verbose          Detailed output

delta build-mapping

Build test mapping database iteratively.

delta build-mapping [OPTIONS]

Options:
  --repo-root PATH        Repository root (default: current directory)
  --local, --no-remote    Build mapping database locally without remote deltatest.dev connection
  --mapping-db PATH       Path to mapping database
  --test-dir PATH         Directory containing tests
  -v, --verbose          Detailed output

delta status

Show local and remote (deltatest.dev) database status and statistics.

delta status [OPTIONS]

Options:
  --repo-root PATH        Repository root (default: current directory)
  --mapping-db PATH       Path to mapping database
  -v, --verbose          Detailed output

Bypassing the Hook

For urgent commits:

git commit --no-verify -m "Urgent hotfix"

VS Code Extension

An official VS Code extension is available to visualize coverage highlights directly in your editor.

Get the Delta Coverage VS Code Extension on the VS Code Marketplace.

Contributing

Delta is an open-source developer productivity tool.