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

# Regression unit test generation

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

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

    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.
  </Tab>
</Tabs>

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

<Tip>
  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.
</Tip>

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