Skip to main content
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

​
Project requirements

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

  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 any environment setup changes: 
    git checkout -b diffblue-agents-planning
  4. Start the workflow: 
    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 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:
EstimateDescription
Expected durationWall-clock time for the full test generation workflow
Token consumptionEstimated tokens your AI coding agent platform will consume
UnitsNumber 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:
FieldDescription
Modules analyzedNumber of modules successfully analyzed
Baseline coverageCurrent line coverage before any test generation
Files to testNumber of source files identified as needing tests
Classes to testNumber of classes with coverage below threshold
Estimated durationExpected time for full test generation
Estimated tokensAI platform token consumption estimate
UnitsNumber of parallel work units
The workflow lists any modules that failed analysis separately with error details.

​
Filter by module

For multi-module projects, you can limit planning to specific modules using the --module flag: 
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 module filtering with package or class filters: 
diffblue-agents run regression-unit-tests-planning 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.
To validate your project setup without measuring coverage or estimating resources, use the prepare project workflow instead.

​
Troubleshooting

  • Build verification fails: Ensure your project compiles and existing tests pass. See the 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 page for more common issues.

Prepare project

Validate and configure build environment only

Generate tests

Run the full test generation workflow