Package org.assertj.core.api.junit.jupiter

Class SoftAssertionsExtension

java.lang.Object

org.assertj.core.api.junit.jupiter.SoftAssertionsExtension

All Implemented Interfaces:

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.TestInstancePostProcessor, org.junit.jupiter.api.extension.TestInstantiationAwareExtension

public class SoftAssertionsExtension
extends Object
implements org.junit.jupiter.api.extension.TestInstancePostProcessor, org.junit.jupiter.api.extension.BeforeEachCallback, org.junit.jupiter.api.extension.ParameterResolver, org.junit.jupiter.api.extension.AfterTestExecutionCallback

Extension for JUnit Jupiter that provides support for injecting a concrete implementation of SoftAssertionsProvider into test methods and (since 3.18.0) into test fields annotated with @InjectSoftAssertions.

Two examples of SoftAssertionsProviders that come packaged with AssertJ are SoftAssertions and BDDSoftAssertions, but custom implementations are also supported as long as they are non-abstract and have a default constructor.

Applicability

In this context, the term "test method" refers to any method annotated with @Test, @RepeatedTest, @ParameterizedTest, @TestFactory, or @TestTemplate.
This extension does not inject SoftAssertionsProvider arguments into test constructors or lifecycle methods.

Scope

Annotated SoftAssertionsProvider fields become valid from the `@BeforeEach` lifecycle phase. For parameters, they become valid when the parameter is resolved.
In the afterTestExecution phase (immediately after the test has returned, but before the AfterEach phase) all collected errors (if any) will be wrapped in a single multiple-failures error.
All SoftAssertionsProvider instances (fields & parameters) created within the scope of the same test method (including its BeforeEach phase) will share the same state object to collect the failed assertions, so that all assertion failures from all SoftAssertionsProviders will be reported in the order that they failed.

Integration with third-party extensions

Sometimes a third-party extension may wish to softly assert something as part of the main test. Or sometimes a third-party extension may be a wrapper around another assertion library (eg, Mockito) and it would be nice for that library's soft assertions to mix well with AssertJ's. This can be achieved through the use of the SoftAssertionExtension's API. Calling getAssertionErrorCollector(ExtensionContext) will return a handle to the error collector used for the current context into which a third-party extension can directly store its assertion failures. Alternatively, calling getSoftAssertionsProvider() will instantiate a SoftAssertionsProvider for the given context that can then be used to make assertions.

Examples

Example parameter injection

  @ExtendWith(SoftAssertionsExtension.class)
 class ExampleTestCase {

    @InjectSoftAssertions
    BDDSoftAssertions bdd;

    @Test
    void multipleFailures(SoftAssertions softly) {
       softly.assertThat(2 * 3).isEqualTo(0);
       softly.assertThat(Arrays.asList(1, 2)).containsOnly(1);
       softly.assertThat(1 + 1).isEqualTo(2);
    }
 }
 

Example field injection

 @ExtendWith(SoftlyExtension.class)
 public class SoftlyExtensionExample {

   // initialized by the SoftlyExtension extension
   @InjectSoftAssertions
   private SoftAssertions soft;

   @Test
   public void chained_soft_assertions_example() {
     String name = "Michael Jordan - Bulls";
     soft.assertThat(name)
         .startsWith("Mi")
         .contains("Bulls");
     // no need to call softly.assertAll(), this is done by the extension
   }

   // nested classes test work too
   @Nested
   class NestedExample {

     @Test
     public void football_assertions_example() {
       String kylian = "Kylian Mbappé";
       soft.assertThat(kylian)
           .startsWith("Ky")
           .contains("bap");
       // no need to call softly.assertAll(), this is done by the extension
     }
   }
 } 

Example using a mix of field and parameter injection

  @ExtendWith(SoftAssertionsExtension.class)
 class ExampleTestCase {

    @InjectSoftAssertions
    SoftAssertions softly

    @Test
    void multipleFailures(BDDSoftAssertions bdd) {
       bdd.then(2 * 3).isEqualTo(0);
       softly.assertThat(Arrays.asList(1, 2)).containsOnly(1);
       bdd.then(1 + 1).isEqualTo(2);
       // When SoftAssertionsExtension calls assertAll(), the three
       // above failures above will be reported in-order.
    }
 }
 

Example third-party extension using SoftAssertionsExtension

 
 class ExampleTestCase implements BeforeEachCallback {

    @Override
    public void beforeEach(ExtensionContext context) {
      SoftAssertions softly = SoftAssertionsExtension
        .getSoftAssertionsProvider(context, SoftAssertions.class);
      softly.assertThat(false).isTrue();
      // When SoftAssertionsExtension calls assertAll(), the
      // above failure will be included in the list of reported failures.
    }
 }
 

Since:

3.13

Author:

Sam Brannen, Arthur Mita (author of SoftlyExtension), Fr Jeremy Krieg

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
SoftAssertionsExtension()

Method Summary

Modifier and Type	Method	Description
void	afterTestExecution(org.junit.jupiter.api.extension.ExtensionContext extensionContext)
void	beforeEach(org.junit.jupiter.api.extension.ExtensionContext context)
static AssertionErrorCollector	getAssertionErrorCollector(org.junit.jupiter.api.extension.ExtensionContext context)	Returns the AssertionErrorCollector for the given extension context, if none exists for the current context then one is created.
static <T extends SoftAssertionsProvider> T	getSoftAssertionsProvider(org.junit.jupiter.api.extension.ExtensionContext context, Class<T> concreteSoftAssertionsProviderType)	Returns a SoftAssertionsProvider instance of the given type for the given extension context.
void	postProcessTestInstance(Object testInstance, org.junit.jupiter.api.extension.ExtensionContext context)
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)

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.junit.jupiter.api.extension.TestInstantiationAwareExtension

getTestInstantiationExtensionContextScope

Constructor Details

SoftAssertionsExtension

public SoftAssertionsExtension()

Method Details

postProcessTestInstance

public void postProcessTestInstance(Object testInstance,
 org.junit.jupiter.api.extension.ExtensionContext context)
                             throws Exception

Specified by:

postProcessTestInstance in interface org.junit.jupiter.api.extension.TestInstancePostProcessor

Throws:

Exception

beforeEach

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

Specified by:

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

Throws:

Exception

supportsParameter

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

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

afterTestExecution

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

Specified by:

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

getAssertionErrorCollector

public static AssertionErrorCollector getAssertionErrorCollector(org.junit.jupiter.api.extension.ExtensionContext context)

Returns the AssertionErrorCollector for the given extension context, if none exists for the current context then one is created.

This method is thread safe - all extensions attempting to access the AssertionErrorCollector for a given context through this method will get a reference to the same AssertionErrorCollector instance, regardless of the order in which they are called.

Third-party extensions that wish to provide soft-asserting behavior can use this method to obtain the current AssertionErrorCollector instance and record their assertion failures into it by calling collectAssertionError(AssertionError).
In this way their soft assertions will integrate with the existing AssertJ soft assertions and the assertion failures (both AssertJ's and the third-party extension's) will be reported in the order that they occurred.

Parameters:

context - the ExtensionContext whose error collector we are attempting to retrieve.

Returns:

The AssertionErrorCollector for the given context.

getSoftAssertionsProvider

public static <T extends SoftAssertionsProvider> T getSoftAssertionsProvider(org.junit.jupiter.api.extension.ExtensionContext context,
 Class<T> concreteSoftAssertionsProviderType)

Returns a SoftAssertionsProvider instance of the given type for the given extension context. If no instance of the given type exists for the supplied context, then one is created.
Note that the given type must be a concrete type with an accessible no-arg constructor for this method to work.

This method is thread safe - all extensions attempting to access the SoftAssertionsProvider for a given context through this method will receive end up getting a reference to the same SoftAssertionsProvider instance of that same type, regardless of the order in which they are called.

Third party extensions that wish to use soft assertions in their own implementation can use this to get a SoftAssertionsProvider instance that interoperates with other soft-asserting extensions (including SoftAssertionsExtension).

The SoftAssertionExtension will take care of initialising this provider instance's delegate at the appropriate time, so that collected soft assertions are routed to the AssertionErrorCollector instance for the current context.

 public class CustomExtension implements BeforeEachCallback {

   @Override
   public void beforeEach(ExtensionContext context) {
     CustomSoftAssertions softly = SoftAssertionsExtension.getSoftAssertionsProvider(context, CustomSoftAssertions.class);
     softly.assertThat(1).isOne();
   }
 }
 

Type Parameters:

T - the type of SoftAssertionsProvider to instantiate.

Parameters:

context - the ExtensionContext whose error collector we are attempting to retrieve.

concreteSoftAssertionsProviderType - the class instance for the type of soft assertions

Returns:

The AssertionErrorCollector for the given context.