Class InstancioExtension

java.lang.Object

org.instancio.junit.InstancioExtension

All Implemented Interfaces:

org.junit.jupiter.api.extension.AfterEachCallback, org.junit.jupiter.api.extension.AfterTestExecutionCallback, org.junit.jupiter.api.extension.BeforeEachCallback, org.junit.jupiter.api.extension.Extension, org.junit.jupiter.api.extension.ParameterResolver, org.junit.jupiter.api.extension.TestInstantiationAwareExtension

public class InstancioExtension
extends Object
implements org.junit.jupiter.api.extension.BeforeEachCallback, org.junit.jupiter.api.extension.AfterEachCallback, org.junit.jupiter.api.extension.AfterTestExecutionCallback, org.junit.jupiter.api.extension.ParameterResolver

The Instancio JUnit extension adds support for additional features when using Instancio with the JUnit framework:

• reporting the seed value to allow reproducing failed tests
• injecting Settings using @WithSettings annotation
• injecting fields and method parameters using @Given annotation

Reproducing failed tests

The extension generates a seed for each test method. When a test fails, the extension reports this seed in the output. Using the @Seed annotation, the test can be re-run with the reported seed to reproduce the data that caused the failure.

For example, given the following test class:

@ExtendWith(InstancioExtension.class)
class ExampleTest {

    @Test
    void verifyPerson() {
        Person person = Instancio.create(Person.class);
        // some test code...
        // ... some assertion fails
    }
}

Once all tests have been executed, the seed values of the failed tests are reported as a summary, for example:

1 test failed. A failure can be reproduced by annotating the test method with @Seed:

  @Seed(12345L) ExampleTest.verifyPerson (seed source: random seed)

The seed of each failed test is also published as a JUnit report entry, which is displayed by IDEs and included in XML test reports.

Subsequently, the failing test can be reproduced by annotating the test method with the Seed annotation:

@Test
@Seed(12345) // will reproduce previously generated data
void verifyPerson() {
    Person person = Instancio.create(Person.class);
    // snip...
}

See the user guide for more details.

Since:

1.1.0

Nested Class Summary

Nested classes/interfaces inherited from interface org.junit.jupiter.api.extension.TestInstantiationAwareExtension

org.junit.jupiter.api.extension.TestInstantiationAwareExtension.ExtensionContextScope

Constructor Summary

Constructors

Constructor	Description
InstancioExtension()	Default constructor; required for JUnit extensions.

Method Summary

Modifier and Type	Method	Description
void	afterEach(org.junit.jupiter.api.extension.ExtensionContext context)
void	afterTestExecution(org.junit.jupiter.api.extension.ExtensionContext context)
void	beforeEach(org.junit.jupiter.api.extension.ExtensionContext context)
org.junit.jupiter.api.extension.TestInstantiationAwareExtension.ExtensionContextScope	getTestInstantiationExtensionContextScope(org.junit.jupiter.api.extension.ExtensionContext rootContext)	Opting in to the test-method scope is recommended by JUnit for forward compatibility, as it is due to become the default behaviour.
Object	resolveParameter(org.junit.jupiter.api.extension.ParameterContext parameterContext, org.junit.jupiter.api.extension.ExtensionContext extensionContext)
boolean	supportsParameter(org.junit.jupiter.api.extension.ParameterContext parameterContext, org.junit.jupiter.api.extension.ExtensionContext extensionContext)	For methods, JUnit invokes (1) beforeEach(), (2) resolveParameter() For constructors, the order is reverse.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

InstancioExtension

public InstancioExtension()

Default constructor; required for JUnit extensions.

Method Details

getTestInstantiationExtensionContextScope

public org.junit.jupiter.api.extension.TestInstantiationAwareExtension.ExtensionContextScope getTestInstantiationExtensionContextScope(org.junit.jupiter.api.extension.ExtensionContext rootContext)

Opting in to the test-method scope is recommended by JUnit for forward compatibility, as it is due to become the default behaviour.

Specified by:

getTestInstantiationExtensionContextScope in interface org.junit.jupiter.api.extension.TestInstantiationAwareExtension

beforeEach

public void beforeEach(org.junit.jupiter.api.extension.ExtensionContext context)
                throws IllegalAccessException

Specified by:

beforeEach in interface org.junit.jupiter.api.extension.BeforeEachCallback

Throws:

IllegalAccessException

afterEach

public void afterEach(org.junit.jupiter.api.extension.ExtensionContext context)

Specified by:

afterEach in interface org.junit.jupiter.api.extension.AfterEachCallback

afterTestExecution

public void afterTestExecution(org.junit.jupiter.api.extension.ExtensionContext context)

Specified by:

afterTestExecution in interface org.junit.jupiter.api.extension.AfterTestExecutionCallback

supportsParameter

public boolean supportsParameter(org.junit.jupiter.api.extension.ParameterContext parameterContext,
 org.junit.jupiter.api.extension.ExtensionContext extensionContext)

For methods, JUnit invokes (1) beforeEach(), (2) resolveParameter() For constructors, the order is reverse. As a result, when resolveParameter() is called, the setup logic hasn't been run yet. For this reason, constructor parameters are not supported.

Specified by:

supportsParameter in interface org.junit.jupiter.api.extension.ParameterResolver

resolveParameter

public Object resolveParameter(org.junit.jupiter.api.extension.ParameterContext parameterContext,
 org.junit.jupiter.api.extension.ExtensionContext extensionContext)

Specified by:

resolveParameter in interface org.junit.jupiter.api.extension.ParameterResolver