Skip to main content

​
Prerequisites

​
Project requirements

Your project must meet the following requirements before running the workflow.
Verify that your project builds and existing tests pass:
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:
    Creating a dedicated branch keeps your main branch clean and lets you review the tests before merging.
  4. Start the workflow:
  5. Diffblue Agents displays a resource estimate including expected duration and estimated AI coding agent token consumption, then prompts you to confirm:
    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.
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:
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:
Module filtering also works with the planning-only workflow:
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:
On PowerShell, quote the value to prevent shell splitting:
Diffblue Agents accepts simple class names and matches them to their fully qualified form automatically:
The flag accepts a comma-separated list of class names or package prefixes. Filtering also works with the planning-only workflow:
You can combine class or package filters with --module:

​
Skip the approval prompt

To run the workflow without the interactive approval prompt, pass --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: 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.