# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cover-docs-preview.diffblue.com/features/cover-cli/writing-tests/merge-mode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.