Split lifecycle into orthogonal scope and managed attribute

Replace the single TestcontainerLifecycle enum (SUITE, CLASS, MANUAL) with two independent @TestContainer attributes: boolean value() for managed/manual control (matching upstream/main) and TestcontainerScope scope() for CLASS/SUITE scoping.
This allows combinations like a manually managed suite-scoped container.

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

Author: rhusar

README.adoc

@@ -89,32 +89,38 @@ public class TypeSpecifiedInjectionTest {
 }
 ----
 
-=== Container Lifecycle
+=== Container Scope
 
 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:
+accepts a `scope` attribute to control the container's scope:
 
-* `TestcontainerLifecycle.CLASS` (default) -- the container is started before each test class and stopped after it
+* `TestcontainerScope.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.
+* `TestcontainerScope.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 scope.
   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.
+
+The `value` attribute (default `true`) controls whether Arquillian manages the container lifecycle. Setting it to
+`false` means the container is created and injected but never started by the framework. The user is responsible for
+starting the container manually. This is orthogonal to scope -- you can have a manually managed suite-scoped container.
 
 [source,java]
 ----
 // Suite-scoped container shared across test classes
-@Testcontainer(TestcontainerLifecycle.SUITE)
+@Testcontainer(scope = TestcontainerScope.SUITE)
 private KeycloakContainer keycloak;
 
 // Class-scoped container (default behavior)
 @Testcontainer
 private SimpleTestContainer container;
 
 // Manually managed container
-@Testcontainer(TestcontainerLifecycle.MANUAL)
+@Testcontainer(false)
 private SimpleTestContainer manualContainer;
+
+// Manually managed suite-scoped container
+@Testcontainer(value = false, scope = TestcontainerScope.SUITE)
+private SimpleTestContainer manualSuiteContainer;
 ----
 
 == Helpers

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

@@ -8,7 +8,6 @@
 import java.lang.reflect.InvocationTargetException;
 
 import org.arquillian.testcontainers.api.TestcontainerEventContext;
-import org.arquillian.testcontainers.api.TestcontainerLifecycle;
 import org.arquillian.testcontainers.api.TestcontainersRequired;
 import org.arquillian.testcontainers.spi.event.AfterTestcontainerStart;
 import org.arquillian.testcontainers.spi.event.AfterTestcontainerStop;
@@ -115,12 +114,10 @@ public void stopContainer(@Observes AfterClass afterClass) {
         TestcontainerRegistryView registries = containerRegistries.get();
         if (registries != null) {
             for (TestcontainerDescription container : registries.classRegistry()) {
-                if (container.testcontainer.value() == TestcontainerLifecycle.CLASS) {
-                    final TestcontainerEventContext context = createContext(container);
-                    beforeTestcontainerStop.fire(new BeforeTestcontainerStop(context));
-                    container.instance.stop();
-                    afterTestcontainerStop.fire(new AfterTestcontainerStop(context));
-                }
+                final TestcontainerEventContext context = createContext(container);
+                beforeTestcontainerStop.fire(new BeforeTestcontainerStop(context));
+                container.instance.stop();
+                afterTestcontainerStop.fire(new AfterTestcontainerStop(context));
             }
         }
     }
@@ -138,7 +135,7 @@ public void startContainer(@Observes(precedence = 500) final AfterEnrichment eve
         }
 
         for (TestcontainerDescription description : registries.classRegistry()) {
-            if (description.testcontainer.value() == TestcontainerLifecycle.CLASS) {
+            if (description.testcontainer.value()) {
                 final TestcontainerEventContext context = createContext(description);
                 beforeTestcontainerStart.fire(new BeforeTestcontainerStart(context));
                 description.instance.start();
@@ -147,7 +144,7 @@ public void startContainer(@Observes(precedence = 500) final AfterEnrichment eve
         }
 
         for (TestcontainerDescription description : registries.suiteRegistry()) {
-            if (!description.instance.isRunning()) {
+            if (description.testcontainer.value() && !description.instance.isRunning()) {
                 final TestcontainerEventContext context = createContext(description);
                 beforeTestcontainerStart.fire(new BeforeTestcontainerStart(context));
                 description.instance.start();
@@ -174,7 +171,8 @@ public void stopSuiteContainers(@Observes AfterSuite afterSuite) {
     }
 
     private static TestcontainerEventContext createContext(final TestcontainerDescription description) {
-        return new TestcontainerEventContext(description.name, description.testcontainer.value(), description.instance);
+        return new TestcontainerEventContext(description.name, description.testcontainer.scope(),
+                description.testcontainer.value(), description.instance);
     }
 
     @SuppressWarnings({ "resource", "BooleanMethodIsAlwaysInverted" })

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

@@ -8,13 +8,13 @@
 import java.util.List;
 
 import org.arquillian.testcontainers.api.Testcontainer;
-import org.arquillian.testcontainers.api.TestcontainerLifecycle;
+import org.arquillian.testcontainers.api.TestcontainerScope;
 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}.
+ * {@link TestcontainerScope scope}.
  * <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
@@ -37,7 +37,7 @@ class TestcontainerRegistryView {
 
     GenericContainer<?> lookupOrCreate(final Class<GenericContainer<?>> type, final Testcontainer testcontainer,
             final List<Annotation> qualifiers) {
-        if (testcontainer.value() == TestcontainerLifecycle.SUITE) {
+        if (testcontainer.scope() == TestcontainerScope.SUITE) {
             return suiteRegistry.lookupOrCreate(type, testcontainer, qualifiers);
         }
         return classRegistry.lookupOrCreate(type, testcontainer, qualifiers);

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

@@ -48,19 +48,26 @@
 public @interface Testcontainer {
 
     /**
-     * Defines the lifecycle scope for this 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 at the end of the configured
+     * {@link #scope() scope}.
+     *
+     * @return {@code true} to have Arquillian manage the lifecycle of the Testcontainer
+     */
+    boolean value() default true;
+
+    /**
+     * Defines the scope for this Testcontainer.
      * <ul>
-     * <li>{@link TestcontainerLifecycle#SUITE SUITE} - the container is started once on first encounter and stopped
+     * <li>{@link TestcontainerScope#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
+     * <li>{@link TestcontainerScope#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 the lifecycle scope for this Testcontainer
+     * @return the scope for this Testcontainer
      */
-    TestcontainerLifecycle value() default TestcontainerLifecycle.CLASS;
+    TestcontainerScope scope() default TestcontainerScope.CLASS;
 
     /**
      * An optional name for the container. When set, the container is registered and looked up by this name, allowing

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

@@ -7,21 +7,23 @@
 import org.testcontainers.containers.GenericContainer;
 
 /**
- * Describes a testcontainer in the context of a lifecycle event. Provides the container name, lifecycle scope,
- * and the container instance.
+ * Describes a testcontainer in the context of a lifecycle event. Provides the container name, scope, whether it is
+ * managed by Arquillian, and the container instance.
  *
  * @author Radoslav Husar
  */
 public class TestcontainerEventContext {
 
     private final String name;
-    private final TestcontainerLifecycle lifecycle;
+    private final TestcontainerScope scope;
+    private final boolean managed;
     private final GenericContainer<?> container;
 
-    public TestcontainerEventContext(final String name, final TestcontainerLifecycle lifecycle,
+    public TestcontainerEventContext(final String name, final TestcontainerScope scope, final boolean managed,
             final GenericContainer<?> container) {
         this.name = name;
-        this.lifecycle = lifecycle;
+        this.scope = scope;
+        this.managed = managed;
         this.container = container;
     }
 
@@ -35,21 +37,21 @@ public String getName() {
     }
 
     /**
-     * Returns the lifecycle scope of this container.
+     * Returns the scope of this container.
      *
-     * @return the lifecycle scope
+     * @return the scope
      */
-    public TestcontainerLifecycle getLifecycle() {
-        return lifecycle;
+    public TestcontainerScope getScope() {
+        return scope;
     }
 
     /**
-     * Returns whether this container's lifecycle is managed by Arquillian (i.e. not {@link TestcontainerLifecycle#MANUAL}).
+     * Returns whether this container's lifecycle is managed by Arquillian.
      *
      * @return {@code true} if Arquillian manages start/stop
      */
     public boolean isManaged() {
-        return lifecycle != TestcontainerLifecycle.MANUAL;
+        return managed;
     }
 
     /**

…ntainers/api/TestcontainerLifecycle.java …stcontainers/api/TestcontainerScope.javasrc/main/java/org/arquillian/testcontainers/api/TestcontainerLifecycle.java renamed to src/main/java/org/arquillian/testcontainers/api/TestcontainerScope.java src/main/java/org/arquillian/testcontainers/api/TestcontainerLifecycle.java renamed to src/main/java/org/arquillian/testcontainers/api/TestcontainerScope.java

@@ -5,27 +5,22 @@
 package org.arquillian.testcontainers.api;
 
 /**
- * Defines the lifecycle scope for a container managed by the Arquillian Testcontainers extension.
+ * Defines the 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,
+public enum TestcontainerScope {
 
     /**
      * The container is started before each test class and stopped after the test class completes. This is the default
-     * behavior.
+     * scope.
      */
     CLASS,
 
     /**
-     * The container is created and injected but never started or stopped by the framework. The user is responsible for
-     * managing the container lifecycle.
+     * 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 scope.
      */
-    MANUAL,
+    SUITE,
+
 }

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

@@ -6,7 +6,6 @@
 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;
@@ -33,7 +32,7 @@
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
 public class ManualContainerTest {
 
-    @Testcontainer(TestcontainerLifecycle.MANUAL)
+    @Testcontainer(false)
     private static SimpleTestContainer container;
 
     @Deployment

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

@@ -6,7 +6,7 @@
 package org.arquillian.testcontainers;
 
 import org.arquillian.testcontainers.api.Testcontainer;
-import org.arquillian.testcontainers.api.TestcontainerLifecycle;
+import org.arquillian.testcontainers.api.TestcontainerScope;
 import org.arquillian.testcontainers.api.TestcontainersRequired;
 import org.arquillian.testcontainers.common.SimpleTestContainer;
 import org.arquillian.testcontainers.common.WildFlyContainer;
@@ -31,10 +31,10 @@
 @TestcontainersRequired(TestAbortedException.class)
 public class MixedLifecycleTest {
 
-    @Testcontainer(TestcontainerLifecycle.SUITE)
+    @Testcontainer(scope = TestcontainerScope.SUITE)
     private SimpleTestContainer suiteContainer;
 
-    @Testcontainer(TestcontainerLifecycle.CLASS)
+    @Testcontainer(scope = TestcontainerScope.CLASS)
     private WildFlyContainer classContainer;
 
     @Deployment

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

@@ -6,7 +6,7 @@
 package org.arquillian.testcontainers;
 
 import org.arquillian.testcontainers.api.Testcontainer;
-import org.arquillian.testcontainers.api.TestcontainerLifecycle;
+import org.arquillian.testcontainers.api.TestcontainerScope;
 import org.arquillian.testcontainers.api.TestcontainersRequired;
 import org.arquillian.testcontainers.common.SimpleTestContainer;
 import org.jboss.arquillian.container.test.api.Deployment;
@@ -28,7 +28,7 @@
 @TestcontainersRequired(TestAbortedException.class)
 public class SuiteContainerTest {
 
-    @Testcontainer(TestcontainerLifecycle.SUITE)
+    @Testcontainer(scope = TestcontainerScope.SUITE)
     private SimpleTestContainer suiteContainer;
 
     @Deployment