Merge Mode

Merge mode enables Diffblue Cover to merge generated tests into existing test classes rather than creating separate files.

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

Enabling Merge Mode

CLI

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

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:

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

See Test naming 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 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.

Maven

Add to your pom.xml:

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

Gradle (Groovy)

Add to your build.gradle:

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

Gradle (Kotlin)

Add to your build.gradle.kts:

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

See Cover Annotations 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:

dcover issues --prompt

Solution 2: Use @WriteTestsTo Annotation

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

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 for more details on @WriteTestsTo.

Solution 3: Remove --merge Flag

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

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:

   dcover remove

2. Regenerate tests with merge mode:

   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 - Class and method naming templates

• Test Coverage Optimizations - How merge mode enhances coverage optimization

• Test Organization Annotations - @WriteTestsTo annotation details

• Commands & Arguments - Full CLI reference