Document how to use `CloseableResource`

[sbrannen]

Overview

As discussed in the Gitter channel, users would greatly benefit from detailed documentation and examples regarding how to make use of CloseableResource in the ExtentionContext.Store.

Deliverables

• Document how to use CloseableResource in various scenarios, potentially via examples in the junit5-samples repository.

[vyarosh]

This is my use case: create html report object before all tests
and write to file after all tests executed:

import org.junit.jupiter.api.extension.BeforeAllCallback;
import org.junit.jupiter.api.extension.ExtensionContext;

public class AfterTestExecutionHook implements
        BeforeAllCallback {

    @Override
    public void beforeAll(ExtensionContext context) throws Exception {
        //initialize "after all test run hook"
        context.getRoot().getStore(ExtensionContext.Namespace.GLOBAL).put("my_report", new CloseableOnlyOnceResource());
    }

    private static class CloseableOnlyOnceResource implements
            ExtensionContext.Store.CloseableResource {
        //ReportManager contains static field of MyReport type as singleton storage and access point  
        private static MyReport htmlReport = ReportManager.createReportSingleton();

        @Override
        public void close() {
            //After all tests run hook.
            //Any additional desired action goes here 
            htmlReport.write();
        }
    }
}

usage:

@ExtendWith(AfterTestExecutionHook .class)
class AnotherClassDemo {

[sormuras]

Here is also a unit test showing a global resource:

junit5/platform-tests/src/test/java/org/junit/jupiter/extensions/Heavyweight.java

Lines 26 to 92 in 548de1f

	public class Heavyweight implements ParameterResolver, BeforeEachCallback {
	@Override
	public void beforeEach(ExtensionContext context) throws Exception {
	context.getStore(ExtensionContext.Namespace.GLOBAL).put("once", new CloseableOnlyOnceResource());
	}
	@Override
	public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext context) {
	return Resource.class.equals(parameterContext.getParameter().getType());
	}
	@Override
	public Object resolveParameter(ParameterContext parameterContext, ExtensionContext context) {
	ExtensionContext engineContext = context.getRoot();
	Store store = engineContext.getStore(ExtensionContext.Namespace.GLOBAL);
	ResourceValue resource = store.getOrComputeIfAbsent(ResourceValue.class);
	resource.usages.incrementAndGet();
	return resource;
	}
	interface Resource {
	String ID = "org.junit.jupiter.extensions.Heavyweight.Resource";
	int usages();
	}
	/**
	* Demo resource class.
	*
	* <p>The class implements interface {@link CloseableResource}
	* and interface {@link AutoCloseable} to show and ensure that a single
	* {@link ResourceValue#close()} method implementation is needed to comply
	* with both interfaces.
	*/
	private static class ResourceValue implements Resource, CloseableResource, AutoCloseable {
	private static final AtomicInteger creations = new AtomicInteger();
	private final AtomicInteger usages = new AtomicInteger();
	@SuppressWarnings("unused") // used via reflection
	ResourceValue() {
	// Open long-living resources here.
	assertEquals(1, creations.incrementAndGet(), "Singleton pattern failure!");
	}
	@Override
	public void close() {
	// Close resources here.
	assertEquals(9, usages.get(), "Usage counter mismatch!");
	}
	@Override
	public int usages() {
	return usages.get();
	}
	}
	private static class CloseableOnlyOnceResource implements CloseableResource {
	private final AtomicBoolean closed = new AtomicBoolean();
	@Override
	public void close() {
	assertTrue(closed.compareAndSet(false, true), "already closed!");
	}
	}

It is also a parameter resolver, so it can be injected into test methods:

junit5/platform-tests/src/test/java/org/junit/jupiter/extensions/HeavyweightAlphaTests.java

Lines 27 to 64 in 548de1f

	/**
	* Unit tests for {@link org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource}
	* stored values.
	*
	* @since 1.1
	*/
	@ExtendWith(Heavyweight.class)
	@ResourceLock(Heavyweight.Resource.ID)
	class HeavyweightAlphaTests {
	private static int mark;
	@BeforeAll
	static void setMark(Heavyweight.Resource resource) {
	assertTrue(resource.usages() > 0);
	mark = resource.usages();
	}
	@TestFactory
	Stream<DynamicTest> alpha1(Heavyweight.Resource resource) {
	return Stream.of(dynamicTest("foo", () -> assertTrue(resource.usages() > 1)));
	}
	@Test
	void alpha2(Heavyweight.Resource resource) {
	assertTrue(resource.usages() > 1);
	}
	@Test
	void alpha3(Heavyweight.Resource resource) {
	assertTrue(resource.usages() > 1);
	}
	@AfterAll
	static void checkMark(Heavyweight.Resource resource) {
	assertEquals(mark, resource.usages() - 4);
	}
	}

Mind the @ResourceLock(Heavyweight.Resource.ID) annotation. Global resources need synchronization guarding when Jupiter executes tests in parallel: https://junit.org/junit5/docs/snapshot/user-guide/#writing-tests-parallel-execution

[sbrannen]

Thanks for providing the examples, @sormuras.

With regard to the last point, @ResourceLock is unnecessary if the CloseableResource is itself thread-safe and designed for concurrent access -- right?

[sormuras]

With regard to the last point, @ResourceLock is unnecessary if the CloseableResource is itself thread-safe and designed for concurrent access -- right?

Absolutely! I'm preparing a new default extension which will provide a @Singleton annotation to support exactly those use cases.