Conditions & Watchers

## The problem Some tests should not run everywhere: an integration test that needs a database, a test that only makes sense on Linux, a test gated behind a feature flag. Deleting or commenting them out loses them. JUnit 5 solves this with **conditional test execution**, and the extension point behind it is `ExecutionCondition`. ## The interface ```java public interface ExecutionCondition extends Extension { ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context); } ``` One method. It receives the `ExtensionContext` — the engine's handle on the node being considered, from which you can get the display name, the test class (`getTestClass()`), the test method (`getTestMethod()`), the annotated element (`getElement()`), tags, and configuration parameters (`getConfigurationParameter(String)`). `ConditionEvaluationResult` is a small value object with three factory methods: `enabled(String reason)`, `disabled(String reason)` and `disabled(String reason, String customReason)` (the second form lets a condition carry both a generic reason and a user-supplied message, which is how annotations with a `disabledReason` attribute work). There is no "abstain" — you must return enabled or disabled, and enabled simply means "I have no objection". ## When it is evaluated The Jupiter engine evaluates conditions **before** the node is executed, for every *container* and every *test*: the test class, each `@Nested` class, and each test method — and for a `@TestTemplate` such as `@RepeatedTest` or `@ParameterizedTest`, for each invocation as well. Conditions registered at class level therefore run once for the class and again for each method in it, so keep them cheap or cache the expensive part (for instance a single socket probe held in a static field or in the extension context store). Conditions are evaluated in registration order and the engine **short-circuits on the first `disabled` result** — remaining conditions are not consulted. Disabling a container skips every test inside it; those tests are not evaluated individually. ## Reporting semantics A disabled node is reported to the launcher as **skipped with a reason**, not failed and not passed. Gradle, Maven Surefire, IDEs and the ConsoleLauncher all surface it as a skip, and the reason string you returned is the message shown. This is the main reason to prefer a condition over silently `return`-ing from the test body: a skipped test is visible, a test that returns early looks green and lies. ## Registration A condition is an ordinary extension, so it is registered the ordinary ways: `@ExtendWith(MyCondition.class)` on a class or method, a `@RegisterExtension` field, automatic registration via the `ServiceLoader` mechanism, or — most idiomatically — through a **composed (meta) annotation**: ```java @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @ExtendWith(DatabaseCondition.class) public @interface RequiresDatabase { String url() default "jdbc:postgresql://localhost:5432/test"; } ``` Inside the condition, `AnnotationSupport.findAnnotation(context.getElement(), RequiresDatabase.class)` gives you the annotation and its attributes. `findAnnotation` walks the element, so class-level annotations are visible when evaluating a method. ## The built-ins are the same mechanism `@Disabled` is implemented by `DisabledCondition`; `@EnabledOnOs` / `@DisabledOnOs`, `@EnabledOnJre` / `@EnabledForJreRange`, `@EnabledIfSystemProperty`, `@EnabledIfEnvironmentVariable`, and `@EnabledIf` / `@DisabledIf` (which call a named boolean method) are each an `ExecutionCondition` shipped with Jupiter. Reach for those first; write your own only when the predicate is genuinely custom. Because they are all conditions, they are all subject to the `junit.jupiter.conditions.deactivate` configuration parameter, which can turn conditions off for a run. ## Design guidance - **Make the reason actionable.** `disabled("no Docker daemon on unix:///var/run/docker.sock")` beats `disabled("skipped")`; that string is the only thing a colleague sees in CI output. - **Fail loudly in CI.** A condition that skips when infrastructure is missing is convenient locally and dangerous in CI, where an infrastructure outage becomes a green build with silent skips. A common pattern is to make the condition itself conditional: skip locally, but return `enabled` (and let the test fail hard) when an environment variable such as `CI` is set. - **Keep it fast and side-effect free.** Conditions run for every node; a five-second connection timeout per test method is a real cost. - **Do not throw from a condition to skip.** An exception from `evaluateExecutionCondition` is a failure, not a skip. - **Conditions are static-ish, per-node decisions.** If the decision can only be made once the test is running with resolved fixtures, that is what assumption-style aborts are for; conditions run before the test instance even exists.