Introduce SUITE, CLASS scope modes for @Testcontainer annotation by rhusar · Pull Request #127 · arquillian/arquillian-extension-testcontainers

rhusar · 2026-04-30T08:25:58Z

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

rhusar · 2026-04-30T08:31:26Z

This is a feature we would need in WildFly clustering test suite when running a group of tests against an Infinispan server and there are also Elytron TS use cases.

Opening as draft before I head over for PTO later today so I don't forget all about it while I am off. Nevertheless, seems fully functional but haven't tested it outside of the integration testsuite done here. Note the complications of the TestcontainerRegistryView class, which is working around the injection of the same class but in different scoped; all explained in the Javadoc.

This will need adaptation as the #123 and #124 get merged.

Have a look @jamezp @jasondlee and might be of interest to @haster too

haster · 2026-04-30T15:43:36Z

This is gonna be really useful to us. We re-use our containers between different testclasses, mostly for performance reasons. This PR is shaping up to be exactly what we planned to send in.

Claude is also very happy:

Strong design choices:

MANUAL cleanly replaces the asymmetric value=false (started=false, stopped=true). Now all three
states are explicit.

SUITE containers start on first encounter via the if (!description.instance.isRunning()) guard,
persist across test classes, stop at AfterSuite. Exactly the cube STARTANDSTOP semantics.

TestcontainerRegistryView solves a real Arquillian SPI limitation (you can't qualify Instance by
scope in a TestEnricher) — clean approach.

…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: arquillian#126 Signed-off-by: Radoslav Husar <rhusar@redhat.com> Signed-off-by: Radoslav Husar <radosoft@gmail.com>

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>

rhusar · 2026-05-02T08:23:33Z

Discussed with @jamezp yesterday and we realized that these concepts are rather orthogonal, so rebased and refactored to actually handle scope and manual mode as 2 separate concepts (i.e. you can have both class and suite scopes manual).

Ready for review now.

rhusar · 2026-05-02T08:26:18Z

Also a note on the TestcontainerRegistryView rather than a single collection/registry - this keeps the door open for potential future concurrent test execution where class scoped registries are not shared while the suite one is.

rhusar · 2026-05-11T14:55:29Z

Back from holiday today. Any chance anyone had any more thoughts on this? @jamezp @haster @jasondlee let me know.

haster

This looks good and useful to me. I've added some comments, and Claude added some more, but nothing major.

haster · 2026-05-13T20:09:46Z

+
+    @Test
+    public void containersAreDifferentInstances() {
+        Assertions.assertNotSame(suiteContainer, classContainer,


The injected containers are of different types, so wouldn't this always be true, regardless of scope?

haster · 2026-05-13T20:13:09Z

+@ExtendWith(ArquillianExtension.class)
+@RunAsClient
+@TestcontainersRequired(TestAbortedException.class)
+public class MixedLifecycleTest {


I think it would be beneficial to have an actual suite of two test classes working together, injecting the same containers, one class and one suitescoped in each. You could then verify that the suitecontainer is the same in both instances but the class containers are different. Not sure how easy that is to actually do, though. 😅

Perhaps that is more a feature of the other test, focusing only on the suite scope injection. 🤔

One possible solution would be to have two test classes in a suite, both extending the same base class, which holds a static field. First testclass records the injected suitescoped container in that field, second class check it against their own injected container.

haster · 2026-05-13T20:38:10Z

-        final TestcontainerRegistry instances = new TestcontainerRegistry();
-        containerRegistry.set(instances);
+
+        // Read suite registry before setting class registry — both InstanceProducers share the same generic type


(generated by Claude)

The ordering comment documents a real footgun. The same SPI limitation that justified TestcontainerRegistryView (distinct types so Instance<T> can disambiguate) applies here too — a future reader who reorders these two lines (or splits them across methods) silently breaks suite resolution. Consider giving the suite registry its own marker subtype (SuiteTestcontainerRegistry extends TestcontainerRegistry) so the producers are distinguishable by type and the ordering becomes irrelevant.

haster · 2026-05-13T20:42:21Z

+                description.instance.start();
+                afterTestcontainerStart.fire(new AfterTestcontainerStart(context));
            }
        }


(generated by Claude)

Your earlier comment about keeping TestcontainerRegistryView open for "future concurrent test execution where class scoped registries are not shared while the suite one is" suggests parallel class execution is on the roadmap. In that world, two classes both hitting this !isRunning() check concurrently can both observe it as false and both call start(). Today it's just a TODO, but worth either a guarding comment ("not safe for parallel class execution") or — if parallel is near-term — a synchronized first-start latch per description.

haster · 2026-05-13T20:46:43Z

I've added some review comments. In general it looks good to me.

I haven't had a lot of time on our side to work on this, preparing for a release took precedence, but I've been putting in some work. I think I'll open a small PR in a few minutes.

After today, I will be on holiday for a long weekend so likely not to respond until later next week.

rhusar · 2026-05-27T14:24:47Z

Hm, should we have a Scope.METHOD that the testcontainer span is only for individual test method? Just analogous to class/suite.

haster · 2026-05-28T05:06:07Z

The injected container would still exist class-wide, correct? It would just be restarted/recreated for every method? Do I understand that correctly?

We don't have a specific usecase for this as of now, but I see the symmetry you're referring to. I'd say, if it's easy to implement, sure, if it's too complex then maybe leave it until people ask for it.

rhusar · 2026-05-28T11:08:27Z

The injected container would still exist class-wide, correct? It would just be restarted/recreated for every method? Do I understand that correctly?

Yes, exactly, that would be it. So at the beginning of every method invocation you get a new container instance so that any state in the container is reset between individual tests.

We don't have a specific usecase for this as of now, but I see the symmetry you're referring to. I'd say, if it's easy to implement, sure, if it's too complex then maybe leave it until people ask for it.

I dont think we do either, but it's an obvious symmetry. Anyway, lets see what @jamezp thinks when he comes back. I would create a new issue fro that anyway, so this can move already.

rhusar force-pushed the container-lifecycle-scoping branch from 35d0681 to d34a1d1 Compare April 30, 2026 08:41

rhusar mentioned this pull request Apr 30, 2026

Add named container lookup to support multiple containers of the same… #123

Merged

haster mentioned this pull request Apr 30, 2026

Additional tests for named container lookup rhusar/arquillian-extension-testcontainers#1

Merged

rhusar added 2 commits May 2, 2026 10:19

rhusar force-pushed the container-lifecycle-scoping branch from d34a1d1 to 111aeec Compare May 2, 2026 08:21

rhusar marked this pull request as ready for review May 2, 2026 08:21

rhusar changed the title ~~Introduce SUITE, CLASS, and MANUAL lifecycle modes for @Testcontainer annotation, replacing the previous boolean value.~~ Introduce SUITE, CLASS scope modes for @Testcontainer annotation May 2, 2026

haster reviewed May 13, 2026

View reviewed changes

rhusar mentioned this pull request May 21, 2026

Allow reusing deployments for multiple test classes arquillian/arquillian-core#850

Open

rhusar mentioned this pull request Jun 17, 2026

Issue 117 part1 #129

Open

Uh oh!

Conversation

rhusar commented Apr 30, 2026

Uh oh!

rhusar commented Apr 30, 2026

Uh oh!

haster commented Apr 30, 2026

Uh oh!

rhusar commented May 2, 2026

Uh oh!

rhusar commented May 2, 2026

Uh oh!

rhusar commented May 11, 2026

Uh oh!

haster left a comment

Choose a reason for hiding this comment

Uh oh!

haster May 13, 2026

Choose a reason for hiding this comment

Uh oh!

haster May 13, 2026

Choose a reason for hiding this comment

Uh oh!

haster May 13, 2026

Choose a reason for hiding this comment

Uh oh!

haster May 13, 2026

Choose a reason for hiding this comment

Uh oh!

haster May 13, 2026

Choose a reason for hiding this comment

Uh oh!

haster commented May 13, 2026

Uh oh!

rhusar commented May 27, 2026

Uh oh!

haster commented May 28, 2026

Uh oh!

rhusar commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rhusar commented May 28, 2026 •

edited

Loading