Skip to content

Commit 5b4c642

Browse files
kdubbsbrannen
kdubb
authored and
sbrannen
committed
Introduce TestInstanceFactory extension API
This commit introduces a new TestInstanceFactory extension API that allows for custom creation of test instances. - TestInstanceFactory must be applied at the class level. - If multiple TestInstanceFactory extensions are registered on a single test class, an exception is thrown. - TestInstanceFactory may also be used with @nested test classes, in which case only one TestInstanceFactory is registered on each level. Issue: #672
1 parent 38e149f commit 5b4c642

File tree

10 files changed

+514
-7
lines changed

10 files changed

+514
-7
lines changed

‎documentation/src/docs/asciidoc/link-attributes.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ endif::[]
6868
:RepetitionInfo: {javadoc-root}/org/junit/jupiter/api/RepetitionInfo.html[RepetitionInfo]
6969
:TestExecutionExceptionHandler: {javadoc-root}/org/junit/jupiter/api/extension/TestExecutionExceptionHandler.html[TestExecutionExceptionHandler]
7070
:TestInfo: {javadoc-root}/org/junit/jupiter/api/TestInfo.html[TestInfo]
71+
:TestInstanceFactory: {javadoc-root}/org/junit/jupiter/api/extension/TestInstanceFactory.html[TestInstanceFactory]
7172
:TestInstancePostProcessor: {javadoc-root}/org/junit/jupiter/api/extension/TestInstancePostProcessor.html[TestInstancePostProcessor]
7273
:TestReporter: {javadoc-root}/org/junit/jupiter/api/TestReporter.html[TestReporter]
7374
:TestTemplate: {javadoc-root}/org/junit/jupiter/api/TestTemplate.html[@TestTemplate]

‎documentation/src/docs/asciidoc/release-notes/release-notes-5.3.0-M1.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ on GitHub.
4848
parallel test execution based on the Fork/Join Framework.
4949
- `Node` implementations may provide a set of `ExclusiveResources` and an
5050
`ExecutionMode` to be used by `ForkJoinPoolHierarchicalTestExecutorService`.
51+
* New extension interface `TestInstanceFactory` that allows extensions to provide
52+
specially created or acquired test instances.
5153
* New overloaded variant of `isAnnotated()` in `AnnotationSupport` that accepts
5254
`Optional<? extends AnnotatedElement>` instead of `AnnotatedElement`.
5355
* New `--fail-if-no-tests` command-line option for the `ConsoleLauncher`.

‎documentation/src/docs/asciidoc/user-guide/extensions.adoc

+20
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,26 @@ Examples:
241241
- `org.example.MyCondition`: deactivates the condition whose FQCN is exactly
242242
`org.example.MyCondition`.
243243

244+
[[extensions-test-instance-factories]]
245+
=== Test Instance Factories
246+
`{TestInstanceFactory}` defines the API for `Extensions` that wish to _provide new_
247+
test instances.
248+
249+
Common use cases include acquiring the test instance from a dependency injection
250+
framework or invoking a static factory method to create the test instance.
251+
252+
A single extension that implements `{TestInstanceFactory}` can be registered for
253+
test classes at the top level and each nested test class. Factories registered on
254+
a nested test class will override that of factories at higher levels.
255+
256+
[WARNING]
257+
====
258+
Registering multiple extensions that implement `{TestInstanceFactory}` for any single class
259+
in the test class hierarchy will result in an exception being thrown for all tests in that
260+
class and any nested test classes below. It is the user's responsibility to ensure that only
261+
a single `{TestInstanceFactory}` is registered for any specific test class.
262+
====
263+
244264
[[extensions-test-instance-post-processing]]
245265
=== Test Instance Post-processing
246266

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstanceFactory.java

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
/*
2+
* Copyright 2015-2018 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* http://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.jupiter.api.extension;
12+
13+
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
14+
15+
import org.apiguardian.api.API;
16+
17+
/**
18+
* {@code TestInstanceFactory} defines the API for {@link Extension
19+
* Extensions} that wish to <em>create</em> test instances.
20+
*
21+
* <p>Common use cases include creating test instances with special construction
22+
* requirements or acquiring the test from a dependency injection framework.
23+
*
24+
* <p>Only one {@code TestInstanceFactory} is allowed to be registered for each
25+
* test class in the test class hierarchy; with lower level factories overriding
26+
* factories registered at higher levels in the hierarchy. Registering multiple
27+
* factories for any single test class will result in an exception being thrown
28+
* for all the tests in that test class and any nested test classes below.
29+
*
30+
* <p>Extensions that implement {@code TestInstanceFactory} must be registered
31+
* at the class level.
32+
*
33+
* <h3>Constructor Requirements</h3>
34+
*
35+
* <p>Consult the documentation in {@link Extension} for details on
36+
* constructor requirements.
37+
*
38+
* @since 5.3
39+
* @see TestInstanceFactoryContext
40+
* @see #instantiateTestClass(TestInstanceFactoryContext, ExtensionContext)
41+
*/
42+
@API(status = EXPERIMENTAL, since = "5.3")
43+
public interface TestInstanceFactory extends Extension {
44+
45+
/**
46+
* Callback for producing a test instance for the supplied context.
47+
*
48+
* <p><strong>Note</strong>: the {@code ExtensionContext} supplied to a
49+
* {@code TestInstanceFactory} will always return an empty
50+
* {@link java.util.Optional} value from
51+
* {@link ExtensionContext#getTestInstance() getTestInstance()}. A
52+
* {@code TestInstanceFactory} should therefore only attempt to create the
53+
* required test instance.
54+
*
55+
* @param factoryContext the context for the test class to be instantiated;
56+
* never {@code null}
57+
* @param extensionContext the current extension context; never {@code null}
58+
* @return the required test instance; never {@code null}
59+
* @throws TestInstantiationException when an error occurs with the
60+
* invocation of a factory
61+
*/
62+
Object instantiateTestClass(TestInstanceFactoryContext factoryContext, ExtensionContext extensionContext)
63+
throws TestInstantiationException;
64+
65+
}

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstanceFactoryContext.java

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/*
2+
* Copyright 2015-2018 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* http://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.jupiter.api.extension;
12+
13+
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
14+
15+
import java.util.Optional;
16+
17+
import org.apiguardian.api.API;
18+
import org.junit.jupiter.api.Nested;
19+
20+
/**
21+
* {@code TestInstanceFactoryContext} encapsulates the <em>context</em> in which
22+
* a {@link #getTestClass test class} is to be instantiated by a
23+
* {@link TestInstanceFactory}.
24+
*
25+
* @since 5.3
26+
* @see TestInstanceFactory
27+
*/
28+
@API(status = EXPERIMENTAL, since = "5.3")
29+
public interface TestInstanceFactoryContext {
30+
31+
/**
32+
* Get the test class for this context.
33+
*
34+
* @return the test class to be instantiated; never {@code null}
35+
*/
36+
Class<?> getTestClass();
37+
38+
/**
39+
* Get the outer class instance for {@link Nested nested} test classes. For
40+
* top level classes there is not outer instance and as such the value will
41+
* be {@link Optional#empty empty}.
42+
*
43+
* @return the outer test class instance, if test class is nested
44+
* @see org.junit.jupiter.api.Nested
45+
*/
46+
Optional<Object> getOuterInstance();
47+
48+
}

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstantiationException.java

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/*
2+
* Copyright 2015-2018 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* http://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.jupiter.api.extension;
12+
13+
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
14+
15+
import org.apiguardian.api.API;
16+
import org.junit.platform.commons.JUnitException;
17+
18+
/**
19+
* Thrown if an error is encountered with the invocation of
20+
* any {@link TestInstanceFactory}.
21+
*
22+
* @since 5.3
23+
*/
24+
@API(status = EXPERIMENTAL, since = "5.3")
25+
public class TestInstantiationException extends JUnitException {
26+
27+
private static final long serialVersionUID = 1L;
28+
29+
public TestInstantiationException(String message) {
30+
super(message);
31+
}
32+
33+
public TestInstantiationException(String message, Throwable cause) {
34+
super(message, cause);
35+
}
36+
37+
}

‎junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/ClassTestDescriptor.java

+57-3
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,21 @@
2828
import java.util.Optional;
2929
import java.util.Set;
3030
import java.util.function.Function;
31+
import java.util.stream.Collectors;
3132

3233
import org.apiguardian.api.API;
3334
import org.junit.jupiter.api.TestInstance.Lifecycle;
3435
import org.junit.jupiter.api.extension.AfterAllCallback;
3536
import org.junit.jupiter.api.extension.BeforeAllCallback;
3637
import org.junit.jupiter.api.extension.Extension;
3738
import org.junit.jupiter.api.extension.ExtensionContext;
39+
import org.junit.jupiter.api.extension.ExtensionContextException;
40+
import org.junit.jupiter.api.extension.TestInstanceFactory;
41+
import org.junit.jupiter.api.extension.TestInstanceFactoryContext;
3842
import org.junit.jupiter.api.extension.TestInstancePostProcessor;
3943
import org.junit.jupiter.engine.execution.AfterEachMethodAdapter;
4044
import org.junit.jupiter.engine.execution.BeforeEachMethodAdapter;
45+
import org.junit.jupiter.engine.execution.DefaultTestInstanceFactoryContext;
4146
import org.junit.jupiter.engine.execution.ExecutableInvoker;
4247
import org.junit.jupiter.engine.execution.JupiterEngineExecutionContext;
4348
import org.junit.jupiter.engine.execution.TestInstanceProvider;
@@ -235,11 +240,60 @@ private Object instantiateAndPostProcessTestInstance(JupiterEngineExecutionConte
235240
return instance;
236241
}
237242

243+
protected Object invokeTestInstanceConstructor(Optional<Object> outerInstance, ExtensionRegistry registry,
244+
ExtensionContext extensionContext) {
245+
Constructor<?> constructor = ReflectionUtils.getDeclaredConstructor(this.testClass);
246+
if (outerInstance.isPresent()) {
247+
return executableInvoker.invoke(constructor, outerInstance.get(), extensionContext, registry);
248+
}
249+
else {
250+
return executableInvoker.invoke(constructor, extensionContext, registry);
251+
}
252+
}
253+
254+
protected TestInstanceFactory resolveTestInstanceFactory(ExtensionRegistry registry,
255+
ExtensionRegistry parentRegistry) {
256+
257+
List<TestInstanceFactory> factories = registry.getExtensions(TestInstanceFactory.class);
258+
if (factories.isEmpty()) {
259+
return null;
260+
}
261+
262+
if (parentRegistry != null) {
263+
List<TestInstanceFactory> parentFactories = parentRegistry.getExtensions(TestInstanceFactory.class);
264+
factories.removeAll(parentFactories);
265+
}
266+
267+
if (factories.size() > 1) {
268+
String factoryNames = factories.stream().map(factory -> factory.getClass().getSimpleName()).collect(
269+
Collectors.joining(","));
270+
271+
String errorMessage = String.format(
272+
"Too many TestInstanceFactory extensions [%s] registered on test class: %s (allowed is at most 1)",
273+
factoryNames, testClass.getSimpleName());
274+
275+
throw new ExtensionContextException(errorMessage);
276+
}
277+
278+
return factories.get(0);
279+
}
280+
281+
protected Object invokeTestInstanceFactory(Optional<Object> outerInstance, ExtensionRegistry registry,
282+
ExtensionRegistry parentRegistry, ExtensionContext extensionContext) {
283+
284+
TestInstanceFactory factory = resolveTestInstanceFactory(registry, parentRegistry);
285+
if (factory == null) {
286+
return invokeTestInstanceConstructor(outerInstance, registry, extensionContext);
287+
}
288+
289+
TestInstanceFactoryContext factoryContext = new DefaultTestInstanceFactoryContext(this.testClass,
290+
outerInstance);
291+
return factory.instantiateTestClass(factoryContext, extensionContext);
292+
}
293+
238294
protected Object instantiateTestClass(JupiterEngineExecutionContext parentExecutionContext,
239295
ExtensionRegistry registry, ExtensionContext extensionContext) {
240-
241-
Constructor<?> constructor = ReflectionUtils.getDeclaredConstructor(this.testClass);
242-
return executableInvoker.invoke(constructor, extensionContext, registry);
296+
return invokeTestInstanceFactory(Optional.empty(), registry, null, extensionContext);
243297
}
244298

245299
private void invokeTestInstancePostProcessors(Object instance, ExtensionRegistry registry,

‎junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/NestedClassTestDescriptor.java

+2-4
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212

1313
import static org.apiguardian.api.API.Status.INTERNAL;
1414

15-
import java.lang.reflect.Constructor;
1615
import java.util.LinkedHashSet;
1716
import java.util.Optional;
1817
import java.util.Set;
@@ -22,7 +21,6 @@
2221
import org.junit.jupiter.engine.execution.ExecutableInvoker;
2322
import org.junit.jupiter.engine.execution.JupiterEngineExecutionContext;
2423
import org.junit.jupiter.engine.extension.ExtensionRegistry;
25-
import org.junit.platform.commons.util.ReflectionUtils;
2624
import org.junit.platform.engine.TestDescriptor;
2725
import org.junit.platform.engine.TestTag;
2826
import org.junit.platform.engine.UniqueId;
@@ -73,8 +71,8 @@ protected Object instantiateTestClass(JupiterEngineExecutionContext parentExecut
7371
Optional<ExtensionRegistry> childExtensionRegistryForOuterInstance = Optional.empty();
7472
Object outerInstance = parentExecutionContext.getTestInstanceProvider().getTestInstance(
7573
childExtensionRegistryForOuterInstance);
76-
Constructor<?> constructor = ReflectionUtils.getDeclaredConstructor(getTestClass());
77-
return executableInvoker.invoke(constructor, outerInstance, extensionContext, registry);
74+
ExtensionRegistry parentRegistry = parentExecutionContext.getExtensionRegistry();
75+
return invokeTestInstanceFactory(Optional.of(outerInstance), registry, parentRegistry, extensionContext);
7876
}
7977

8078
}

‎junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/execution/DefaultTestInstanceFactoryContext.java

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/*
2+
* Copyright 2015-2018 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* http://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.jupiter.engine.execution;
12+
13+
import java.util.Optional;
14+
15+
import org.junit.jupiter.api.extension.TestInstanceFactoryContext;
16+
17+
public class DefaultTestInstanceFactoryContext implements TestInstanceFactoryContext {
18+
19+
private final Class<?> testClass;
20+
private final Optional<Object> outerInstance;
21+
22+
public DefaultTestInstanceFactoryContext(Class<?> testClass, Optional<Object> outerInstance) {
23+
this.testClass = testClass;
24+
this.outerInstance = outerInstance;
25+
}
26+
27+
@Override
28+
public Class<?> getTestClass() {
29+
return testClass;
30+
}
31+
32+
@Override
33+
public Optional<Object> getOuterInstance() {
34+
return outerInstance;
35+
}
36+
37+
}

0 commit comments

Comments
 (0)