Introduction

Delta is a developer-first, cloud-augmented intelligent test runner built for high-velocity software engineering teams. By mapping dynamic test coverage at runtime (identifying exactly which lines of source code are executed by each test), Delta computes the exact intersection between code changes and the test suite.

When code changes, Delta queries the mapping database and returns only the affected tests, cutting test run times by up to 90%. This documentation guides you through installing the CLI, using it with pytest, and automating it via Git hooks.

How it works: Delta analyzes your git history and matches modified source code lines with execution paths recorded in your mapping database. It does not alter your test files; it simply selects and runs the correct tests.

Installation

The command-line interface deltatest-cli is published on PyPI. It can be easily installed using pip or other python package managers in your virtual environment.

Prerequisites

Python 3.8 or higher
Git repository initialized
Existing pytest test suite

Install CLI Package

Install the package inside your project's active virtual environment:

pip

(.venv) $ pip install deltatest-cli

If you use Poetry or Pipenv, install it as a development dependency:

Poetry & Pipenv

# Poetry
$ poetry add deltatest-cli --group dev

# Pipenv
$ pipenv install deltatest-cli --dev

This automatically installs the CLI utility delta along with its core dependencies: pytest, pytest-cov, and coverage.

Verify Installation

Check if the CLI utility is correctly installed by verifying the version:

bash

$ delta --version
deltatest-cli version 0.4.6

Choose Your Setup Mode

Delta supports two modes of tracking code-to-test mapping. Choose the setup that best fits your workflow:

Delta Cloud (Recommended)

Saves mappings in the cloud. Synchronizes coverage data across all developers in the team, supports CI/CD pipelines, and eliminates local database rebuild time.

Local Mode

Stores code-to-test mappings in a local SQLite database file at .delta/test_mapping.db. Ideal for single-developer workflows or offline usage.

Delta Cloud Integration

Cloud integration enables sharing test mappings. If a team member writes a test or runs a test suite, your local workspace will immediately know which tests to run without you needing to run the full suite locally to generate a database.

1. Register Account

If you don't have a Delta account, register a new account from the CLI:

bash

$ delta register
Email: admin@company.com
Password: ********
✓ User registered successfully!

2. Authenticate

Login to save your secure access token to your local environment configuration (saved in ~/.delta/config.toml):

bash

$ delta login
Email: admin@company.com
Password: ********
✓ Authentication successful. API key saved.

3. Track Repository

Associate your local repository with Delta Cloud:

bash

$ delta track --name my-application-repo
✓ Repository tracked successfully!
Repo ID: aa251edf-8d2b-4e1b-9fca-72bf7e8ea7bc

4. Seed Initial Cloud Mappings

Run your tests locally with coverage-context recording enabled to populate the database, then push it to Delta Cloud:

bash

# Run tests with test contexts enabled
$ pytest --cov=. --cov-context=test --cov-report=

# Push mappings to Delta Cloud
$ delta push
✓ Coverage file found: .coverage
✓ Syncing mappings to Delta Cloud...
✓ Mapping pushed successfully!

Local SQLite Mode

If you prefer offline or isolated database tracking, you can use Local Mode.

Build Local Mapping Database

Delta provides a command to build the mapping database iteratively by executing your tests, extracting coverage contexts, and storing them in an SQLite database file:

bash

$ delta build-mapping
Scanning for tests in: tests/
Building local mapping database...
[1/48] Running tests/test_auth.py::test_login... ✓
[2/48] Running tests/test_auth.py::test_logout... ✓
...
Database created at .delta/test_mapping.db with 48 test maps!

This command iteratively runs tests, creates .delta/test_mapping.db, and updates it. You should add the .delta/ folder to your .gitignore so database files aren't checked into your source control.

Resumable Builder: If the build process gets interrupted, simply run delta build-mapping again. It is resumable and will pick up right where it left off.

Pytest Integration

The deltatest-cli includes a pytest plugin that hooks directly into the pytest test collection lifecycle to filter out unaffected tests.

Running Affected Tests

To run only the tests affected by your unstaged and staged git changes compared to your base branch, add the --delta flag:

pytest

(.venv) $ pytest --delta

Example Terminal Output

Here is what you will see when executing pytest with Delta. Notice how the unaffected tests are automatically deselected, running in milliseconds rather than minutes:

terminal

$ pytest --delta
============================= test session starts ==============================
platform darwin -- Python 3.10.8, pytest-7.2.1, pluggy-1.0.0
plugins: cov-4.0.0, delta-0.4.6
Local mode: /Users/name/workspace/app/.delta/test_mapping.db
Analyzing git changes against base branch: master
Found 3 affected tests out of 145 total tests.

collected 145 items / 142 deselected / 3 selected

tests/test_auth.py ...                                                   [100%]

====================== 3 passed, 142 deselected in 1.42s =======================

Specifying a Base Branch

By default, Delta compares changes against the master branch. If your main development branch is named main or develop, pass it via the --delta-base option:

pytest

# Compare against main branch
$ pytest --delta --delta-base main

# Compare against develop branch
$ pytest --delta --delta-base develop

This allows Delta to calculate the diff between your current branch and the base branch, running only the tests that traverse those changed code lines.

Dry-Run Preview

If you want to quickly see which tests would be run without actually executing them, use the delta run CLI command with the --dry-run flag:

bash

$ delta run --dry-run
Analyzing git changes against base branch: master
Selected Tests (Dry-Run):
 - tests/test_auth.py::test_login
 - tests/test_auth.py::test_logout
 - tests/test_settings.py::test_update_profile

Configure Defaults

To avoid typing --delta every time, you can configure it as a default option in your project's pytest.ini or pyproject.toml file:

pytest.ini

[pytest]
addopts = --delta --delta-base main

pyproject.toml

[tool.pytest.ini_options]
addopts = "--delta --delta-base main"

Git Pre-commit Hook Integration

Automate your developer workflow by setting up a git pre-commit hook that automatically runs only the affected tests before allowing a commit to succeed.

Install Git Hook

To register the Delta git pre-commit hook in your local git repository, run the following command:

bash

$ delta install-pre-commit

Alternative Syntax: You can also run delta install pre-commit or delta install hook. They perform the exact same hook registration under the hood!

This command performs the following actions:

Generates/updates a standard .git/hooks/pre-commit script that intercepts commits.
Generates/updates a .git/hooks/post-commit script that updates the mapping database.
Ensures your .gitignore is updated to ignore Delta's cache and local database folders.

Developer Workflow Example

Once installed, the hook runs automatically on every commit. Let's see an example workflow:

You modify src/auth.py to fix a bug, and stage it:
```
$ git add src/auth.py
```

You attempt to commit your change:

$ git commit -m "Fix login token validation"

The pre-commit hook triggers and executes only the affected tests:

Repository: /Users/name/workspace/app
Target branch: master
Log file: /Users/name/workspace/app/.delta/pre-commit.log
Mapping Service: Delta Cloud (repo aa251edf...)

Running affected tests...
tests/test_auth.py ..                                            [100%]
All 2 affected tests passed!

[main c1a2b3d] Fix login token validation
 1 file changed, 4 insertions(+), 1 deletion(-)

No Auto-Push: Delta does not automatically run git push after a successful commit anymore. Run git push manually as you normally would when you're ready to share your changes with the remote server!

Bypassing Hooks

If you have an urgent change or are committing documentation and need to skip running tests, bypass the hook with the standard git flag:

bash

$ git commit -m "urgent readme tweak" --no-verify

Command Reference

Delta provides a full set of subcommands under the main delta command prefix.

Command	Description	Key Options & Examples
`delta run`	Run affected tests based on git diff.	`--dry-run` - Show tests without executing. `--base-branch <name>` - Base branch (default: master).
`delta update-mapping`	Update local mapping SQLite database using coverage output.	`--coverage-file <path>` - Path to .coverage database.
`delta build-mapping`	Resumable, iterative mapping database builder.	`--test-dir <path>` - Target tests directory.
`delta push`	Upload local test mappings to Delta Cloud.	`-v` - Verbose log outputs.
`delta register`	Creates a new Delta cloud account.	—
`delta login`	Authenticate CLI and save keys locally.	—
`delta track`	Track this repository on Delta Cloud.	`--name <repo-name>` - Project repository name.
`delta install`	Install Delta git hook(s).	Accepts target: `pre-commit`, `pre_commit`, or `hook`.
`delta install-pre-commit`	Install Git pre-commit verification hook (alias).	`--base-branch <name>` - Branch to compare commits against.

Troubleshooting & FAQs

Q: Why is "No tests selected" showing up when I edited code?

This typically occurs if the modified code lines have never been executed during a test run with coverage active, so they aren't in the mapping database. To resolve this, run your tests once with coverage context recording to seed the database:

bash

$ pytest --cov=. --cov-context=test --cov-report=
$ delta update-mapping

Q: How do I handle target branch does not exist error?

If you see a git error about a branch not existing, it means Delta's base branch target (default master) is missing from your local repository. Specify the correct branch using:

$ pytest --delta --delta-base main

Or install the git hook specifying the base branch:

$ delta install-pre-commit --base-branch main

Q: How do I disable the git hooks completely?

You can remove the hooks generated by Delta directly from your repository's hooks folder:

bash

$ rm -f .git/hooks/pre-commit .git/hooks/post-commit

Q: Does Delta support pytest-xdist?

Yes. Delta collects tests using standard pytest collection APIs. When using pytest-xdist, Delta generates the test selection list and feeds it directly into the runners, keeping selection times fast and accurate.