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

# Prepare project for test generation

> Validate and configure your project's build environment for test generation

Run this workflow to validate your project setup, preview build configuration changes, or catch environment issues before running test generation. The workflow adds missing dependencies and configures build tools without generating tests or measuring coverage.

<Note>
  The prepare project workflow runs automatically as the first step of the [planning workflow](/workflows/regression-unit-tests#preview-the-workflow) and the [full test generation workflow](/workflows/regression-unit-tests). Run the prepare project workflow independently only if you want to validate your environment setup without proceeding to planning or test generation.
</Note>

## 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+              |
    | Version control | Git repository  |

    The workflow helps identify and resolve build issues.
  </Tab>

  <Tab title="Python">
    | Requirement     | Details        |
    | --------------- | -------------- |
    | Python version  | 3.9+           |
    | Version control | Git repository |

    The workflow helps identify and resolve build issues.

    If your project uses a virtual environment, activate the virtual environment 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 the environment setup changes:

   ```bash theme={null}
   git checkout -b diffblue-agents-setup
   ```

4. Start the workflow:

   ```bash theme={null}
   diffblue-agents run regression-unit-tests-prepare-project
   ```

## What the workflow does

### 1. Verify git repository

The workflow verifies the project is a git repository. The workflow aborts if this check fails.

### 2. Detect project configuration

The workflow analyzes your project to identify:

* Build system (Maven, Gradle, or Python build tools)
* Project modules and structure
* Source and test directories
* Testing framework (if present)
* Existing dependencies

### 3. Validate and configure build environment

The workflow validates and configures your build environment in an isolated git worktree.

The workflow:

1. Creates a temporary worktree
2. Pre-creates test directories for test generation
3. Validates the build environment by checking for [required dependencies](#dependencies-that-may-be-added)
4. Adds missing dependencies to build configuration files
5. Commits valid changes and cherry-picks the changes back to your branch
6. Cleans up the temporary worktree

For Python projects, the workflow also:

* Removes stale virtual environments from the worktree
* Copies the virtual environment from the worktree back to your source repository
* Repairs virtual environment paths to work in the source location

### 4. Display summary

The workflow shows a summary of changes made to your build configuration.

## What files can be modified

The workflow **only commits changes to build configuration files**. The workflow never changes your source code or test files.

Build configuration files that may be committed:

<Tabs>
  <Tab title="Java">
    * `pom.xml` (Maven projects)
    * `build.gradle` / `build.gradle.kts` (Gradle projects)
    * `.gitignore` (to exclude generated files)
  </Tab>

  <Tab title="Python">
    * `pyproject.toml`
    * `setup.py`
    * `requirements.txt` / `requirements-dev.txt`
    * `.gitignore` (to exclude virtual environments)
  </Tab>
</Tabs>

All changes are committed in a single commit with a descriptive message listing what was added or modified.

<Note>
  For Python projects, the workflow also creates or updates a `.venv` directory in your project root. The virtual environment files are not committed to git (they are excluded via `.gitignore`).
</Note>

## Dependencies that may be added

The workflow ensures your project has the minimum dependencies required for test generation:

<Tabs>
  <Tab title="Java">
    | Dependency | Purpose            |
    | ---------- | ------------------ |
    | JUnit      | Testing framework  |
    | Mockito    | Mocking library    |
    | JaCoCo     | Coverage reporting |
  </Tab>

  <Tab title="Python">
    | Dependency  | Purpose            |
    | ----------- | ------------------ |
    | pytest      | Testing framework  |
    | pytest-cov  | Coverage reporting |
    | pytest-mock | Mocking library    |

    The workflow also scans your existing test files for imports, decorators, and markers that indicate additional dependencies. Any detected dependencies are added to the dependency file and installed.
  </Tab>
</Tabs>

The workflow may upgrade existing dependencies, if necessary.

## Understanding the output

When the workflow completes, you see:

* **Build environment changes** — A list of modifications made (e.g., "Added JUnit 5.10.0", "Added JaCoCo Maven plugin")
* **A new commit** — The commit contains any modifications, with a descriptive message

If no changes were needed, the workflow completes with no modifications.

## After running the workflow

1. Review the commit to verify the changes are appropriate for your project.
2. If you need to adjust the changes, modify the build configuration files and amend the commit.

Your project environment is now configured for test generation.

## Next steps

* Run the [planning workflow](/workflows/regression-unit-tests-planning) to measure coverage and preview resource estimates
* Run the [regression unit test generation](/workflows/regression-unit-tests) workflow to generate tests

## Troubleshooting

* **Git repository check fails**: Ensure you are running the command from a git repository. Initialize one with `git init` if needed.
* **Build system detection fails**: Verify you have a valid `pom.xml`, `build.gradle`, or `pyproject.toml` file in your project root or module directories.
* **Changes not applied**: Check that you don't have uncommitted changes that conflict with the build configuration files. Commit or stash your changes before running the workflow.
* See the [troubleshooting](/troubleshooting) page for more common issues.