> For the complete documentation index, see [llms.txt](https://cover-docs.diffblue.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cover-docs.diffblue.com/features/cover-cli/writing-tests/merge-mode.md).

# Merge Mode

## Overview

Merge mode is an optional test generation approach where Diffblue Cover **merges generated tests into existing test classes** rather than creating separate test files. This provides a more natural integration with your existing test suite.

**Default Behavior (Separate Files):**

```
src/test/java/com/example/
├── MyServiceTest.java          (your manual tests)
└── MyServiceDiffblueTest.java  (Diffblue generated tests - separate file)
```

**With merge mode (`--merge` flag):**

```
src/test/java/com/example/
└── MyServiceTest.java          (your manual tests + generated tests merged together)
```

## Why Use Merge Mode?

Merge mode provides several benefits:

1. **Simpler Project Structure** - All tests for a class live in one file, with no separate `*DiffblueTest` files
2. **Easier Navigation** - Find and maintain tests in a single location alongside your manual tests
3. **Smarter Test Class Coverage Optimization** - Diffblue Cover considers your manual tests, then provides only the generated tests that add unique coverage. See [Test Coverage Optimizations](/features/cover-cli/writing-tests/test-coverage-optimizations.md) for details.

## Enabling Merge Mode

### CLI

To use merge mode with the CLI, add the `--merge` flag:

```bash
dcover create --merge
```

With `--merge`, the default class name template changes to `${CLASS_NAME}Test`. If your existing test classes use a different naming convention, you can override this with `--class-name-template`:

```bash
dcover create --merge --class-name-template='${CLASS_NAME}Tests'
```

See [Test naming](/features/cover-cli/writing-tests/test-naming.md) for all available template variables.

### IntelliJ Plugin

Merge mode is enabled by default in the IntelliJ plugin. However, the plugin uses `${CLASS_NAME}DiffblueTest` by default, which keeps generated tests in separate files.

To take advantage of merge mode, update the class name template in your plugin settings to match your existing test naming conventions (e.g., `${CLASS_NAME}Test`). This allows generated tests to merge into your existing test classes.

See [Test Naming](/features/cover-plugin/cover-plugin-settings/test-naming.md) for plugin settings details.

## Key Behavior Differences

| Aspect            | Default Behavior            | With `--merge`                  |
| ----------------- | --------------------------- | ------------------------------- |
| Test file naming  | `${CLASS_NAME}DiffblueTest` | `${CLASS_NAME}Test`             |
| Test placement    | Separate file               | Merged into existing test class |
| Existing tests    | Not touched                 | Preserved, new tests added      |
| Test updates      | File replaced               | Individual tests updated        |
| cover-annotations | Not required                | Required (v1.4.0+)              |

***

## Prerequisites

### cover-annotations Requirement

**When using `--merge`, the `cover-annotations` library version 1.4.0 or later is required.**

If the library is missing or outdated when using `--merge`, Diffblue Cover displays an error during environment checks and halts execution. This requirement does not apply when running without `--merge`.

{% tabs %}
{% tab title="Maven" %}
Add to your `pom.xml`:

```xml
<dependency>
    <groupId>com.diffblue.cover</groupId>
    <artifactId>cover-annotations</artifactId>
    <version>1.9.0</version>
    <scope>test</scope>
</dependency>
```

{% endtab %}

{% tab title="Gradle (Groovy)" %}
Add to your `build.gradle`:

```groovy
compileOnly 'com.diffblue.cover:cover-annotations:1.9.0'
testImplementation 'com.diffblue.cover:cover-annotations:1.9.0'
```

{% endtab %}

{% tab title="Gradle (Kotlin)" %}
Add to your `build.gradle.kts`:

```kotlin
compileOnly("com.diffblue.cover:cover-annotations:1.9.0")
testImplementation("com.diffblue.cover:cover-annotations:1.9.0")
```

{% endtab %}
{% endtabs %}

See [Cover Annotations](/features/cover-annotations.md) for more information about the annotations library.

***

## Troubleshooting

### R090: Failed to Merge Tests

When you see this error:

```
[R090] Failed to merge tests into test class

Failed to merge tests into test class for com.example.MyService.

To resolve this, you can:
- Add @WriteTestsTo("MyServiceDiffblueTest") annotation to MyService, or
- Run Diffblue Cover without the --merge flag

You can customize the annotation value to any valid Java class name.
```

**What R090 means:** Diffblue Cover attempted to merge generated tests into an existing test class, but the merge failed. This happens when:

* The existing test class has code that conflicts with the generated tests
* Tests fail validation after merging (compile errors, test failures)

#### Solution 1: Use dcover issues --prompt (Recommended)

Run `dcover issues --prompt` to get an AI-assistant-ready prompt that will help you apply the necessary annotations:

```bash
dcover issues --prompt
```

#### Solution 2: Use @WriteTestsTo Annotation

Add the `@WriteTestsTo` annotation to direct tests to a separate file:

```java
package com.example;

import com.diffblue.cover.annotations.WriteTestsTo;

@WriteTestsTo("MyServiceDiffblueTest")
public class MyService {
    // Tests will be written to MyServiceDiffblueTest.java
    // instead of merging into MyServiceTest.java
}
```

See [Test Organization Annotations](/features/cover-annotations/test-organization-annotations.md) for more details on `@WriteTestsTo`.

#### Solution 3: Remove --merge Flag

Run without `--merge` to use the default separate-file behavior:

```bash
dcover create
```

### Environment Check Failures

#### Missing or Outdated cover-annotations

**Error:** Diffblue Cover requires `cover-annotations` when using `--merge` and fails when the dependency is missing or below version 1.4.0.

**Solution:** Add or update the `cover-annotations` dependency (see Prerequisites section). Version 1.9.0 or later is recommended.

***

## Adopting Merge Mode

### From Existing \*DiffblueTest Files

If you have existing `*DiffblueTest` files and want to switch to merge mode:

1. **Remove existing Diffblue tests:**

   ```bash
   dcover remove
   ```
2. **Regenerate tests with merge mode:**

   ```bash
   dcover create --merge
   ```
3. **Review the merged tests** in your `*Test.java` files

### CI/CD Considerations

If you have CI/CD pipelines using Diffblue Cover and want to adopt merge mode:

1. Add `cover-annotations` 1.4.0+ to all build environments
2. Run `dcover remove` once to clean up existing `*DiffblueTest` files
3. Update `dcover create` commands to include `--merge` flag
4. Update any scripts that reference `*DiffblueTest` file patterns

***

## Known Limitations

### IntelliJ Plugin

* If merge fails in the plugin, you may receive tests with compilation errors that require manual resolution
* The plugin does not validate merged tests the same way the CLI does

### Cover Reports

Merge mode does not affect how Cover Reports attributes coverage. Diffblue Cover uses annotations (`@ManagedByDiffblue`, `@MethodsUnderTest`, `@Tag("ContributionFromDiffblue")`) to correctly identify generated tests regardless of file location.

***

## Related Topics

* [Test naming](/features/cover-cli/writing-tests/test-naming.md) - Class and method naming templates
* [Test Coverage Optimizations](/features/cover-cli/writing-tests/test-coverage-optimizations.md) - How merge mode enhances coverage optimization
* [Test Organization Annotations](/features/cover-annotations/test-organization-annotations.md) - @WriteTestsTo annotation details
* [Commands & Arguments](/features/cover-cli/commands-and-arguments.md) - Full CLI reference