Introduce SUITE, CLASS, and MANUAL lifecycle modes for @TestContainer annotation, replacing the previous boolean value.

SUITE-scoped containers are started once and shared across test classes,
CLASS-scoped containers follow the existing per-class behavior,
MANUAL-scoped containers are injected but never started/stopped by the framework.

Add TestcontainerLifecycle enum for container lifecycle scoping

Suite-scoped containers use @SuiteScoped registry created in BeforeSuite, while class-scoped containers use a fresh @ClassScoped registry per test class.
TestcontainerRegistryView routes lookups to the correct registry based on lifecycle value.

Resolves: #126

Signed-off-by: Radoslav Husar <rhusar@redhat.com>
Signed-off-by: Radoslav Husar <radosoft@gmail.com>

Author: rhusar

README.adoc

@@ -89,9 +89,33 @@ public class TypeSpecifiedInjectionTest {
 }
 ----
 
-By default, this extension will manage the lifecycle of each Testcontainer that is injected into the test. If you'd
-prefer to manage the lifecycle yourself, use the `value=true` attribute in the `@Testcontainer` annotation. For example
-use `@Testcontainer(false)`.
+=== Container Lifecycle
+
+By default, this extension manages the lifecycle of each Testcontainer per test class. The `@Testcontainer` annotation
+accepts a `TestcontainerLifecycle` value to control when containers are started and stopped:
+
+* `TestcontainerLifecycle.CLASS` (default) -- the container is started before each test class and stopped after it
+  completes.
+* `TestcontainerLifecycle.SUITE` -- the container is started once on first encounter and stopped when the test suite
+  ends. The same container instance is shared across all test classes that request the same type with suite lifecycle.
+  This is useful for expensive containers that do not need to be restarted between test classes.
+* `TestcontainerLifecycle.MANUAL` -- the container is created and injected but never started or stopped by the
+  framework. The user is responsible for managing the container lifecycle.
+
+[source,java]
+----
+// Suite-scoped container shared across test classes
+@Testcontainer(TestcontainerLifecycle.SUITE)
+private KeycloakContainer keycloak;
+
+// Class-scoped container (default behavior)
+@Testcontainer
+private SimpleTestContainer container;
+
+// Manually managed container
+@Testcontainer(TestcontainerLifecycle.MANUAL)
+private SimpleTestContainer manualContainer;
+----
 
 == Helpers
 

src/main/java/org/arquillian/testcontainers/ContainerInjectionTestEnricher.java

@@ -29,7 +29,7 @@
 @SuppressWarnings({ "unchecked" })
 public class ContainerInjectionTestEnricher implements TestEnricher {
     @Inject
-    private Instance<TestcontainerRegistry> instances;
+    private Instance<TestcontainerRegistryView> registries;
 
     @Override
     public void enrich(final Object testCase) {
@@ -60,7 +60,7 @@ public void enrich(final Object testCase) {
                     }
                 }
 
-                value = instances.get()
+                value = registries.get()
                         .lookupOrCreate((Class<GenericContainer<?>>) field.getType(), testcontainer, qualifiers);
             } catch (Exception e) {
                 throw new RuntimeException("Could not lookup value for field " + field, e);

src/main/java/org/arquillian/testcontainers/TestContainersObserver.java

@@ -7,6 +7,7 @@
 import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationTargetException;
 
+import org.arquillian.testcontainers.api.TestcontainerLifecycle;
 import org.arquillian.testcontainers.api.TestcontainersRequired;
 import org.jboss.arquillian.container.spi.ContainerRegistry;
 import org.jboss.arquillian.core.api.Instance;
@@ -15,26 +16,46 @@
 import org.jboss.arquillian.core.api.annotation.Observes;
 import org.jboss.arquillian.test.spi.TestClass;
 import org.jboss.arquillian.test.spi.annotation.ClassScoped;
+import org.jboss.arquillian.test.spi.annotation.SuiteScoped;
 import org.jboss.arquillian.test.spi.event.enrichment.AfterEnrichment;
 import org.jboss.arquillian.test.spi.event.suite.AfterClass;
+import org.jboss.arquillian.test.spi.event.suite.AfterSuite;
 import org.jboss.arquillian.test.spi.event.suite.BeforeClass;
+import org.jboss.arquillian.test.spi.event.suite.BeforeSuite;
 import org.testcontainers.DockerClientFactory;
 
 @SuppressWarnings("unused")
 class TestContainersObserver {
 
     private static final String NO_DOCKER_MSG = "No Docker/podman environment is available.";
 
+    @Inject
+    @SuiteScoped
+    private InstanceProducer<TestcontainerRegistry> suiteContainerRegistry;
+
     @Inject
     @ClassScoped
-    private InstanceProducer<TestcontainerRegistry> containerRegistry;
+    private InstanceProducer<TestcontainerRegistry> classContainerRegistry;
+
+    @Inject
+    @ClassScoped
+    private InstanceProducer<TestcontainerRegistryView> containerRegistries;
 
     @Inject
     private Instance<ContainerRegistry> registry;
 
+    /**
+     * Creates the suite-scoped {@link TestcontainerRegistry} once before the suite starts.
+     *
+     * @param beforeSuite the before suite event
+     */
+    public void createSuiteRegistry(@Observes BeforeSuite beforeSuite) {
+        suiteContainerRegistry.set(new TestcontainerRegistry());
+    }
+
     /**
      * This first checks if the {@link TestcontainersRequired} annotation is present on the test class failing if necessary. It
-     * then creates the {@link TestcontainerRegistry} and stores it in a {@link ClassScoped} instance.
+     * then creates the class-scoped {@link TestcontainerRegistry} and the combined {@link TestcontainerRegistryView}.
      *
      * @param beforeClass the before class event
      *
@@ -56,38 +77,68 @@ public void createContainer(@Observes(precedence = 500) BeforeClass beforeClass)
                 throw createException(throwable);
             }
         }
-        final TestcontainerRegistry instances = new TestcontainerRegistry();
-        containerRegistry.set(instances);
+
+        // Read suite registry before setting class registry — both InstanceProducers share the same generic type
+        // (TestcontainerRegistry), and .get() resolves hierarchically (most-specific scope wins), so a subsequent
+        // .get() on the suite producer would return the class-scoped value instead.
+        final TestcontainerRegistry suiteRegistry = suiteContainerRegistry.get();
+        final TestcontainerRegistry classRegistry = new TestcontainerRegistry();
+        classContainerRegistry.set(classRegistry);
+
+        containerRegistries.set(new TestcontainerRegistryView(suiteRegistry, classRegistry));
     }
 
     /**
-     * Stops all containers, even ones not managed via Arquillian, after the test is complete
+     * Stops class-scoped containers after the test class is complete. Suite-scoped containers are not stopped here.
      *
      * @param afterClass the after class event
      */
     public void stopContainer(@Observes AfterClass afterClass) {
-        TestcontainerRegistry registry = containerRegistry.get();
-        if (registry != null) {
-            for (TestcontainerDescription container : registry) {
-                container.instance.stop();
+        TestcontainerRegistryView registries = containerRegistries.get();
+        if (registries != null) {
+            for (TestcontainerDescription container : registries.classRegistry()) {
+                if (container.testcontainer.value() == TestcontainerLifecycle.CLASS) {
+                    container.instance.stop();
+                }
             }
         }
     }
 
     /**
      * Starts all containers after enrichment is done. This happens after the {@link ContainerInjectionTestEnricher} is
-     * invoked.
+     * invoked. Suite-scoped containers are only started if they are not already running.
      *
      * @param event the after enrichment event
      */
     public void startContainer(@Observes(precedence = 500) final AfterEnrichment event) {
-        TestcontainerRegistry registry = containerRegistry.get();
-        if (registry != null) {
-            // Look for the servers to start on fields only
-            for (TestcontainerDescription description : registry) {
-                if (description.testcontainer.value()) {
-                    description.instance.start();
-                }
+        TestcontainerRegistryView registries = containerRegistries.get();
+        if (registries == null) {
+            return;
+        }
+
+        for (TestcontainerDescription description : registries.classRegistry()) {
+            if (description.testcontainer.value() == TestcontainerLifecycle.CLASS) {
+                description.instance.start();
+            }
+        }
+
+        for (TestcontainerDescription description : registries.suiteRegistry()) {
+            if (!description.instance.isRunning()) {
+                description.instance.start();
+            }
+        }
+    }
+
+    /**
+     * Stops all suite-scoped containers when the test suite ends.
+     *
+     * @param afterSuite the after suite event
+     */
+    public void stopSuiteContainers(@Observes AfterSuite afterSuite) {
+        TestcontainerRegistry suiteRegistry = suiteContainerRegistry.get();
+        if (suiteRegistry != null) {
+            for (TestcontainerDescription container : suiteRegistry) {
+                container.instance.stop();
             }
         }
     }

src/main/java/org/arquillian/testcontainers/TestcontainerRegistryView.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright The Arquillian Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.arquillian.testcontainers;
+
+import java.lang.annotation.Annotation;
+import java.util.List;
+
+import org.arquillian.testcontainers.api.Testcontainer;
+import org.arquillian.testcontainers.api.TestcontainerLifecycle;
+import org.testcontainers.containers.GenericContainer;
+
+/**
+ * A unified view over both the suite-scoped and class-scoped {@link TestcontainerRegistry} instances, routing
+ * container lookup and creation to the appropriate registry based on the container's configured
+ * {@link TestcontainerLifecycle lifecycle}.
+ * <p>
+ * This class exists because Arquillian's {@link org.jboss.arquillian.core.api.Instance Instance&lt;T&gt;} injection
+ * in {@link org.jboss.arquillian.test.spi.TestEnricher TestEnricher} services cannot carry scope annotations
+ * ({@code @SuiteScoped}/{@code @ClassScoped}). Injecting {@code Instance<TestcontainerRegistry>} directly would
+ * always resolve to the most-specific (class) scope, making it impossible to reach the suite registry. This distinct
+ * type is produced as {@code @ClassScoped} and provides a single injection point that holds references to both
+ * registries.
+ *
+ * @author Radoslav Husar
+ */
+class TestcontainerRegistryView {
+
+    private final TestcontainerRegistry suiteRegistry;
+    private final TestcontainerRegistry classRegistry;
+
+    TestcontainerRegistryView(final TestcontainerRegistry suiteRegistry, final TestcontainerRegistry classRegistry) {
+        this.suiteRegistry = suiteRegistry;
+        this.classRegistry = classRegistry;
+    }
+
+    GenericContainer<?> lookupOrCreate(final Class<GenericContainer<?>> type, final Testcontainer testcontainer,
+            final List<Annotation> qualifiers) {
+        if (testcontainer.value() == TestcontainerLifecycle.SUITE) {
+            return suiteRegistry.lookupOrCreate(type, testcontainer, qualifiers);
+        }
+        return classRegistry.lookupOrCreate(type, testcontainer, qualifiers);
+    }
+
+    TestcontainerRegistry suiteRegistry() {
+        return suiteRegistry;
+    }
+
+    TestcontainerRegistry classRegistry() {
+        return classRegistry;
+    }
+}

src/main/java/org/arquillian/testcontainers/api/Testcontainer.java

@@ -48,12 +48,19 @@
 public @interface Testcontainer {
 
     /**
-     * Indicates whether Arquillian should manage the starting of the Testcontainer. With a value of {@code false},
-     * Arquillian will not start the server. It will still attempt to stop the server.
+     * Defines the lifecycle scope for this Testcontainer.
+     * <ul>
+     * <li>{@link TestcontainerLifecycle#SUITE SUITE} - the container is started once on first encounter and stopped
+     * when the test suite ends; the same instance is shared across test classes</li>
+     * <li>{@link TestcontainerLifecycle#CLASS CLASS} - the container is started before each test class and stopped
+     * after it completes (default)</li>
+     * <li>{@link TestcontainerLifecycle#MANUAL MANUAL} - the container is created and injected but never started or
+     * stopped by the extension</li>
+     * </ul>
      *
-     * @return {@code true} to have Arquillian manage the lifecycle of the Testcontainer
+     * @return the lifecycle scope for this Testcontainer
      */
-    boolean value() default true;
+    TestcontainerLifecycle value() default TestcontainerLifecycle.CLASS;
 
     /**
      * The type used to create the value for the field. The type must have a no-arg constructor.

src/main/java/org/arquillian/testcontainers/api/TestcontainerLifecycle.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright The Arquillian Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.arquillian.testcontainers.api;
+
+/**
+ * Defines the lifecycle scope for a container managed by the Arquillian Testcontainers extension.
+ *
+ * @author Radoslav Husar
+ */
+public enum TestcontainerLifecycle {
+
+    /**
+     * The container is started once on first encounter and stopped when the test suite ends. The same container
+     * instance is shared across all test classes that request the same container type with suite lifecycle.
+     */
+    SUITE,
+
+    /**
+     * The container is started before each test class and stopped after the test class completes. This is the default
+     * behavior.
+     */
+    CLASS,
+
+    /**
+     * The container is created and injected but never started or stopped by the framework. The user is responsible for
+     * managing the container lifecycle.
+     */
+    MANUAL,
+}

src/test/java/org/arquillian/testcontainers/ManualContainerTest.java

@@ -6,6 +6,7 @@
 package org.arquillian.testcontainers;
 
 import org.arquillian.testcontainers.api.Testcontainer;
+import org.arquillian.testcontainers.api.TestcontainerLifecycle;
 import org.arquillian.testcontainers.api.TestcontainersRequired;
 import org.arquillian.testcontainers.common.SimpleTestContainer;
 import org.jboss.arquillian.container.test.api.Deployment;
@@ -32,7 +33,7 @@
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
 public class ManualContainerTest {
 
-    @Testcontainer(false)
+    @Testcontainer(TestcontainerLifecycle.MANUAL)
     private static SimpleTestContainer container;
 
     @Deployment

src/test/java/org/arquillian/testcontainers/MixedLifecycleTest.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright The Arquillian Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.arquillian.testcontainers;
+
+import org.arquillian.testcontainers.api.Testcontainer;
+import org.arquillian.testcontainers.api.TestcontainerLifecycle;
+import org.arquillian.testcontainers.api.TestcontainersRequired;
+import org.arquillian.testcontainers.common.SimpleTestContainer;
+import org.arquillian.testcontainers.common.WildFlyContainer;
+import org.jboss.arquillian.container.test.api.Deployment;
+import org.jboss.arquillian.container.test.api.RunAsClient;
+import org.jboss.arquillian.junit5.ArquillianExtension;
+import org.jboss.shrinkwrap.api.ShrinkWrap;
+import org.jboss.shrinkwrap.api.asset.EmptyAsset;
+import org.jboss.shrinkwrap.api.spec.JavaArchive;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.opentest4j.TestAbortedException;
+
+/**
+ * Tests that suite-scoped and class-scoped containers coexist correctly in a single test class.
+ *
+ * @author Radoslav Husar
+ */
+@ExtendWith(ArquillianExtension.class)
+@RunAsClient
+@TestcontainersRequired(TestAbortedException.class)
+public class MixedLifecycleTest {
+
+    @Testcontainer(TestcontainerLifecycle.SUITE)
+    private SimpleTestContainer suiteContainer;
+
+    @Testcontainer(TestcontainerLifecycle.CLASS)
+    private WildFlyContainer classContainer;
+
+    @Deployment
+    public static JavaArchive createDeployment() {
+        return ShrinkWrap.create(JavaArchive.class)
+                .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");
+    }
+
+    @Test
+    public void suiteContainerIsRunning() {
+        Assertions.assertNotNull(suiteContainer, "Expected the suite container to be injected.");
+        Assertions.assertTrue(suiteContainer.isRunning(), "Expected the suite container to be running");
+    }
+
+    @Test
+    public void classContainerIsRunning() {
+        Assertions.assertNotNull(classContainer, "Expected the class container to be injected.");
+        Assertions.assertTrue(classContainer.isRunning(), "Expected the class container to be running");
+    }
+
+    @Test
+    public void containersAreDifferentInstances() {
+        Assertions.assertNotSame(suiteContainer, classContainer,
+                "Suite and class containers should be different instances");
+    }
+}