# Customizing test setup

By default, Diffblue Cover will write tests that are executed in isolation but it's possible to provide a custom base class with additional logic to run before / after the tests themselves.

## Background

A key feature of Diffblue Cover is automatically configuring classes such that the method under test can be successfully executed.

However, sometimes Diffblue Cover is unable to appropriately configure and clean up the environment such that tests can be usefully written and needs guidance from the user in the form of a custom base class which can provide behavior inherited by the test class.

## eLearning

{% embed url="<https://youtu.be/TJnx2xPlL_4?feature=shared>" %}

## Custom Base Class

When writing tests for `com.example.SomeClass` Diffblue Cover will look for the existence of `com.example.SomeClassDiffblueBase` and use that as a super-class when writing `com.example.SomeClassDiffblueTest`. This `com.example.SomeClassDiffblueBase` class can contain methods to be run before/after writing tests, correctly annotated according to the testing framework used. The base class needs to have the same name as the class under test, with a `DiffblueBase` suffix appended, it must be in the same package as the class under test, but likely should be defined in the `src/test/java` source tree so that it’s kept separate from production code.

Note that if you're creating tests with TestNG for a class that uses Spring, the custom base class feature **cannot** be used.

Given a class under test: `src/main/java/com/example/SomeClass.java`

```java
package com.example;

class SomeClass {
  void methodUnderTest() {
    // ...
  }
}
```

and a custom base class: `src/test/java/com/example/SomeClassDiffblueBase.java`

```java
package com.example;

class SomeClassDiffblueBase {

}
```

then Cover will write a test class `src/test/java/com/example/SomeClassDiffblueTest.java` extending that custom base class.

{% tabs %}
{% tab title="JUNIT 4" %}

```java
package com.example;

import org.junit.Test;

class SomeClassDiffblueTest extends SomeClassDiffblueBase {
  @Test
  void testMethodUnderTest() {
    // Arrange
    // ...

    // Act
    // ...

    // Assert
    // ...
  }
}
```

{% endtab %}

{% tab title="JUNIT JUPITER 5" %}

```java
package com.example;

import org.junit.jupiter.api.Test;

class SomeClassDiffblueTest extends SomeClassDiffblueBase {
  @Test
  void testMethodUnderTest() {
    // Arrange
    // ...

    // Act
    // ...

    // Assert
    // ...
  }
}
```

{% endtab %}

{% tab title="TESTNG" %}

```java
package com.example;

import org.testng.annotations.Test;

class SomeClassDiffblueTest extends SomeClassDiffblueBase {
  @Test
  void testMethodUnderTest() {
    // Arrange
    // ...

    // Act
    // ...

    // Assert
    // ...
  }
}
```

{% endtab %}
{% endtabs %}

**Note:** Once the custom base class has been written or updated, please make sure that it has been compiled so that Cover is able to find the compiled class.

## `@BeforeXXX` Annotated Methods

The most common use case for using a custom base class is to customize the test setup, often to perform some static initialization of some environmental state.

For example, your base class might need to switch to some test environment before tests are run at all, and might need to reset some license limits ahead of each test run.

If your class under test needs some shared environment state to be set up before tests are run at all, you can add a static, visible, no-argument method to your base class annotated with `org.junit.jupiter.api.BeforeAll` (or `org.junit.BeforeClass` if using JUnit 4, respectively `org.testng.annotations.BeforeClass` if using TestNG) performing that initialization logic.

If your methods under test need some state setup or reset before each test is run, you can add a non-static, visible, no-argument method to your base class annotated with `org.junit.jupiter.api.BeforeEach` (or `org.junit.Before` if using JUnit 4, respectively `org.testng.annotations.BeforeMethod` if using TestNG) performing that initialization logic.

For example, your base class might look like the following, with `setupTestEnvironment()` being called once before `SomeClassDiffblueTest`, and `resetLicenseLimits()` being called before each test method found:

{% tabs %}
{% tab title="JUNIT 4" %}

```java
package com.example;

import org.junit.BeforeClass;
import org.junit.Before;

class SomeClassDiffblueBase {

  @BeforeClass
  public static void setupTestEnvironment() {
    // custom static configuration
    Environment.state = new TestEnvironment();
  }

  @Before
  public void resetLicenseLimits() {
    // reset license limits
    Licensing.remainingUsages = 100;
  }
}
```

{% endtab %}

{% tab title="JUNIT JUPITER 5" %}

```java
package com.example;

import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;

class SomeClassDiffblueBase {

  @BeforeAll
  static void setupTestEnvironment() {
    // custom static configuration
    Environment.state = new TestEnvironment();
  }

  @BeforeEach
  void resetLicenseLimits() {
    // reset license limits
    Licensing.remainingUsages = 100;
  }
}
```

{% endtab %}

{% tab title="TESTNG" %}

```java
package com.example;

import org.testng.annotations.BeforeClass;
import org.testng.annotations.BeforeMethod;

class SomeClassDiffblueBase {

  @BeforeClass
  public void setupTestEnvironment() {
    // custom static configuration
    Environment.state = new TestEnvironment();
  }

  @BeforeMethod
  public void resetLicenseLimits() {
    // reset license limits
    Licensing.remainingUsages = 100;
  }
}
```

{% endtab %}
{% endtabs %}

## `@AfterXXX` Annotated Methods

A less common use case for a custom base class is to customize the test cleanup logic.

If your class under test needs some shared environment state to be cleared after tests are all run, you can add a static, visible, no-argument method to your base class annotated with `org.junit.jupiter.api.AfterAll` (or `org.junit.AfterClass` if using JUnit 4, respectively `org.testng.annotations.AfterClass` if using TestNG) performing that logic.

If your method under test needs some state reset after each test is run, you can add a non-static, visible, no-argument method to your base class annotated with `org.junit.jupiter.api.AfterEach` (or `org.junit.After` if using JUnit 4, respectively `org.testng.annotations.AfterMethod` if using TestNG) performing that logic.

For example, your base class might look like the following, with `resetLicenseUsageCount()` being called after each test in `SomeClassDiffblueTest` and then `resetTestEnvironment()` called after all the tests:

{% tabs %}
{% tab title="JUNIT 4" %}

```java
package com.example;

import org.junit.AfterClass;
import org.junit.After;

class SomeClassDiffblueBase {

  @AfterClass
  public static void resetTestEnvironment() {
    // clear test configuration
    Environment.state = null;
  }

  @After
  public void resetLicenseUsageCount() {
    // reset license limits
    Licensing.usageCount = 0;
  }
}
```

{% endtab %}

{% tab title="JUNIT JUPITER 5" %}

```java
package com.example;

import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.AfterEach;

class SomeClassDiffblueBase {

  @AfterAll
  static void resetTestEnvironment() {
    // clear test configuration
    Environment.state = null;
  }

  @AfterEach
  void resetLicenseUsageCount() {
    // reset license limits
    Licensing.usageCount = 0;
  }
}
```

{% endtab %}

{% tab title="TESTNG" %}

```java
package com.example;

import org.testng.annotations.AfterClass;
import org.testng.annotations.AfterMethod;

class SomeClassDiffblueBase {

  @AfterClass
  public void resetTestEnvironment() {
    // clear test configuration
    Environment.state = null;
  }

  @AfterMethod
  public void resetLicenseUsageCount() {
    // reset license limits
    Licensing.usageCount = 0;
  }
}
```

{% endtab %}
{% endtabs %}

## Field Inputs

Another use case for custom base classes is to provide initialized inputs that Cover would otherwise struggle to get right.

For example, perhaps your method under test requires some `ComplexObject` in order to execute, but it requires multiple calls to configure.

Note: Currently only static fields can be used.

Given a class under test: `src/main/java/com/example/SomeClass.java`

```java
package com.example;

class SomeClass {
  void methodUnderTest(ComplexObject complex) {
    // ...
  }
}
```

and a custom base class: `src/test/java/com/example/SomeClassDiffblueBase.java`

{% tabs %}
{% tab title="JUNIT 4" %}

```java
package com.example;

import org.junit.Before;

class SomeClassDiffblueBase {

  static ComplexObject complex;

  @Before
  public void resetTestEnvironment() {
    complex = ComplexObject.builder()
      .withName("For Unit Tests")
      .withSquareNumber(64)
      .build();
  }
}
```

{% endtab %}

{% tab title="JUNIT JUPITER 5" %}

```java
package com.example;

import org.junit.jupiter.api.BeforeEach;

class SomeClassDiffblueBase {

  static ComplexObject complex;

  @BeforeEach
  void resetTestEnvironment() {
    complex = ComplexObject.builder()
      .withName("For Unit Tests")
      .withSquareNumber(64)
      .build();
  }
}
```

{% endtab %}

{% tab title="TESTNG" %}

```java
package com.example;

import org.testng.annotations.BeforeMethod;

class SomeClassDiffblueBase {

  static ComplexObject complex;

  @BeforeMethod
  public void resetTestEnvironment() {
    complex = ComplexObject.builder()
      .withName("For Unit Tests")
      .withSquareNumber(64)
      .build();
  }
}
```

{% endtab %}
{% endtabs %}

Cover will use that initialized field to write the test class: `src/test/java/com/example/SomeClassDiffblueTest.java`

{% tabs %}
{% tab title="JUNIT" %}

```java
package com.example;

import org.junit.Test;

class SomeClassDiffblueTest extends SomeClassDiffblueBase {

  @Test
  public void testMethodUnderTest() {
    // Arrange
    SomeClass someClass = new SomeClass();

    // Act
    someClass.methodUnderTest(SomeClassDiffblueBase.complex);

    // Assert
    // ...
  }
}
```

{% endtab %}

{% tab title="JUNIT JUPITER 5" %}

```java
package com.example;

import org.junit.jupiter.api.Test;

class SomeClassDiffblueTest extends SomeClassDiffblueBase {

  @Test
  void testMethodUnderTest() {
    // Arrange
    SomeClass someClass = new SomeClass();

    // Act
    someClass.methodUnderTest(SomeClassDiffblueBase.complex);

    // Assert
    // ...
  }
}
```

{% endtab %}

{% tab title="TESTNG" %}

```java
package com.example;

import org.testng.annotations.Test;

class SomeClassDiffblueTest extends SomeClassDiffblueBase {

  @Test
  public void testMethodUnderTest() {
    // Arrange
    SomeClass someClass = new SomeClass();

    // Act
    someClass.methodUnderTest(SomeClassDiffblueBase.complex);

    // Assert
    // ...
  }
}
```

{% endtab %}
{% endtabs %}


---

# 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/custom-test-setup.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.