Reintroduce support for @testinstance lifecycle

Issue: #419

Author: sbrannen

junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestInstance.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2015-2017 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package org.junit.jupiter.api;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * {@code @TestInstance} is a class-level annotation that is used to configure
+ * the {@linkplain Lifecycle lifecycle} of test instances for the annotated
+ * test class.
+ *
+ * <p>If {@code @TestInstance} is not declared on a test class, the lifecycle
+ * mode will default to {@link Lifecycle#PER_METHOD PER_METHOD}.
+ *
+ * @author Sam Brannen
+ * @since 5.0
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface TestInstance {
+
+	/**
+	 * Enumeration of test instance lifecycle <em>modes</em>.
+	 */
+	enum Lifecycle {
+
+		/**
+		 * When using this mode, a new test instance will be created once per test class.
+		 *
+		 * @see #PER_METHOD
+		 */
+		PER_CLASS,
+
+		/**
+		 * When using this mode, a new test instance will be created for each test method
+		 * or test factory method.
+		 *
+		 * <p>This mode is analogous to the behavior found in JUnit versions 1 through 4.
+		 *
+		 * @see #PER_CLASS
+		 */
+		PER_METHOD;
+
+	}
+
+	/**
+	 * The test instance lifecycle <em>mode</em> to use.
+	 */
+	Lifecycle value();
+
+}

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

@@ -21,9 +21,12 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 import java.util.function.Function;
 
+import org.junit.jupiter.api.TestInstance;
+import org.junit.jupiter.api.TestInstance.Lifecycle;
 import org.junit.jupiter.api.extension.AfterAllCallback;
 import org.junit.jupiter.api.extension.BeforeAllCallback;
 import org.junit.jupiter.api.extension.ContainerExtensionContext;
@@ -40,6 +43,7 @@
 import org.junit.jupiter.engine.extension.ExtensionRegistry;
 import org.junit.platform.commons.JUnitException;
 import org.junit.platform.commons.meta.API;
+import org.junit.platform.commons.util.AnnotationUtils;
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.commons.util.ReflectionUtils;
 import org.junit.platform.engine.TestDescriptor;
@@ -172,13 +176,8 @@ public void after(JupiterEngineExecutionContext context) throws Exception {
 
 	protected TestInstanceProvider testInstanceProvider(JupiterEngineExecutionContext parentExecutionContext,
 			ExtensionRegistry registry, ExtensionContext extensionContext) {
-		return childExtensionRegistry -> {
-			Constructor<?> constructor = ReflectionUtils.getDeclaredConstructor(this.testClass);
-			Object instance = executableInvoker.invoke(constructor, extensionContext,
-				childExtensionRegistry.orElse(registry));
-			invokeTestInstancePostProcessors(instance, childExtensionRegistry.orElse(registry), extensionContext);
-			return instance;
-		};
+
+		return new LifecycleAwareTestInstanceProvider(this.testClass, registry, extensionContext);
 	}
 
 	protected void invokeTestInstancePostProcessors(Object instance, ExtensionRegistry registry,
@@ -272,4 +271,53 @@ private void invokeMethodInTestExtensionContext(Method method, TestExtensionCont
 		executableInvoker.invoke(method, instance, context, registry);
 	}
 
+	private final class LifecycleAwareTestInstanceProvider implements TestInstanceProvider {
+
+		private final Class<?> testClass;
+		private final Lifecycle lifecycle;
+		private final ExtensionRegistry registry;
+		private final ExtensionContext extensionContext;
+		private Object testInstance;
+
+		LifecycleAwareTestInstanceProvider(Class<?> testClass, ExtensionRegistry registry,
+				ExtensionContext extensionContext) {
+
+			this.testClass = testClass;
+			this.lifecycle = getInstanceLifecycle(testClass);
+			this.registry = registry;
+			this.extensionContext = extensionContext;
+		}
+
+		@Override
+		public Object getTestInstance(Optional<ExtensionRegistry> childExtensionRegistry) throws Exception {
+			if (this.lifecycle == Lifecycle.PER_METHOD) {
+				return createTestInstance(childExtensionRegistry);
+			}
+
+			// else Lifecycle.PER_CLASS
+			if (this.testInstance == null) {
+				this.testInstance = createTestInstance(childExtensionRegistry);
+			}
+			return this.testInstance;
+		}
+
+		private Object createTestInstance(Optional<ExtensionRegistry> childExtensionRegistry) {
+			Constructor<?> constructor = ReflectionUtils.getDeclaredConstructor(this.testClass);
+			Object instance = executableInvoker.invoke(constructor, this.extensionContext,
+				childExtensionRegistry.orElse(this.registry));
+			invokeTestInstancePostProcessors(instance, childExtensionRegistry.orElse(this.registry),
+				this.extensionContext);
+			return instance;
+		}
+
+		private TestInstance.Lifecycle getInstanceLifecycle(Class<?> testClass) {
+			// @formatter:off
+			return AnnotationUtils.findAnnotation(testClass, TestInstance.class)
+					.map(TestInstance::value)
+					.orElse(Lifecycle.PER_METHOD);
+			// @formatter:on
+		}
+
+	}
+
 }

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

@@ -60,8 +60,9 @@ public final Set<TestTag> getTags() {
 	@Override
 	protected TestInstanceProvider testInstanceProvider(JupiterEngineExecutionContext parentExecutionContext,
 			ExtensionRegistry registry, ExtensionContext extensionContext) {
+
 		return childExtensionRegistry -> {
-			// Extensions registered for nested classes and below are not to be used for instancing outer classes
+			// Extensions registered for nested classes and below are not to be used for instantiating outer classes
 			Optional<ExtensionRegistry> childExtensionRegistryForOuterInstance = Optional.empty();
 			Object outerInstance = parentExecutionContext.getTestInstanceProvider().getTestInstance(
 				childExtensionRegistryForOuterInstance);

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/TestInstanceLifecycleTests.java

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2015-2017 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package org.junit.jupiter.engine;
+
+import static org.junit.jupiter.api.Assertions.assertAll;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestInstance;
+import org.junit.jupiter.api.TestInstance.Lifecycle;
+import org.junit.platform.engine.test.event.ExecutionEventRecorder;
+import org.junit.platform.runner.JUnitPlatform;
+import org.junit.runner.RunWith;
+
+/**
+ * Tests for {@link TestInstance @TestInstance} lifecycle support.
+ *
+ * @since 5.0
+ */
+@RunWith(JUnitPlatform.class)
+public
+
+class TestInstanceLifecycleTests extends AbstractJupiterTestEngineTests {
+
+	private static int instanceCount;
+	private static int beforeCount;
+	private static int afterCount;
+
+	@BeforeEach
+	void init() {
+		instanceCount = 0;
+		beforeCount = 0;
+		afterCount = 0;
+	}
+
+	@Test
+	void instancePerMethod() {
+		performAssertions(InstancePerMethodTestCase.class, 2);
+	}
+
+	@Test
+	void instancePerClass() {
+		performAssertions(InstancePerClassTestCase.class, 1);
+	}
+
+	private void performAssertions(Class<?> testClass, int expectedInstanceCount) {
+		ExecutionEventRecorder eventRecorder = executeTestsForClass(testClass);
+
+		// @formatter:off
+		assertAll(
+			() -> assertEquals(expectedInstanceCount, instanceCount, "instance count"),
+			() -> assertEquals(2, eventRecorder.getContainerStartedCount(), "# containers started"),
+			() -> assertEquals(2, eventRecorder.getContainerFinishedCount(), "# containers finished"),
+			() -> assertEquals(2, eventRecorder.getTestStartedCount(), "# tests started"),
+			() -> assertEquals(2, eventRecorder.getTestSuccessfulCount(), "# tests succeeded"),
+			() -> assertEquals(2, beforeCount, "# before calls"),
+			() -> assertEquals(2, afterCount, "# after calls")
+		);
+		// @formatter:on
+	}
+
+	// The following is commented out b/c it's the default.
+	// @TestInstance(Lifecycle.PER_METHOD)
+	private static class InstancePerMethodTestCase {
+
+		InstancePerMethodTestCase() {
+			instanceCount++;
+		}
+
+		@BeforeEach
+		void before() {
+			beforeCount++;
+		}
+
+		@AfterEach
+		void after() {
+			afterCount++;
+		}
+
+		@Test
+		void test1() {
+		}
+
+		@Test
+		void test2() {
+		}
+
+	}
+
+	@TestInstance(Lifecycle.PER_CLASS)
+	private static class InstancePerClassTestCase extends InstancePerMethodTestCase {
+	}
+
+}