Skip to main content

​
Prerequisites

​
Project requirements

Your project must meet the following requirements before running the workflow.
RequirementDetails
Build systemMaven or Gradle
Java version8+
Testing frameworkJUnit (4, 5, or 6)
Build stateProject compiles and existing tests pass
Version controlGit repository with a clean working tree
Verify that your project builds and existing tests pass:
mvn clean compile && mvn test
You can use your AI coding agent platform to help fix failing tests before running the workflow.

​
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 if you have not already done so.
  3. Create a branch for the generated tests: 
    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: 
    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. 
diffblue-agents run regression-unit-tests-planning
The planning workflow performs all preparation and analysis steps without generating tests. See the planning workflow 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 instead.

​
Filter by module

For multi-module projects, you can limit test generation to specific modules using the --module flag: 
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: 
diffblue-agents run regression-unit-tests com.example --module apps/server
Module filtering also works with the planning-only workflow: 
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.

​
Skip the approval prompt

To run the workflow without the interactive approval prompt, pass --auto-approve: 
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 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.
  1. 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:
FieldDescription
Tests generatedTotal number of tests written by the agent platform
Files processedNumber of source files that were targeted for test generation
Line coverage beforeBaseline line coverage before the workflow ran
Line coverage afterLine coverage after committed tests are included
RuntimeTotal 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 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 page for more common issues.