# Changelog
Source: https://docs.diffblue.com/changelog
New features, improvements, and fixes in Diffblue Agents
## Google Gemini CLI and OpenCode support
### Breaking changes
* **`DIFFBLUE_AGENTS_CLAUDE_CLI_MAX_TURNS` renamed to `DIFFBLUE_AGENTS_CLI_MAX_TURNS`.** Update any environment variable configuration that referenced the old name.
### New features
* **Google Gemini CLI support.** Use Google Gemini CLI as the AI coding agent for test generation. Select it during `diffblue-agents install` or set `DIFFBLUE_AGENTS_PLATFORM=gemini`.
* **OpenCode support.** Use [OpenCode](https://opencode.ai/docs/) as the AI coding agent for test generation. Select it during `diffblue-agents install` or set `DIFFBLUE_AGENTS_PLATFORM=opencode`. See the [system requirements](/system-requirements#supported-ai-coding-agent-platforms) for provider credential setup.
## Python mutation testing on Windows (experimental), with reliability fixes
### New features
* **Python mutation testing on Windows (experimental).** The `test-quality-report` workflow now runs mutation testing on Windows for Python projects. On Linux and macOS, Python 3.7–3.12 projects now use mutmut 2.x, which is more stable than mutmut 3.x.
### Improvements
* **Per-user telemetry attribution for offline licenses.** When you use an offline license, workflow telemetry now attributes usage to your git `user.email` instead of the license holder's email. If you have not configured `user.email`, the license email is used as a fallback.
### Fixes
* **Workflow failure when git identity is not configured.** If `user.name` or `user.email` is not set in git, workflows no longer fail with an unclear error. The workflow now proceeds and displays a warning with the commands to configure your git identity.
* **Unclear error when `python3-venv` is missing.** On Linux, if `python3-venv` is not installed, the workflow now fails immediately with an actionable message — for example, `python3.12-venv is not installed. Run: sudo apt install python3.12-venv`. Previously the workflow failed late at "Measure coverage" with no useful guidance.
* **Python mutation score incorrectly reported as 0.** If a previous run left a stale `.mutmut-cache` file in your project, mutation testing completed immediately with a score of 0. The workflow now removes any stale cache before running.
* **Missing error details when all modules fail planning.** When all modules are excluded during planning, the CLI now shows the reason each module was excluded. Previously only a count was shown.
* **Ant projects were rejected during planning.** Projects using Ant with JaCoCo coverage configured are no longer excluded during planning. Previously these projects produced 0 modules analyzed with no explanation.
## Test Quality Agent, failing test removal, and workflow improvements
### New features
* **Diffblue Test Quality Agent.** You can now run the `test-quality-report` workflow for Java projects. This workflow measures test coverage, mutation score, and test strength across your project, and generates an HTML report breaking down the metrics per module and per class.
### Improvements
* **Failing tests are automatically removed.** The test generation workflow now validates generated tests by running them. If any tests generated by Diffblue Agents fail validation, the CLI automatically removes those tests before making the final commit, and refunds your license credits for those lines.
* **Filter validation.** The CLI validates `--filter` arguments before starting a workflow and displays an error message if the filter is invalid.
* **Simple class names in `--filter`.** You can now use simple class names with `--filter`; the CLI automatically converts them to their fully qualified form.
* **Multiple comma-separated values for `--filter`.** You can pass multiple class or package filters using `--filter` (for example, `diffblue-agents run regression-unit-tests --filter com.example.owner,com.example.vet`). If you use PowerShell, quote the value to prevent shell splitting.
* **View all workflows without a license.** The `workflows` command displays all workflows, regardless of your license state. Workflows you cannot access appear dimmed with a reason. The `license` command also shows which agents are enabled on your license.
* **Support for versioned Python interpreters.** You can now use versioned interpreters like `python3.12` and `python3.11` alongside `python3`.
* **Arrow key navigation in CLI text inputs.** You can now navigate NPS and license activation prompts using your arrow keys.
### Fixes
* **Python coverage measurement excludes doctest plugins.** The workflow now excludes doctest plugins from coverage measurement. This fixes inaccurate coverage baselines for projects using doctests.
* **Windows path handling in LLM commands.** Fixes an issue where commands containing backslashes in Windows file paths failed to execute.
* **Crash after switching AI coding agents.** Fixes a crash that occurred if you switched AI coding agents while a workflow was running.
* **Duplicate license activation on double-submit.** The CLI disables the license activation input after submission. This prevents duplicate activations.
## One-line install, user approval, environment setup workflow, and Python improvements
### New features
* **One-line install scripts.** Install Diffblue Agents with a single command on macOS, Linux, and Windows. The script downloads the latest release, extracts it, and adds it to your `PATH`. See [installation](/installation) for details.
* **Approval prompt before test generation.** After resource estimates are calculated, the CLI displays the expected cost and asks for confirmation before proceeding. Use `--auto-approve` to skip the prompt in CI or automated workflows.
* **`regression-unit-tests-prepare-project` workflow.** Environment validation and setup now runs as its own workflow, separate from test generation. Run `regression-unit-tests-prepare-project` to verify your project environment without starting test generation. See [prepare project](/workflows/regression-unit-tests-prepare-project) for details.
### Improvements
* **Automatic Python test dependency detection.** During environment setup, the agent scans existing test files for patterns (e.g. `@pytest.mark.asyncio`) and automatically installs missing test dependencies before test generation starts.
* **Actionable error messages.** Common failures (out of tokens, timeouts, license errors) now show specific remediation steps instead of generic error messages.
* **Environment setup changes visible in CLI.** Installed packages and configuration changes made during environment setup are now displayed in the CLI output.
* **Improved JDK detection.** Java version resolution now checks `PATH` and the original `JAVA_HOME` in addition to standard locations, reducing failures on machines with complex Java setups.
* **Faster coverage checks.** Redundant coverage verification is now skipped when building projects, reducing test generation time.
* **Generated Python files copied to source.** Dynamically generated files (e.g. `_version.py`) are now copied from the virtual environment back to the source tree, fixing issues with Python packages that generate version files during build.
### Fixes
* **Windows command line length limit for git operations.** Resolved "command too long" errors on Windows when committing or reverting large changesets.
* **Duplicate license activation prompt.** The license activation prompt no longer appears twice during the automatic installation flow.
* **CLI error after install completes.** Resolved a UI error that could appear after installation finishes.
* **Long workflow names no longer break CLI layout.** The "Executing" label now wraps correctly for workflows with long names.
* **Python venv symlinks on macOS.** Python virtual environment setup no longer fails on macOS due to broken symlinks after worktree copy.
* **Paths with spaces on Windows.** The server launcher now correctly handles installation paths that contain spaces on Windows.
* **Special characters in filenames.** Git file tracking now handles repositories with special characters in filenames.
## Parallel progress display fix
### Fixes
* **Parallel progress display.** Worker sub-tasks that lacked user-visible messages no longer clutter the CLI task list during parallel test generation.
## Module filtering, proxy support, and Python reliability
### New features
* **`--module` flag for filtering test generation.** Limit test generation to specific modules in multi-module projects with `--module apps/server,apps/cli`.
### Improvements
* **Corporate proxy support.** Configure a corporate proxy (`diffblue.agents.proxy.host`, `diffblue.agents.proxy.port`) for environments that route traffic through a proxy. Proxy support extends to both license validation and telemetry.
* **Automatic server restart on license change.** The server now detects when the license file has changed and automatically restarts with the new configuration.
* **Lines covered column in summary.** The test generation summary now includes a "Lines Covered" column showing coverage counts (e.g. "160/200").
### Fixes
* **JVM memory exhaustion with parallel agents.** Fixed out-of-memory errors when running multiple agents in parallel by automatically calculating appropriate JVM heap limits based on available system memory.
* **Python virtual environment reliability.** Fixed multiple issues with Python virtual environment path repair when copying between worktrees, including stale `.pth` files, `direct_url.json` paths, and Windows-specific path handling.
* **Non-source files excluded from callable discovery.** Files that are not valid source code (e.g. font files, text files in source directories) are now filtered out during callable discovery, preventing lexer crashes.
* **Undefined work unit count in planning summary.** Fixed a display issue when work unit counts were undefined in the planning summary view.
* **Raw mode errors in non-interactive environments.** The CLI no longer errors when run in non-interactive environments such as CI/CD pipelines.
## General availability
Diffblue Agents v1.0.0 is the first general availability release. It provides AI-powered regression unit test generation and planning workflows for Java and Python projects, with support for Maven, Gradle, and pytest.
# Overview
Source: https://docs.diffblue.com/index
What Diffblue Agents does and how it works
**Looking for Diffblue Cover?** Documentation has moved to [cover-docs.diffblue.com](https://cover-docs.diffblue.com).
## What Diffblue Agents does
Diffblue Agents orchestrates workflows through your existing AI coding agent platform. You bring your own [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms), and Agents handles scoping, verification, execution, and rollback — autonomously, across entire projects.
Each workflow handles a specific software engineering task from start to finish. Agents delegates code generation to your agent platform and manages everything else: breaking work into partitions, validating results, rolling back failures, and committing verified output.
The current release includes the **[Diffblue Testing Agent](/workflows/regression-unit-tests)** — autonomous regression unit test generation for Java and Python projects.
## How it works
Diffblue Agents runs locally on your machine. It consists of two components:
* **Diffblue Agents Server** — a local server that orchestrates workflows and manages licensing.
* **Diffblue Agents CLI** — a command-line interface that submits workflow requests and displays progress.
When you run a workflow, Diffblue Agents analyzes your project, breaks the work into partitions, and processes each partition independently.
All execution happens in temporary git worktrees.
Results are validated automatically — only verified output is committed to your current branch. Anything that fails validation is rolled back.
## Next steps
* Check the [system requirements](/system-requirements) for your environment.
* [Install Diffblue Agents](/installation) and run through the [quickstart](/quickstart).
# Install Diffblue Agents
Source: https://docs.diffblue.com/installation
Download and install Diffblue Agents
## Prerequisites
Verify that you meet the [system requirements](/system-requirements) before proceeding.
## Install
```bash theme={null}
curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh | sh
```
```bash theme={null}
curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh | sh
```
```bash theme={null}
curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh | sh
```
```powershell theme={null}
irm https://release.diffblue.com/diffblue-agents/install.ps1 | iex
```
The install script downloads the latest release for your platform, extracts it to `~/.diffblue/agents/` (`%USERPROFILE%\.diffblue\agents` on Windows), and adds it to your `PATH`.
To reinstall or update, run the same command again: the script will replace the existing installation.
If the Diffblue Agents server is running, stop it before reinstalling with `diffblue-agents --stop-server` from your project directory.
To verify, navigate to your project directory and run:
```bash theme={null}
diffblue-agents version
```
To pass options, download and run the script directly instead of piping it:
```bash theme={null}
curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh -o install.sh
sh install.sh --force --install-dir /opt/diffblue-agents
```
```bash theme={null}
curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh -o install.sh
sh install.sh --force --install-dir /opt/diffblue-agents
```
```bash theme={null}
curl -fsSL https://release.diffblue.com/diffblue-agents/install.sh -o install.sh
sh install.sh --force --install-dir /opt/diffblue-agents
```
```powershell theme={null}
& ([scriptblock]::Create((irm https://release.diffblue.com/diffblue-agents/install.ps1))) -Force -InstallDir C:\diffblue-agents
```
| Option | Shell | PowerShell | Description |
| ------------------------ | ---------------------- | -------------------- | ------------------------------------------------------------------ |
| Custom install directory | `--install-dir ` | `-InstallDir ` | Install to a custom directory instead of `~/.diffblue/agents/` |
| Skip PATH modification | `--no-modify-path` | `-NoModifyPath` | Do not add the `cli` directory to your `PATH` |
| Force | `--force` | `-Force` | Stop a running server before overwriting the existing installation |
You can also [install manually](#manual-install) by downloading and extracting the archive yourself.
## Configure your AI coding agent
Diffblue Agents uses Claude Code by default. To select a different [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) or provide a custom path, use the `install` command.
### Interactive configuration
Run the install command without arguments to select your agent interactively:
```bash theme={null}
diffblue-agents install
```
The install command scans your `PATH` for supported agents and presents an interactive selection menu. If your agent is not detected automatically, select "Enter path manually" to specify the agent type and executable path.
The install command saves your selection and then validates that the selected agent works correctly by running a test prompt, which may take up to 60 seconds. If validation fails, you may need to rerun the install command to correct the saved path.
### Non-interactive configuration
To configure an agent without using the interactive selection menu, specify the agent type and path directly:
```bash theme={null}
diffblue-agents install agent
```
Replace `` with `claude`, `copilot`, `gemini`, or `opencode`, and `` with the absolute path to the agent executable.
**Examples:**
```bash theme={null}
diffblue-agents install agent claude /usr/local/bin/claude
diffblue-agents install agent gemini /usr/local/bin/gemini
diffblue-agents install agent opencode /usr/local/bin/opencode
```
This mode is useful for automated setup or CI/CD pipelines.
### Configuration options
See the [CLI reference](/reference/cli#environment-variables) for all configuration options, including environment variables for agent platform selection and custom paths.
## Manual install
1. Download the archive for your platform:
```bash theme={null}
curl -JLO https://release.diffblue.com/diffblue-agents/latest-macos_aarch64
```
```bash theme={null}
curl -JLO https://release.diffblue.com/diffblue-agents/latest-macos_amd64
```
```bash theme={null}
curl -JLO https://release.diffblue.com/diffblue-agents/latest-linux
```
```powershell theme={null}
curl.exe -JLO https://release.diffblue.com/diffblue-agents/latest-windows
```
2. Extract the archive:
```bash theme={null}
unzip diffblue-agents-*.zip
```
```bash theme={null}
unzip diffblue-agents-*.zip
```
```bash theme={null}
unzip diffblue-agents-*.zip
```
```powershell theme={null}
Expand-Archive diffblue-agents-*.zip .
```
3. Add the `cli` directory to your `PATH` or create an alias. Replace `X.X.X` with the version you installed.
```bash theme={null}
# add the cli directory to your PATH:
echo 'export PATH="$HOME/diffblue-agents-X.X.X-macos_aarch64/cli:$PATH"' >> ~/.zshrc
source ~/.zshrc
# or, create an alias:
echo 'alias diffblue-agents="$HOME/diffblue-agents-X.X.X-macos_aarch64/cli/diffblue-agents"' >> ~/.zshrc
source ~/.zshrc
```
```bash theme={null}
# add the cli directory to your PATH:
echo 'export PATH="$HOME/diffblue-agents-X.X.X-macos_amd64/cli:$PATH"' >> ~/.zshrc
source ~/.zshrc
# or, create an alias:
echo 'alias diffblue-agents="$HOME/diffblue-agents-X.X.X-macos_amd64/cli/diffblue-agents"' >> ~/.zshrc
source ~/.zshrc
```
```bash theme={null}
# add the cli directory to your PATH:
echo 'export PATH="$HOME/diffblue-agents-X.X.X-linux_amd64/cli:$PATH"' >> ~/.bashrc
source ~/.bashrc
# or, create an alias:
echo 'alias diffblue-agents="$HOME/diffblue-agents-X.X.X-linux_amd64/cli/diffblue-agents"' >> ~/.bashrc
source ~/.bashrc
```
```powershell theme={null}
# add the cli directory to your PATH:
[Environment]::SetEnvironmentVariable("PATH", "$HOME\diffblue-agents-X.X.X-windows_amd64\cli;$([Environment]::GetEnvironmentVariable("PATH", "User"))", "User")
# or, create an alias:
Set-Alias diffblue-agents "$HOME\diffblue-agents-X.X.X-windows_amd64\cli\diffblue-agents.ps1"
```
4. Verify the installation:
```bash theme={null}
diffblue-agents version
```
## Troubleshooting
macOS may quarantine files downloaded from the internet. If you see a warning that the file is from an unidentified developer, remove the quarantine attribute from the extracted directory:
```bash theme={null}
# Apple Silicon
xattr -r -d com.apple.quarantine diffblue-agents-X.X.X-macos_aarch64/
# Intel
xattr -r -d com.apple.quarantine diffblue-agents-X.X.X-macos_amd64/
```
Windows may block downloaded scripts from executing. In PowerShell, navigate into the Diffblue Agents installation directory and run:
```powershell theme={null}
Unblock-File cli\diffblue-agents.ps1
Unblock-File server\diffblue-agents-server.ps1
Unblock-File jre\bin\java.exe
```
If the scripts still fail to execute after unblocking, set your PowerShell execution policy to RemoteSigned for the current user:
```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Then restart your terminal.
## Next steps
* [Quickstart](/quickstart) — activate your license and run your first workflow.
# Diffblue Agents Third Party Notices and/or Licenses
Source: https://docs.diffblue.com/legal/diffblue-legal/agents-third-party-notices
Licensed by Diffblue Limited. For the full license text of the Diffblue Limited License, please see the [End User License Agreement (EULA)](/legal/diffblue-legal/diffblue-end-user-license-agreement-eula).
This product includes third-party software components. The table below lists each component and its license.
| Component | License |
| --------------------------------------------------------------- | ---------------------------------------------------- |
| @alcalzone/ansi-tokenize | MIT License |
| @bufbuild/protobuf | Apache License, Version 2.0 |
| @grpc/grpc-js | Apache License, Version 2.0 |
| @grpc/proto-loader | Apache License, Version 2.0 |
| @inkjs/ui | MIT License |
| @js-sdsl/ordered-map | MIT License |
| @opentelemetry/api | Apache License, Version 2.0 |
| @opentelemetry/api-logs | Apache License, Version 2.0 |
| @opentelemetry/core | Apache License, Version 2.0 |
| @opentelemetry/otlp-transformer | Apache License, Version 2.0 |
| @opentelemetry/resources | Apache License, Version 2.0 |
| @opentelemetry/sdk-logs | Apache License, Version 2.0 |
| @opentelemetry/sdk-metrics | Apache License, Version 2.0 |
| @opentelemetry/sdk-trace-base | Apache License, Version 2.0 |
| @opentelemetry/semantic-conventions | Apache License, Version 2.0 |
| @protobufjs/aspromise | The 3-Clause BSD License |
| @protobufjs/base64 | The 3-Clause BSD License |
| @protobufjs/codegen | The 3-Clause BSD License |
| @protobufjs/eventemitter | The 3-Clause BSD License |
| @protobufjs/fetch | The 3-Clause BSD License |
| @protobufjs/float | The 3-Clause BSD License |
| @protobufjs/path | The 3-Clause BSD License |
| @protobufjs/pool | The 3-Clause BSD License |
| @protobufjs/utf8 | The 3-Clause BSD License |
| @types/gradient-string | MIT License |
| @types/human-number | MIT License |
| @types/node | MIT License |
| @types/react | MIT License |
| @types/react-dom | MIT License |
| @types/tinycolor2 | MIT License |
| ansi-escapes | MIT License |
| ansi-regex | MIT License |
| ansi-styles | MIT License |
| ANTLR 4 Runtime | The 3-Clause BSD License |
| Apache Commons Codec | Apache License, Version 2.0 |
| Apache Commons Exec | Apache License, Version 2.0 |
| Apache Commons IO | Apache License, Version 2.0 |
| Apache Commons Lang | Apache License, Version 2.0 |
| Apache Commons Text | Apache License, Version 2.0 |
| Apache HttpClient | Apache License, Version 2.0 |
| Apache HttpCore | Apache License, Version 2.0 |
| ArC - Runtime | Apache License, Version 2.0 |
| asm | The 3-Clause BSD License |
| asm-analysis | The 3-Clause BSD License |
| asm-commons | The 3-Clause BSD License |
| asm-tree | The 3-Clause BSD License |
| asm-util | The 3-Clause BSD License |
| auto-bind | MIT License |
| Brotli4j | Apache License, Version 2.0 |
| buffer-crc32 | MIT License |
| CDI APIs | Apache License, Version 2.0 |
| CDI Language Model | Apache License, Version 2.0 |
| chalk | MIT License |
| ClassGraph | MIT License |
| ClassMate | Apache License, Version 2.0 |
| cli-boxes | MIT License |
| cli-cursor | MIT License |
| cli-spinners | MIT License |
| cli-truncate | MIT License |
| cliui | ISC License |
| CloudEvents - API | Apache License, Version 2.0 |
| CloudEvents - Core | Apache License, Version 2.0 |
| CloudEvents - JSON Jackson | Apache License, Version 2.0 |
| code-excerpt | MIT License |
| color-convert | MIT License |
| color-name | MIT License |
| Commons Logging to JBoss Logging | Apache License, Version 2.0 |
| convert-to-spaces | MIT License |
| crac | The 2-Clause BSD License |
| cron-utils | Apache License, Version 2.0 |
| csstype | MIT License |
| deepmerge | MIT License |
| Eclipse Expressly | Eclipse Public License - v 2.0 |
| Eclipse Parsson | Eclipse Public License - v 2.0 |
| emoji-regex | MIT License |
| environment | MIT License |
| error-prone annotations | Apache License, Version 2.0 |
| es-toolkit | MIT License |
| escalade | MIT License |
| escape-string-regexp | MIT License |
| Feign Core | Apache License, Version 2.0 |
| Feign Gson | Apache License, Version 2.0 |
| Feign OkHttp | Apache License, Version 2.0 |
| Feign SLF4J | Apache License, Version 2.0 |
| figures | MIT License |
| FindBugs-jsr305 | Apache License, Version 2.0 |
| get-caller-file | ISC License |
| get-east-asian-width | MIT License |
| Gizmo | Apache License, Version 2.0 |
| gradient-string | MIT License |
| Gson | Apache License, Version 2.0 |
| Guava InternalFutureFailureAccess and InternalFutures | Apache License, Version 2.0 |
| Guava: Google Core Libraries for Java | Apache License, Version 2.0 |
| has-flag | MIT License |
| HdrHistogram | The 2-Clause BSD License |
| Hibernate Validator Engine | Apache License, Version 2.0 |
| human-number | MIT License |
| indent-string | MIT License |
| ink | MIT License |
| ink-gradient | MIT License |
| ink-link | MIT License |
| ink-select-input | MIT License |
| ink-spinner | MIT License |
| ink-text-input | MIT License |
| Internet Time Utility | Apache License, Version 2.0 |
| is-fullwidth-code-point | MIT License |
| is-in-ci | MIT License |
| is-unicode-supported | MIT License |
| J2ObjC Annotations | Apache License, Version 2.0 |
| Jackson dataformat: Smile | Apache License, Version 2.0 |
| Jackson datatype: jdk8 | Apache License, Version 2.0 |
| Jackson datatype: JSR310 | Apache License, Version 2.0 |
| Jackson-annotations | Apache License, Version 2.0 |
| Jackson-core | Apache License, Version 2.0 |
| jackson-databind | Apache License, Version 2.0 |
| Jackson-dataformat-YAML | Apache License, Version 2.0 |
| Jackson-module-parameter-names | Apache License, Version 2.0 |
| Jakarta Activation API | Eclipse Distribution License - v 1.0 |
| Jakarta Annotations API | Eclipse Public License - v 2.0 |
| Jakarta Dependency Injection | Apache License, Version 2.0 |
| Jakarta Expression Language API | Eclipse Public License - v 2.0 |
| Jakarta Interceptors | Eclipse Public License - v 2.0 |
| Jakarta JSON Processing API | Eclipse Public License - v 2.0 |
| Jakarta RESTful WS API | Eclipse Public License - v 2.0 |
| Jakarta Validation API | Apache License, Version 2.0 |
| Jakarta XML Binding API | Eclipse Distribution License - v 1.0 |
| jakarta.transaction API | Eclipse Public License - v 2.0 |
| Jandex: Core | Apache License, Version 2.0 |
| Java Concurrency Tools Core Library | Apache License, Version 2.0 |
| JavaEWAH | Apache License, Version 2.0 |
| Javassist | Apache License, Version 2.0 |
| JBoss Log Manager | Apache License, Version 2.0 |
| JBoss Logging 3 | Apache License, Version 2.0 |
| JBoss Threads | Apache License, Version 2.0 |
| JCodings | MIT License |
| Joda-Time | Apache License, Version 2.0 |
| Joni | MIT License |
| JOpt Simple | MIT License |
| JsonSchemaValidator | Apache License, Version 2.0 |
| LatencyUtils | Creative Commons Zero v1.0 Universal |
| libphonenumber | Apache License, Version 2.0 |
| Licensespring Core | LicenseSpring Compiled SDK License Agreement (LCSLA) |
| Licensespring License Client | LicenseSpring Compiled SDK License Agreement (LCSLA) |
| lodash.camelcase | MIT License |
| long | Apache License, Version 2.0 |
| meow | MIT License |
| MicroProfile Config API | Apache License, Version 2.0 |
| MicroProfile Context Propagation | Apache License, Version 2.0 |
| MicroProfile Rest Client API | Apache License, Version 2.0 |
| mimic-fn | MIT License |
| net.thisptr:jackson-jq | Apache License, Version 2.0 |
| net.thisptr:jackson-jq-extra | Apache License, Version 2.0 |
| Netty/Buffer | Apache License, Version 2.0 |
| Netty/Codec | Apache License, Version 2.0 |
| Netty/Codec/DNS | Apache License, Version 2.0 |
| Netty/Codec/HAProxy | Apache License, Version 2.0 |
| Netty/Codec/HTTP | Apache License, Version 2.0 |
| Netty/Codec/HTTP2 | Apache License, Version 2.0 |
| Netty/Codec/Socks | Apache License, Version 2.0 |
| Netty/Common | Apache License, Version 2.0 |
| Netty/Handler | Apache License, Version 2.0 |
| Netty/Handler/Proxy | Apache License, Version 2.0 |
| Netty/Resolver | Apache License, Version 2.0 |
| Netty/Resolver/DNS | Apache License, Version 2.0 |
| Netty/TomcatNative \[OpenSSL - Classes] | Apache License, Version 2.0 |
| Netty/Transport | Apache License, Version 2.0 |
| Netty/Transport/Native/Unix/Common | Apache License, Version 2.0 |
| onetime | MIT License |
| Open Feign Forms Core | Apache License, Version 2.0 |
| oshi-core | MIT License |
| parse-ms | MIT License |
| patch-console | MIT License |
| pend | MIT License |
| pretty-ms | MIT License |
| proto-google-common-protos | Apache License, Version 2.0 |
| protobufjs | The 3-Clause BSD License |
| Quarkus - ArC - Runtime | Apache License, Version 2.0 |
| Quarkus - Bootstrap - Classloader common utilities | Apache License, Version 2.0 |
| Quarkus - Bootstrap - Runner | Apache License, Version 2.0 |
| Quarkus - Configuration - YAML - Runtime | Apache License, Version 2.0 |
| Quarkus - Core - Runtime | Apache License, Version 2.0 |
| Quarkus - Credentials - Runtime | Apache License, Version 2.0 |
| Quarkus - Development mode - SPI | Apache License, Version 2.0 |
| Quarkus - FS Util | Apache License, Version 2.0 |
| Quarkus - gRPC - API | Apache License, Version 2.0 |
| Quarkus - gRPC - Reflection | Apache License, Version 2.0 |
| Quarkus - gRPC - Runtime | Apache License, Version 2.0 |
| Quarkus - gRPC - Stubs for health and reflection | Apache License, Version 2.0 |
| Quarkus - gRPC Common - Runtime | Apache License, Version 2.0 |
| Quarkus - Jackson - Runtime | Apache License, Version 2.0 |
| Quarkus - Jackson Jq - Runtime | Apache License, Version 2.0 |
| Quarkus - Jakarta REST Client - Runtime | Apache License, Version 2.0 |
| Quarkus - JSON-P - Runtime | Apache License, Version 2.0 |
| Quarkus - Mutiny - Runtime | Apache License, Version 2.0 |
| Quarkus - Netty - Runtime | Apache License, Version 2.0 |
| Quarkus - OpenTelemetry - Runtime | Apache License, Version 2.0 |
| Quarkus - Proxy Registry - Runtime | Apache License, Version 2.0 |
| Quarkus - REST - Common - Runtime | Apache License, Version 2.0 |
| Quarkus - REST - Jackson - Runtime | Apache License, Version 2.0 |
| Quarkus - REST - Jackson Common Bits - Runtime | Apache License, Version 2.0 |
| Quarkus - REST - Runtime | Apache License, Version 2.0 |
| Quarkus - REST Client - Runtime | Apache License, Version 2.0 |
| Quarkus - REST Client Jackson | Apache License, Version 2.0 |
| Quarkus - REST Clients Config - Runtime | Apache License, Version 2.0 |
| Quarkus - Security - Runtime SPI | Apache License, Version 2.0 |
| Quarkus - SmallRye Context Propagation - Runtime | Apache License, Version 2.0 |
| Quarkus - SmallRye Stork - Runtime | Apache License, Version 2.0 |
| Quarkus - TLS Registry - Runtime | Apache License, Version 2.0 |
| Quarkus - TLS Registry - Runtime SPI | Apache License, Version 2.0 |
| Quarkus - Value Registry | Apache License, Version 2.0 |
| Quarkus - Vert.x - HTTP - Runtime | Apache License, Version 2.0 |
| Quarkus - Vert.x - Runtime | Apache License, Version 2.0 |
| Quarkus - Vert.x Late Bound MDC Provider | Apache License, Version 2.0 |
| Quarkus - Vert.x Utils | Apache License, Version 2.0 |
| Quarkus - Virtual Threads - Runtime | Apache License, Version 2.0 |
| Quarkus - WebSockets Next - SPI | Apache License, Version 2.0 |
| Quarkus Flow :: Core :: Runtime | Apache License, Version 2.0 |
| Quarkus Security API | Apache License, Version 2.0 |
| react | MIT License |
| react-dom | MIT License |
| react-reconciler | MIT License |
| require-directory | MIT License |
| RESTEasy Reactive - Client - Runtime | Apache License, Version 2.0 |
| RESTEasy Reactive - Common Runtime | Apache License, Version 2.0 |
| RESTEasy Reactive - Common Types | Apache License, Version 2.0 |
| RESTEasy Reactive - Jackson Support - Runtime | Apache License, Version 2.0 |
| RESTEasy Reactive - Runtime | Apache License, Version 2.0 |
| RESTEasy Reactive - Vert.x Support - Runtime | Apache License, Version 2.0 |
| restore-cursor | MIT License |
| scheduler | MIT License |
| semver4j | MIT License |
| Serverless Workflow :: Annotations | Apache License, Version 2.0 |
| Serverless Workflow :: API | Apache License, Version 2.0 |
| Serverless Workflow :: Experimental :: Fluent :: Functional | Apache License, Version 2.0 |
| Serverless Workflow :: Experimental :: Lambda | Apache License, Version 2.0 |
| Serverless Workflow :: Experimental:: Types | Apache License, Version 2.0 |
| Serverless Workflow :: Fluent :: Spec | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: Core | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: HTTP | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: Jackson:: Lifecycle Events | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: Jackson:: Model | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: JQ | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: Json utils | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: OpenAPI | Apache License, Version 2.0 |
| Serverless Workflow :: Impl :: Template :: Jersey | Apache License, Version 2.0 |
| Serverless Workflow :: Serialization | Apache License, Version 2.0 |
| Serverless Workflow :: Types | Apache License, Version 2.0 |
| signal-exit | ISC License |
| SLF4J API Module | MIT License |
| SLF4J: JBoss Log Manager | Apache License, Version 2.0 |
| slice-ansi | MIT License |
| SmallRye Certificate Generator - Private Key PEM utilities | Apache License, Version 2.0 |
| SmallRye Common: Annotations | Apache License, Version 2.0 |
| SmallRye Common: Classloader | Apache License, Version 2.0 |
| SmallRye Common: Constraints | Apache License, Version 2.0 |
| SmallRye Common: CPU | Apache License, Version 2.0 |
| SmallRye Common: Expressions | Apache License, Version 2.0 |
| SmallRye Common: Functions | Apache License, Version 2.0 |
| SmallRye Common: IO | Apache License, Version 2.0 |
| SmallRye Common: Net | Apache License, Version 2.0 |
| SmallRye Common: OS | Apache License, Version 2.0 |
| SmallRye Common: References | Apache License, Version 2.0 |
| SmallRye Common: Vert.x Context Utilities | Apache License, Version 2.0 |
| SmallRye Config: CDI | Apache License, Version 2.0 |
| SmallRye Config: Common | Apache License, Version 2.0 |
| SmallRye Config: ConfigSource - YAML | Apache License, Version 2.0 |
| SmallRye Config: Core | Apache License, Version 2.0 |
| SmallRye Config: Crypto | Apache License, Version 2.0 |
| SmallRye Context Propagation: API | Apache License, Version 2.0 |
| SmallRye Context Propagation: Core | Apache License, Version 2.0 |
| SmallRye Context Propagation: Storage | Apache License, Version 2.0 |
| SmallRye Fault Tolerance: Vert.x Integration | Apache License, Version 2.0 |
| SmallRye Mutiny - Code Generator | Apache License, Version 2.0 |
| SmallRye Mutiny - Core library | Apache License, Version 2.0 |
| SmallRye Mutiny - Integration with SmallRye Context Propagation | Apache License, Version 2.0 |
| SmallRye Mutiny - Runtime Helpers | Apache License, Version 2.0 |
| SmallRye Mutiny - Vert.x Auth Common | Apache License, Version 2.0 |
| SmallRye Mutiny - Vert.x Bridge Common | Apache License, Version 2.0 |
| SmallRye Mutiny - Vert.x Core | Apache License, Version 2.0 |
| SmallRye Mutiny - Vert.x URI Template | Apache License, Version 2.0 |
| SmallRye Mutiny - Vert.x Web | Apache License, Version 2.0 |
| SmallRye Mutiny - Vert.x Web Common | Apache License, Version 2.0 |
| SmallRye Mutiny Zero JDK Flow / Reactive Streams Adapters | Apache License, Version 2.0 |
| SmallRye Stork : Core | Apache License, Version 2.0 |
| SmallRye Stork : Main API classes | Apache License, Version 2.0 |
| SnakeYAML | Apache License, Version 2.0 |
| stack-utils | MIT License |
| string-width | MIT License |
| strip-ansi | MIT License |
| supports-color | MIT License |
| supports-hyperlinks | MIT License |
| swagger-annotations | Apache License, Version 2.0 |
| swagger-compat-spec-parser | Apache License, Version 2.0 |
| swagger-core | Apache License, Version 2.0 |
| swagger-models | Apache License, Version 2.0 |
| swagger-parser | Apache License, Version 2.0 |
| swagger-parser-core | Apache License, Version 2.0 |
| swagger-parser-safe-url-resolver | Apache License, Version 2.0 |
| swagger-parser-v2-converter | Apache License, Version 2.0 |
| swagger-parser-v3 | Apache License, Version 2.0 |
| terminal-link | MIT License |
| tinycolor2 | MIT License |
| tinygradient | MIT License |
| to-rotated | MIT License |
| type-fest | MIT License |
| undici-types | MIT License |
| univocity-parsers | Apache License, Version 2.0 |
| Vert.x Auth Common | Apache License, Version 2.0 |
| Vert.x Bridge Common | Apache License, Version 2.0 |
| Vert.x Codegen | Apache License, Version 2.0 |
| Vert.x Core | Apache License, Version 2.0 |
| Vert.x gRPC | Apache License, Version 2.0 |
| Vert.x gRPC Client | Apache License, Version 2.0 |
| Vert.x gRPC Common | Apache License, Version 2.0 |
| Vert.x gRPC Server | Apache License, Version 2.0 |
| Vert.x URI Template | Apache License, Version 2.0 |
| Vert.x Web | Apache License, Version 2.0 |
| Vert.x Web Client | Apache License, Version 2.0 |
| Vert.x Web Common | Apache License, Version 2.0 |
| widest-line | MIT License |
| wildfly-common | Apache License, Version 2.0 |
| wrap-ansi | MIT License |
| ws | MIT License |
| y18n | ISC License |
| yargs | MIT License |
| yargs-parser | ISC License |
| yauzl | MIT License |
| yoga-layout | MIT License |
# Cover Third Party Notices and/or Licenses
Source: https://docs.diffblue.com/legal/diffblue-legal/cover-third-party-notices-and-or-licenses
This document is hosted on the Diffblue Cover documentation site.
# End User License Agreement (EULA)
Source: https://docs.diffblue.com/legal/diffblue-legal/diffblue-end-user-license-agreement-eula
This document is hosted on the Diffblue Cover documentation site.
# Diffblue Legal
Source: https://docs.diffblue.com/legal/diffblue-legal/index
Please refer to the following:
* [Terms of Use](https://www.diffblue.com/legal/)
* [End User License Agreement (EULA)](/legal/diffblue-legal/diffblue-end-user-license-agreement-eula)
* [Diffblue Agents Third Party Notices and/or Licenses](/legal/diffblue-legal/agents-third-party-notices)
* [Cover Third Party Notices and/or Licenses](/legal/diffblue-legal/cover-third-party-notices-and-or-licenses)
* [Privacy Notice](/legal/diffblue-legal/privacy-notice)
© Copyright Diffblue Limited 2026. All rights reserved.
Diffblue, Diffblue Cover, and the Diffblue logo are trademarks of Diffblue Ltd. All other product, service, and company names are the trademarks or registered trademarks of their respective owners.
[www.diffblue.com/contact](https://www.diffblue.com/contact)
# Privacy Notice
Source: https://docs.diffblue.com/legal/diffblue-legal/privacy-notice
This document is hosted on the Diffblue Cover documentation site.
# Quickstart
Source: https://docs.diffblue.com/quickstart
Activate your license and run the Diffblue Testing Agent
## Prerequisites
* Diffblue Agents [installed](/installation)
* A license key with the Diffblue Testing Agent enabled (from your Diffblue account manager or trial sign-up)
* A [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) installed and authenticated — run `diffblue-agents install` to configure
* A Java or Python project that meets the [project requirements](/workflows/regression-unit-tests#project-requirements)
## Activate your license
Run the activation command with your license key:
```bash theme={null}
diffblue-agents license activate
```
Verify the license is active:
```bash theme={null}
diffblue-agents license
```
You should see your license status, edition, licensed agents, and expiry date.
## Prepare your project
In your terminal, navigate to your project directory. Before running Diffblue Agents, verify that your project builds and any existing tests pass. See the [project requirements](/workflows/regression-unit-tests#project-requirements) for language-specific details.
## Trust the project directory
Your AI coding agent must trust the project directory before Diffblue Agents can use it.
Open your agent in the project root and approve the trust prompt. If available, select the option to remember this setting for future sessions. You only need to do this once per project.
```bash theme={null}
claude
```
Select the **Yes, I trust this folder** option.
```bash theme={null}
copilot
```
Select the **Yes, and remember this folder for future sessions** option.
## Create a branch
Ensure your working tree is clean before creating a branch — commit or stash any uncommitted changes:
```bash theme={null}
git status
```
Create a branch for the generated tests:
```bash theme={null}
git checkout -b diffblue-agents-tests
```
Diffblue Agents generates tests in temporary worktrees and cherry-picks passing tests to the current branch. Creating a dedicated branch keeps your main branch clean and lets you review the tests before merging.
## Run the regression unit test generation workflow
From the root of your project, start the workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests
```
Diffblue Agents starts its server, analyzes your project, and runs through the following stages:
* Detects project configuration and validates the build environment (see [prepare project workflow](/workflows/regression-unit-tests-prepare-project) for details)
* Measures baseline code coverage
* Determines what needs testing and partitions the work
* Displays a resource estimate and prompts you to confirm (`Y` to proceed, `n` to abort)
* Generates, compiles, and validates tests for each partition
* Commits passing tests and rolls back failing tests
* Reports final coverage and a summary
## Review the results
When the workflow completes, it displays a summary:
```
Runtime: 8m 5s (execution: 7m 42s, approval wait: 0m 23s) | Files Processed: 22 | Callable Functions: 87
Tests Generated: 136 (136 committed, 0 rolled back)
Module Language Line Coverage Lines Covered Branch Coverage
Total - 94.5% (+94.5%) 1842/1949 (+1842) 96.3% (+96.3%)
```
Generated tests are committed to your current branch. Review the commits with `git log` to see what was added.
## Next steps
* Validate your project setup before running test generation with the [prepare project workflow](/workflows/regression-unit-tests-prepare-project).
* Preview the scope and resource estimates with the [planning workflow](/workflows/regression-unit-tests-planning).
* See the [regression unit test generation](/workflows/regression-unit-tests) workflow for language-specific details and options.
* See [troubleshooting](/troubleshooting) if you run into issues.
# CLI reference
Source: https://docs.diffblue.com/reference/cli
Commands, environment variables, and usage examples for the Diffblue Agents CLI
## Commands
```
diffblue-agents [command] [options]
```
| Command | Description |
| ---------------------------- | ----------------------------------------------- |
| `help` | Show help message |
| `version` | Show the version of this application |
| `workflows` | Show available workflows and their requirements |
| `run [ARGS...]` | Run a workflow with optional arguments |
| `install` | Configure an AI coding agent interactively |
| `license` | Show license status, licensed agents, and quota |
| `license activate ` | Activate a license key |
| `license deactivate` | Deactivate the current license |
## Environment variables
| Variable | Description | Default |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `DIFFBLUE_AGENTS_SERVER_SCHEME` | Server communication protocol | |
| `DIFFBLUE_AGENTS_SERVER_NAME` | Server host | `localhost` |
| `DIFFBLUE_AGENTS_SERVER_PORT` | Server port override (normally auto-assigned; see `.diffblue/server.json`) | |
| `DIFFBLUE_AGENTS_SERVER_REQUEST_TIMEOUT` | Request timeout in ms | `5000` |
| `DIFFBLUE_AGENTS_JAVA_HOME` | Java installation for building and testing target projects | |
| `DIFFBLUE_AGENTS_PLATFORM` | Agent platform: `claude`, `copilot`, `gemini`, or `opencode` | `claude` |
| `DIFFBLUE_AGENTS_CLAUDE_CLI_PATH` | Path to Claude CLI executable | `claude` |
| `DIFFBLUE_AGENTS_CLI_MAX_TURNS` | Max agent turns per CLI invocation (Claude and Copilot only; ignored by Gemini and OpenCode) | `25` |
| `DIFFBLUE_AGENTS_AGENT_TIMEOUT` | CLI agent process timeout, ISO-8601 | `PT20M` |
| `DIFFBLUE_AGENTS_PLANNING_DETECTION_TIMEOUT` | Planning detection step timeout, ISO-8601 | `PT20M` |
| `DIFFBLUE_AGENTS_TEST_GENERATION_TIMEOUT` | Per work-unit test generation timeout, ISO-8601 | `PT10M` |
| `DIFFBLUE_AGENTS_PROCESS_TIMEOUT` | Default subprocess timeout (utility commands), ISO-8601 | `PT2M` |
| `DIFFBLUE_AGENTS_COVERAGE_TEST_TIMEOUT` | Test execution timeout during coverage measurement, ISO-8601 | `PT5M` |
| `DIFFBLUE_AGENTS_COPILOT_CLI_PATH` | Path to Copilot CLI executable | `copilot` |
| `DIFFBLUE_AGENTS_GEMINI_CLI_PATH` | Path to Gemini CLI executable | `gemini` |
| `DIFFBLUE_AGENTS_OPENCODE_CLI_PATH` | Path to OpenCode CLI executable | `opencode` |
| `DIFFBLUE_AGENTS_OPENCODE_MODEL` | OpenCode model override in `provider/model` form (for example, `anthropic/claude-sonnet-4-6`). When unset, Diffblue Agents picks the first available model from a built-in fallback list. | |
| `DIFFBLUE_AGENTS_GIT_SIGNING` | Enable git commit/tag signing | `true` |
## Examples
List available workflows:
```bash theme={null}
diffblue-agents workflows
```
Run a workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests
```
Run on a custom server port:
```bash theme={null}
DIFFBLUE_AGENTS_SERVER_PORT=8081 diffblue-agents run regression-unit-tests
```
# Network configuration
Source: https://docs.diffblue.com/reference/network-configuration
Configure proxy settings for Diffblue Agents in corporate network environments
## Configuration sources
Properties are read in the following priority order (highest priority first):
1. Environment variables (`DIFFBLUE_AGENTS_PROXY_HOST=proxy.example.com`)
2. User config file (`~/.diffblue/agents/config.properties`)
Environment variable names are derived from property names by converting to uppercase and replacing dots and hyphens with underscores. For example, `diffblue.agents.proxy.host` becomes `DIFFBLUE_AGENTS_PROXY_HOST`.
## Proxy configuration
Route outbound server traffic through a corporate HTTP proxy. This applies to license validation and telemetry.
| Property | Environment variable | Description |
| -------------------------------- | -------------------------------- | ----------------------------------- |
| `diffblue.agents.proxy.host` | `DIFFBLUE_AGENTS_PROXY_HOST` | Proxy server hostname or IP address |
| `diffblue.agents.proxy.port` | `DIFFBLUE_AGENTS_PROXY_PORT` | Proxy server port |
| `diffblue.agents.proxy.username` | `DIFFBLUE_AGENTS_PROXY_USERNAME` | Username for proxy authentication |
| `diffblue.agents.proxy.password` | `DIFFBLUE_AGENTS_PROXY_PASSWORD` | Password for proxy authentication |
The proxy is enabled when both `host` and `port` are set. If only one is set, the proxy is not used. Authentication credentials are optional — set both `username` and `password` if the proxy requires authentication.
### Configure via environment variables
```bash theme={null}
export DIFFBLUE_AGENTS_PROXY_HOST=proxy.example.com
export DIFFBLUE_AGENTS_PROXY_PORT=8080
export DIFFBLUE_AGENTS_PROXY_USERNAME=myuser
export DIFFBLUE_AGENTS_PROXY_PASSWORD=mypassword
```
### Configure via config file
Create or edit `~/.diffblue/agents/config.properties`:
```properties theme={null}
diffblue.agents.proxy.host=proxy.example.com
diffblue.agents.proxy.port=8080
diffblue.agents.proxy.username=myuser
diffblue.agents.proxy.password=mypassword
```
# Telemetry export
Source: https://docs.diffblue.com/reference/telemetry-export
Forward Diffblue Agents telemetry to your own OpenTelemetry-compatible collector
Diffblue Agents emits structured telemetry events throughout workflow execution. Events are stored locally at `~/.diffblue/agents/telemetry/events-*.jsonl`. To send them to an external observability platform, configure one or more OTLP-compatible collectors such as Grafana, Datadog, or Honeycomb.
## Configure an OTLP endpoint
Add one or more OTLP endpoints to `~/.diffblue/agents/config.properties`. Each endpoint is identified by a numeric prefix (1 to 99).
```properties theme={null}
otel.exporter.otlp.1.endpoint=https://otlp.example.com:4318/v1/logs
otel.exporter.otlp.1.timeout=30s
otel.exporter.otlp.1.headers=Authorization=Bearer
```
| Property | Description |
| --------------------------------- | ------------------------------------------------- |
| `otel.exporter.otlp..endpoint` | OTLP HTTP endpoint URL (required) |
| `otel.exporter.otlp..timeout` | Request timeout (default: `30s`) |
| `otel.exporter.otlp..headers` | HTTP headers as comma-separated `key=value` pairs |
Replace `` with a number from 1 to 99.
### Multiple endpoints
```properties theme={null}
# Primary collector
otel.exporter.otlp.1.endpoint=https://otlp.example.com:4318/v1/logs
otel.exporter.otlp.1.headers=Authorization=Bearer
# Secondary collector
otel.exporter.otlp.2.endpoint=https://backup-otlp.example.com:4318/v1/logs
otel.exporter.otlp.2.headers=Authorization=Bearer
```
### Provider examples
```properties theme={null}
otel.exporter.otlp.1.endpoint=https://otlp-gateway-prod-gb-south-1.grafana.net/otlp/v1/logs
otel.exporter.otlp.1.headers=Authorization=Basic
```
```properties theme={null}
otel.exporter.otlp.1.endpoint=https://http-intake.logs.datadoghq.com/api/v2/logs
otel.exporter.otlp.1.headers=DD-API-KEY=
```
```properties theme={null}
otel.exporter.otlp.1.endpoint=https://api.honeycomb.io/v1/logs
otel.exporter.otlp.1.headers=x-honeycomb-team=
```
Refer to your provider's documentation for the exact endpoint URL and authentication header format. These may vary by region or account.
## Error handling
Invalid endpoint configurations are skipped without affecting workflow execution. Diffblue Agents logs a warning to stderr for:
* Malformed endpoint URLs
* Invalid timeout values (the default of 30 seconds is used instead)
* Malformed header key-value pairs
If an endpoint is unreachable at runtime, events are dropped for that endpoint. Other configured endpoints and the workflow itself are not affected.
# Support
Source: https://docs.diffblue.com/support
Get help with Diffblue Agents through self-service resources and the community forum
## Self-service
Start with the resources available in this documentation:
* [Troubleshooting](/troubleshooting) — solutions for common issues with installation, licensing, and workflow execution.
* [CLI reference](/reference/cli) — all available commands and options.
## Community forum
Ask questions, report issues, share feedback, and connect with other Diffblue Agents users on the [Diffblue community forum](https://forum.diffblue.com/).
## Dedicated support
Customers on paid support plans have access to dedicated support. Contact your Diffblue account manager for details.
# Requirements
Source: https://docs.diffblue.com/system-requirements
System and project requirements for running Diffblue Agents
## System requirements
| Requirement | Details |
| ---------------- | ------------------------ |
| Operating system | macOS, Linux, or Windows |
| Git | 2.25+ |
### Supported AI coding agent platforms
You need one of the following AI coding agent platforms installed and authenticated:
* Claude Code
* GitHub Copilot CLI
* Google Gemini CLI
* [OpenCode](https://opencode.ai/docs/) — open-source agent CLI. Supported providers include Anthropic, AWS Bedrock, and Google. Configure credentials per the [OpenCode provider docs](https://opencode.ai/docs/providers/).
Run `diffblue-agents install` to select your agent platform or provide a custom path.
The Diffblue Agents archive includes bundled Java and Node.js runtimes. You only need to install Java and Node.js if needed for building and testing your target project.
## Project requirements
Your project must be in a Git repository with a clean working tree.
### Java projects
| Requirement | Details |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| Java | JDK version(s) relevant for your particular project must be installed. |
| Build tool | Maven or Gradle. `mvn` or `gradle` must be on `PATH` or Maven/Gradle wrapper is present in your project's root. |
### Python projects
| Requirement | Details |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Python | A `python3`, `python`, or `py` interpreter must be installed. Diffblue Agents scans `PATH` and common installation locations (Homebrew, pyenv, asdf, Conda, system directories) automatically. |
| venv | The `venv` module must be available. On Debian/Ubuntu (including WSL), install `python3-venv` separately: `sudo apt install python3-venv`. On macOS and Windows, `venv` is included with Python. |
| Test framework | Dependencies such as `pytest` and `pytest-cov` are installed automatically by the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) if not already installed. |
## Network access
The Diffblue Agents server runs locally. Network access is required for:
* License activation and validation (`https://api.licensespring.com`, `https://licensing.diffblue.com`)
* A working [AI coding agent platform](#supported-ai-coding-agent-platforms)
* Dependency resolution (Maven Central, Gradle repositories, PyPI, etc.)
# Quickstart
Source: https://docs.diffblue.com/test-quality-quickstart
Assess your test quality with the Diffblue Test Quality Agent
## Prerequisites
* Diffblue Agents [installed](/installation) (no license required)
* A [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) installed and authenticated — run `diffblue-agents install` to configure
* A project that meets the [project requirements](/workflows/test-quality-report#project-requirements)
## Run the test quality report
From the root of your project, start the workflow:
```bash theme={null}
diffblue-agents run test-quality-report
```
Diffblue Agents starts its server, analyzes your project, and runs through the following stages:
* Detects your build system, language, and modules
* Configures coverage and mutation testing tools if not already present
* Runs coverage and mutation analysis
* Displays a per-module quality report
## Review the results
The report shows four metrics for each module and class:
| Metric | Meaning |
| ------------------- | ------------------------------------------------- |
| **Line coverage** | Percentage of code lines executed by tests |
| **Branch coverage** | Percentage of code branches executed by tests |
| **Mutation score** | Percentage of code mutations detected by tests |
| **Test strength** | Percentage of covered mutations detected by tests |
See [understanding the report](/workflows/test-quality-report#understanding-the-report) for details on interpreting the metrics.
## Next steps
* See the [test quality report](/workflows/test-quality-report) workflow for filtering options and tool configuration details.
* Address gaps identified in the report by running the [Diffblue Testing Agent](/quickstart).
# Troubleshooting
Source: https://docs.diffblue.com/troubleshooting
Solutions for common issues with Diffblue Agents
## Installation and setup
Your build tool may require a different Java version than what is currently active. Verify which version is active:
```bash theme={null}
java -version
echo $JAVA_HOME
```
Check what your project targets (e.g. `sourceCompatibility` in `build.gradle` or `maven.compiler.source` in `pom.xml`) and ensure a compatible Java version is installed and selected. For example, a project targeting Java 18 needs at least Java 18 — but Java 21 works too.
Update `JAVA_HOME` and `PATH` to point to the correct installation:
```bash theme={null}
export JAVA_HOME=/path/to/correct/jdk
export PATH="$JAVA_HOME/bin:$PATH"
```
Diffblue Agents uses the Python interpreter on your `PATH`. Verify which version is active:
```bash theme={null}
python3 --version
```
If your project uses a virtual environment, activate it before running the workflow:
```bash theme={null}
source venv/bin/activate
```
Diffblue Agents requires Python 3.9 or later. If you have multiple Python versions installed, ensure the correct one is first on your `PATH`.
Diffblue Agents requires a [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) on your `PATH` and authenticated. Verify it is available:
```bash theme={null}
claude --version
```
If the command is not found, install and authenticate the coding agent before running Diffblue Agents. Check the [system requirements](/system-requirements) for supported platforms.
macOS may quarantine files downloaded from the internet. Remove the quarantine attribute:
```bash theme={null}
xattr -r -d com.apple.quarantine diffblue-agents/
```
Windows may block downloaded scripts from executing. In PowerShell, navigate into the Diffblue Agents installation directory and run:
```powershell theme={null}
Unblock-File cli\diffblue-agents.ps1
Unblock-File server\diffblue-agents-server.ps1
Unblock-File jre\bin\java.exe
```
Restart your terminal after unblocking.
If the scripts still fail to execute after unblocking, set your PowerShell execution policy to RemoteSigned for the current user. This allows signed scripts downloaded from the Internet to run:
```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Another process is using the assigned port. Either stop the other process, or override the port:
```bash theme={null}
DIFFBLUE_AGENTS_SERVER_PORT=9090 diffblue-agents run regression-unit-tests
```
The CLI cannot reach the Diffblue Agents Server. Check the port the server is running on from `.diffblue/server.json` in your project root:
```bash theme={null}
cat .diffblue/server.json
```
Then verify the server is reachable:
```bash theme={null}
curl http://localhost:/workflows
```
If `.diffblue/server.json` does not exist, the server is not running. A stale file (where the PID is no longer active) indicates the server crashed — restart the workflow.
## Licensing
Check the following:
* Your machine can reach `https://api.licensespring.com`, `https://licensing.diffblue.com`, and `https://otlp-gateway-prod-gb-south-1.grafana.net`. Check that firewall rules allow outbound connections to these URLs.
* Your system clock is accurate. License validation is time-sensitive.
* The license key is entered correctly, including hyphens.
* Your [proxy settings](/reference/network-configuration#proxy-configuration) are correct, if your network requires a proxy.
If the issue persists, contact your Diffblue account manager.
The workflow requires access to an agent that is not enabled on your license. Your license is active but does not include the agent this workflow needs.
Check which agents are enabled on your license:
```bash theme={null}
diffblue-agents license
```
Look for the **Agents** row in the output. Run `diffblue-agents workflows` to see which workflows you can access and which require additional agent access.
Visit the [Diffblue pricing page](https://www.diffblue.com/pricing/) or contact your Diffblue account manager to upgrade your license.
Your license quota (measured in additional lines covered) has been reached. The current workflow completes its in-progress work but does not start new partitions.
Check your remaining quota:
```bash theme={null}
diffblue-agents license
```
Visit the [Diffblue pricing page](https://www.diffblue.com/pricing/) or contact your Diffblue account manager to upgrade your license.
## Workflow execution
The workflow checks that your project builds and existing tests pass before generating new tests. If validation fails:
To catch validation issues before running the full workflow, run the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) first.
1. Verify the project builds:
* Maven: `mvn compile`
* Gradle: `./gradlew clean build`
2. Verify existing tests pass:
* Maven: `mvn test`
* Gradle: `./gradlew test`
3. Ensure JaCoCo is configured and Mockito is in your test dependencies.
4. Fix any build or test failures, then re-run the workflow.
1. Verify existing tests pass:
```bash theme={null}
pytest
```
2. Ensure pytest-cov is installed:
```bash theme={null}
pip show pytest-cov
```
3. If your project uses a virtual environment, ensure it is activated.
4. Fix any test failures, then re-run the workflow.
Diffblue Agents validates every generated test by compiling and running it. Tests that fail validation are rolled back automatically. This is expected behavior. The workflow summary shows how many tests were committed and how many were rolled back.
A high rollback rate may indicate that the target code is difficult to test in isolation, or that the project has complex dependencies that affect test execution.
Diffblue Agents generates tests in a temporary worktree and cherry-picks committed tests back to your branch. If you made changes to the same files while the workflow was running, cherry-pick conflicts can occur.
Resolve conflicts using standard git conflict resolution. The workflow reports which commits had conflicts.
Diffblue Agents caches the build environment state in `.diffblue/project-state.json` to skip environment setup on repeat runs. If the cache is stale or corrupt, delete it to force a fresh setup:
```bash theme={null}
rm .diffblue/project-state.json
```
This file is safe to delete at any time. Diffblue Agents recreates it after the next successful environment setup.
## Still need help?
If your issue is not listed here, ask on the [Diffblue community forum](https://forum.diffblue.com/) or see the [support](/support) page for all available channels.
# Regression unit test generation
Source: https://docs.diffblue.com/workflows/regression-unit-tests
Generate regression unit tests across an entire project
## Prerequisites
* Diffblue Agents [installed](/installation) with an active license and the Diffblue Testing Agent enabled
* A [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) installed and authenticated
## Project requirements
Your project must meet the following requirements before running the workflow.
| Requirement | Details |
| ----------------- | ---------------------------------------- |
| Build system | Maven or Gradle |
| Java version | 8+ |
| Testing framework | JUnit (4, 5, or 6) |
| Build state | Project compiles and existing tests pass |
| Version control | Git repository with a clean working tree |
Verify that your project builds and existing tests pass:
```bash Maven theme={null}
mvn clean compile && mvn test
```
```bash Gradle theme={null}
./gradlew clean build && ./gradlew test
```
You can use your AI coding agent platform to help fix failing tests before running the workflow.
| Requirement | Details |
| ----------------- | ---------------------------------------- |
| Python version | 3.9+ |
| Testing framework | pytest |
| Coverage tool | pytest-cov in dependencies |
| Build state | Existing tests pass |
| Version control | Git repository with a clean working tree |
Verify that pytest and pytest-cov are installed and your existing tests pass:
```bash theme={null}
pytest
```
If your project uses a virtual environment, activate it before running the workflow. Diffblue Agents detects and uses the active virtual environment automatically.
## Run the workflow
Diffblue Agents automatically detects the project language, build system, and test framework.
1. Open a terminal at the root of your project.
2. [Trust the project directory](/quickstart#trust-the-project-directory) if you have not already done so.
3. Create a branch for the generated tests:
```bash theme={null}
git checkout -b diffblue-agents-tests
```
Creating a dedicated branch keeps your main branch clean and lets you review the tests before merging.
4. Start the workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests
```
5. Diffblue Agents displays a resource estimate including expected duration and estimated AI coding agent token consumption, then prompts you to confirm:
```
Continue with test generation? (Y/n)
```
Press `Y` to proceed or `n` to abort. Token estimates are indicative — actual costs depend on your subscription with the AI coding agent platform.
## Preview the workflow
To validate your project setup and preview the scope of work before running the full test generation workflow, use the [planning workflow](/workflows/regression-unit-tests-planning).
```bash theme={null}
diffblue-agents run regression-unit-tests-planning
```
The planning workflow performs all preparation and analysis steps without generating tests. See the [planning workflow](/workflows/regression-unit-tests-planning) documentation for details.
Use this workflow to catch and correct environment issues early or to review the estimated token consumption before committing to a full run.
The `regression-unit-tests-planning` workflow:
* Verifies your project configuration
* Measures baseline coverage
* Partitions the work
* Provides a resource estimate (expected duration and estimated AI coding agent platform token consumption)
To run only the environment validation step without measuring coverage or estimating resources, use the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) instead.
## Filter by module
For multi-module projects, you can limit test generation to specific modules using the `--module` flag:
```bash theme={null}
diffblue-agents run regression-unit-tests --module apps/server,apps/cli
```
The flag accepts a comma-separated list of module paths relative to the project root. The workflow only analyzes and generates tests for the specified modules.
You can combine module filtering with package or class filters:
```bash theme={null}
diffblue-agents run regression-unit-tests com.example.owner,com.example.vet --module apps/server
```
Module filtering also works with the planning-only workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests-planning --module apps/server
```
If you specify a module that doesn't exist in the project, the workflow will fail with an error listing the valid module names.
## Filter by class or package
To limit test generation to specific classes or packages, use the `--filter` flag:
```bash theme={null}
# Single filter
diffblue-agents run regression-unit-tests --filter com.example.owner
# Multiple filters (comma-separated)
diffblue-agents run regression-unit-tests --filter com.example.owner,com.example.vet
```
On PowerShell, quote the value to prevent shell splitting:
```powershell theme={null}
diffblue-agents run regression-unit-tests --filter "com.example.owner,com.example.vet"
```
Diffblue Agents accepts simple class names and matches them to their fully qualified form automatically:
```bash theme={null}
diffblue-agents run regression-unit-tests --filter OwnerController
```
The flag accepts a comma-separated list of class names or package prefixes.
Filtering also works with the planning-only workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests-planning --filter com.example.owner
```
You can combine class or package filters with `--module`:
```bash theme={null}
diffblue-agents run regression-unit-tests --filter com.example.owner,com.example.vet --module apps/server
```
## Skip the approval prompt
To run the workflow without the interactive approval prompt, pass `--auto-approve`:
```bash theme={null}
diffblue-agents run regression-unit-tests --auto-approve
```
Use this flag for CI/CD pipelines and other unattended environments.
Non-interactive environments (piped output, no TTY) auto-approve automatically. Pass `--auto-approve` explicitly to suppress the informational message.
## What the regression-unit-tests workflow does
The `regression-unit-tests` workflow runs through the following stages:
1. **Plan** — prepares the project (see [prepare project workflow](/workflows/regression-unit-tests-prepare-project) for details), measures baseline coverage, and determines what needs testing. This is the same phase that runs when you use `regression-unit-tests-planning` above.
2. **Approve** — displays a resource estimate and prompts you to confirm before proceeding. Press `Y` to continue or `n` to abort. If you pass `--auto-approve`, the workflow skips this step.
3. **Generate tests** — for each partition, Diffblue Agents:
* Plans test generation for the target code
* Delegates test writing to your AI coding agent platform
* Compiles and runs the generated tests
* Validates that tests pass and improve coverage
* Commits passing tests
* Rolls back tests that fail validation
All test generation runs in temporary git worktrees.
4. **Cherry-pick and report** — cherry-picks committed tests to your branch and displays a summary.
## Understand the results
When the workflow completes, the summary includes:
| Field | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Tests generated | Total number of tests written by the agent platform |
| Files processed | Number of source files that were targeted for test generation |
| Line coverage before | Baseline line coverage before the workflow ran |
| Line coverage after | Line coverage after committed tests are included |
| Runtime | Total workflow execution time. If you used the approval prompt, this includes a breakdown of execution time and approval wait time |
A high rollback count is normal. Diffblue Agents validates every test strictly — only tests that compile, pass, and improve coverage are kept.
## Troubleshooting
* If the workflow fails during validation, verify that your project builds and tests pass before re-running. See the [project requirements](#project-requirements) for language-specific commands.
* If cherry-pick conflicts are reported, you made changes to the same files while the workflow was running. Resolve conflicts with standard git conflict resolution.
* See the [troubleshooting](/troubleshooting) page for more common issues.
# Plan regression unit test generation
Source: https://docs.diffblue.com/workflows/regression-unit-tests-planning
Preview test generation scope and estimate resource consumption
Run this workflow to understand which modules and classes need tests and review resource estimates before running the full test generation workflow. The planning workflow performs all preparation and analysis steps without generating tests.
## Prerequisites
* Diffblue Agents [installed](/installation) with an active license and the Diffblue Testing Agent enabled
* A [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) installed and authenticated
## Project requirements
| Requirement | Details |
| ----------------- | ---------------------------------------- |
| Build system | Maven or Gradle |
| Java version | 8+ |
| Testing framework | JUnit (4, 5, or 6) |
| Build state | Project compiles and existing tests pass |
| Version control | Git repository with a clean working tree |
Verify that your project builds and existing tests pass:
```bash Maven theme={null}
mvn clean compile && mvn test
```
```bash Gradle theme={null}
./gradlew clean build && ./gradlew test
```
You can use your AI coding agent platform to help fix failing tests before running the workflow.
| Requirement | Details |
| ----------------- | ---------------------------------------- |
| Python version | 3.9+ |
| Testing framework | pytest |
| Coverage tool | pytest-cov in dependencies |
| Build state | Existing tests pass |
| Version control | Git repository with a clean working tree |
If you have existing tests, verify that pytest and pytest-cov are installed and your existing tests pass:
```bash theme={null}
pytest
```
If your project uses a virtual environment, activate it before running the workflow. Diffblue Agents detects and uses it automatically.
## Run the workflow
1. Open a terminal at the root of your project.
2. [Trust the project directory](/quickstart#trust-the-project-directory) if you have not already done so.
3. Create a branch for any environment setup changes:
```bash theme={null}
git checkout -b diffblue-agents-planning
```
4. Start the workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests-planning
```
## What the workflow does
### 1. Prepare project
The workflow validates and configures your build environment. See the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) for complete details.
The workflow verifies your project is a git repository, detects build system and modules, validates the build environment, and adds missing dependencies. If any build configuration changes are needed, the workflow commits them in a single commit. The workflow **only modifies build configuration files**, never your source code or test files.
### 2. Measure baseline coverage
The workflow measures coverage in an isolated git worktree. A *worktree* is a separate working directory linked to your repository that allows the workflow to measure coverage safely without affecting your current working directory.
The workflow:
1. Creates a temporary worktree
2. Runs your existing test suite
3. Collects coverage data for each module
4. Identifies untested or under-tested classes and methods
5. Cleans up the worktree
The coverage measurement shows current line coverage percentage per module and number of source files analyzed. The workflow identifies classes and methods that need test coverage.
### 3. Partition work
The workflow analyzes the coverage data to determine which classes need tests and how to group them into work units.
The workflow identifies classes with coverage below the target threshold and optimizes work units to balance work across parallel workers while keeping related code together.
### 4. Calculate resource estimates
The workflow provides estimates for the full test generation workflow:
| Estimate | Description |
| ----------------- | ----------------------------------------------------------- |
| Expected duration | Wall-clock time for the full test generation workflow |
| Token consumption | Estimated tokens your AI coding agent platform will consume |
| Units | Number of work units that will be processed in parallel |
Token estimates are indicative. Actual consumption depends on your project complexity, existing test quality, and your AI platform subscription.
### 5. Display summary
The workflow shows the planning results including baseline coverage per module, number of files and classes to be tested, and resource estimates for full test generation. Any modules that encountered errors during analysis are listed separately.
## Understanding the output
The workflow summary includes:
| Field | Description |
| ------------------ | -------------------------------------------------- |
| Modules analyzed | Number of modules successfully analyzed |
| Baseline coverage | Current line coverage before any test generation |
| Files to test | Number of source files identified as needing tests |
| Classes to test | Number of classes with coverage below threshold |
| Estimated duration | Expected time for full test generation |
| Estimated tokens | AI platform token consumption estimate |
| Units | Number of parallel work units |
The workflow lists any modules that failed analysis separately with error details.
## Filter by class or package
To limit planning to specific classes or packages, use the `--filter` flag:
```bash theme={null}
# Single filter
diffblue-agents run regression-unit-tests-planning --filter com.example.owner
# Multiple filters (comma-separated)
diffblue-agents run regression-unit-tests-planning --filter com.example.owner,com.example.vet
```
On PowerShell, quote the value to prevent shell splitting:
```powershell theme={null}
diffblue-agents run regression-unit-tests-planning --filter "com.example.owner,com.example.vet"
```
Diffblue Agents accepts simple class names and matches them to their fully qualified form automatically:
```bash theme={null}
diffblue-agents run regression-unit-tests-planning --filter OwnerController
```
The flag accepts a comma-separated list of class names or package prefixes.
## Filter by module
For multi-module projects, you can limit planning to specific modules using the `--module` flag:
```bash theme={null}
diffblue-agents run regression-unit-tests-planning --module apps/server,apps/cli
```
The flag accepts a comma-separated list of module paths relative to the project root. The workflow only analyzes the specified modules.
You can combine `--filter` with `--module`:
```bash theme={null}
diffblue-agents run regression-unit-tests-planning --filter com.example --module apps/server
```
If you specify a module that doesn't exist, the workflow fails with an error listing valid module names.
## After running the workflow
1. Review the resource estimates to decide if the token consumption and duration are acceptable for your use case.
2. Review any build configuration changes. If the workflow committed changes to build files, verify the changes are appropriate.
3. Check for module errors. If any modules failed analysis, fix the underlying issues before proceeding.
If you are satisfied with the planning results, proceed to the [regression unit test generation workflow](/workflows/regression-unit-tests).
To validate your project setup without measuring coverage or estimating resources, use the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) instead.
## Troubleshooting
* **Build verification fails**: Ensure your project compiles and existing tests pass. See the [project requirements](#project-requirements) for language-specific commands.
* **Coverage measurement fails**: Check that your project has the required coverage tools (JaCoCo for Java, pytest-cov for Python). The workflow adds these automatically during project preparation. Verify the tools are configured correctly.
* **"Nothing to test" error**: All your code is already fully covered by tests. No additional tests are needed.
* **Module filter errors**: Verify module paths are relative to the project root and match the structure detected during build system detection.
* See the [troubleshooting](/troubleshooting) page for more common issues.
## Related workflows
Validate and configure build environment only
Run the full test generation workflow
# Prepare project for test generation
Source: https://docs.diffblue.com/workflows/regression-unit-tests-prepare-project
Validate and configure your project's build environment for test generation
Run this workflow to validate your project setup, preview build configuration changes, or catch environment issues before running test generation. The workflow adds missing dependencies and configures build tools without generating tests or measuring coverage.
The prepare project workflow runs automatically as the first step of the [planning workflow](/workflows/regression-unit-tests#preview-the-workflow) and the [full test generation workflow](/workflows/regression-unit-tests). Run the prepare project workflow independently only if you want to validate your environment setup without proceeding to planning or test generation.
## Prerequisites
* Diffblue Agents [installed](/installation) with an active license and the Diffblue Testing Agent enabled
* A [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) installed and authenticated
## Project requirements
| Requirement | Details |
| --------------- | --------------- |
| Build system | Maven or Gradle |
| Java version | 8+ |
| Version control | Git repository |
The workflow helps identify and resolve build issues.
| Requirement | Details |
| --------------- | -------------- |
| Python version | 3.9+ |
| Version control | Git repository |
The workflow helps identify and resolve build issues.
If your project uses a virtual environment, activate the virtual environment before running the workflow. Diffblue Agents detects and uses it automatically.
## Run the workflow
1. Open a terminal at the root of your project.
2. [Trust the project directory](/quickstart#trust-the-project-directory) if you have not already done so.
3. Create a branch for the environment setup changes:
```bash theme={null}
git checkout -b diffblue-agents-setup
```
4. Start the workflow:
```bash theme={null}
diffblue-agents run regression-unit-tests-prepare-project
```
## What the workflow does
### 1. Verify git repository
The workflow verifies the project is a git repository. The workflow aborts if this check fails.
### 2. Detect project configuration
The workflow analyzes your project to identify:
* Build system (Maven, Gradle, or Python build tools)
* Project modules and structure
* Source and test directories
* Testing framework (if present)
* Existing dependencies
### 3. Validate and configure build environment
The workflow validates and configures your build environment in an isolated git worktree.
The workflow:
1. Creates a temporary worktree
2. Pre-creates test directories for test generation
3. Validates the build environment by checking for [required dependencies](#dependencies-that-may-be-added)
4. Adds missing dependencies to build configuration files
5. Commits valid changes and cherry-picks the changes back to your branch
6. Cleans up the temporary worktree
For Python projects, the workflow also:
* Removes stale virtual environments from the worktree
* Copies the virtual environment from the worktree back to your source repository
* Repairs virtual environment paths to work in the source location
### 4. Display summary
The workflow shows a summary of changes made to your build configuration.
## What files can be modified
The workflow **only commits changes to build configuration files**. The workflow never changes your source code or test files.
Build configuration files that may be committed:
* `pom.xml` (Maven projects)
* `build.gradle` / `build.gradle.kts` (Gradle projects)
* `.gitignore` (to exclude generated files)
* `pyproject.toml`
* `setup.py`
* `requirements.txt` / `requirements-dev.txt`
* `.gitignore` (to exclude virtual environments)
All changes are committed in a single commit with a descriptive message listing what was added or modified.
For Python projects, the workflow also creates or updates a `.venv` directory in your project root. The virtual environment files are not committed to git (they are excluded via `.gitignore`).
## Dependencies that may be added
The workflow ensures your project has the minimum dependencies required for test generation:
| Dependency | Purpose |
| ---------- | ------------------ |
| JUnit | Testing framework |
| Mockito | Mocking library |
| JaCoCo | Coverage reporting |
| Dependency | Purpose |
| ----------- | ------------------ |
| pytest | Testing framework |
| pytest-cov | Coverage reporting |
| pytest-mock | Mocking library |
The workflow also scans your existing test files for imports, decorators, and markers that indicate additional dependencies. Any detected dependencies are added to the dependency file and installed.
The workflow may upgrade existing dependencies, if necessary.
## Understanding the output
When the workflow completes, you see:
* **Build environment changes** — A list of modifications made (e.g., "Added JUnit 5.10.0", "Added JaCoCo Maven plugin")
* **A new commit** — The commit contains any modifications, with a descriptive message
If no changes were needed, the workflow completes with no modifications.
## After running the workflow
1. Review the commit to verify the changes are appropriate for your project.
2. If you need to adjust the changes, modify the build configuration files and amend the commit.
Your project environment is now configured for test generation.
## Next steps
* Run the [planning workflow](/workflows/regression-unit-tests-planning) to measure coverage and preview resource estimates
* Run the [regression unit test generation](/workflows/regression-unit-tests) workflow to generate tests
## Troubleshooting
* **Git repository check fails**: Ensure you are running the command from a git repository. Initialize one with `git init` if needed.
* **Build system detection fails**: Verify you have a valid `pom.xml`, `build.gradle`, or `pyproject.toml` file in your project root or module directories.
* **Changes not applied**: Check that you don't have uncommitted changes that conflict with the build configuration files. Commit or stash your changes before running the workflow.
* See the [troubleshooting](/troubleshooting) page for more common issues.
# Test quality report
Source: https://docs.diffblue.com/workflows/test-quality-report
Assess test quality with coverage, mutation score, and test strength metrics
Run this workflow to measure test coverage, mutation score, and test strength across your project. The report breaks down metrics per module and per class.
## Prerequisites
* Diffblue Agents [installed](/installation) (no license required)
* A [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) installed and authenticated
## Project requirements
| Requirement | Details |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Build system | Maven 3.8.6+ or Gradle 8.4+ |
| Java version | 8+ |
| Testing framework | JUnit (4, 5, or 6) |
| Mutation testing | Automatically configured ([PIT](https://pitest.org/)); the appropriate PIT version and JUnit plugin are selected based on your project's Java version |
| Build state | Project compiles and existing tests pass |
| Version control | Git repository with a clean working tree |
| Requirement | Details |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Python version | 3.7+ (Linux/macOS); 3.7-3.12 (Windows, 3.13+ unsupported) |
| Testing framework | pytest |
| Mutation testing | Automatically configured ([mutmut](https://mutmut.readthedocs.io/)); the appropriate mutmut version is selected based on your project's Python version |
| Build state | Existing tests pass |
| Version control | Git repository with a clean working tree |
## Run the workflow
```bash theme={null}
diffblue-agents run test-quality-report
```
The workflow:
1. Detects your build system, language, and modules
2. Configures coverage and mutation testing tools if not already present
3. Runs coverage and mutation analysis
4. Displays a per-module quality report
## Filter by module
Limit the assessment to specific modules with `--module`:
```bash theme={null}
diffblue-agents run test-quality-report --module apps/server
```
## Filter by package or class
Scope the assessment to a specific package or class with `--filter`:
```bash theme={null}
diffblue-agents run test-quality-report --filter com.example.payments
```
## Understanding the report
The report shows four metrics for each module and class:
| Metric | Meaning |
| ------------------- | ------------------------------------------------------------------------------------ |
| **Line coverage** | Percentage of code lines executed by tests |
| **Branch coverage** | Percentage of code branches (if/else, switch) executed by tests |
| **Mutation score** | Percentage of code mutations detected by tests (killed mutants / total mutants) |
| **Test strength** | Percentage of covered mutations detected by tests (killed mutants / covered mutants) |
### What the metrics tell you
* **High line coverage, low mutation score**: Your tests run the code but don't verify its behavior. Assertions may be missing or too weak.
* **Low line coverage, high test strength**: The code that is covered is tested effectively, but not enough code is actually covered.
* **Low line coverage**: Parts of your code aren't reached by any test.
## Tool configuration
The workflow automatically configures mutation testing tools if they are not already present:
* **Java**: Adds the [PIT (Pitest)](https://pitest.org/) Maven or Gradle plugin
* **Python**: Installs [mutmut](https://mutmut.readthedocs.io/) in the virtual environment
Tool configuration changes are committed to your repository only after a successful run. On subsequent runs, the tools are already configured and the workflow skips this step.
## Next steps
Address gaps identified in the report by running the Diffblue Testing Agent:
```bash theme={null}
diffblue-agents run regression-unit-tests
```