> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diffblue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan regression unit test generation

> 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

<Tabs>
  <Tab title="Java">
    | 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:

    <CodeGroup>
      ```bash Maven theme={null}
      mvn clean compile && mvn test
      ```

      ```bash Gradle theme={null}
      ./gradlew clean build && ./gradlew test
      ```
    </CodeGroup>

    <Note>
      You can use your AI coding agent platform to help fix failing tests before running the workflow.
    </Note>
  </Tab>

  <Tab title="Python">
    | 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.
  </Tab>
</Tabs>

## 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     |

<Warning>
  Token estimates are indicative. Actual consumption depends on your project complexity, existing test quality, and your AI platform subscription.
</Warning>

### 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).

<Tip>
  To validate your project setup without measuring coverage or estimating resources, use the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) instead.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Prepare project" icon="wrench" href="/workflows/regression-unit-tests-prepare-project">
    Validate and configure build environment only
  </Card>

  <Card title="Generate tests" icon="flask" href="/workflows/regression-unit-tests">
    Run the full test generation workflow
  </Card>
</CardGroup>