testwhen

testwhen is a term used in software testing to describe conditional execution of tests based on a runtime predicate. The predicate can check operating system, environment variables, feature flags, availability of dependencies, or other state at test time. If the predicate evaluates to true, the test is executed; otherwise the test is skipped or marked as not applicable. This concept is commonly implemented in test frameworks as a decorator, annotation, or function that gates a test.

In practice, testwhen appears as skip-if or enable-if mechanisms. Examples include a skip-if condition that prevents a test from running when a dependency is missing, or an enable-if condition that activates a test only when a feature flag is enabled. Some frameworks expose testwhen as a general purpose utility, while others integrate it with metadata tags or markers for selective test discovery.

Use cases include platform-specific tests (only run on Windows), optional dependencies, experimental features behind flags, environment-specific configurations in continuous integration, and performance or reliability tests that should not run in every context.

Advantages include reducing false failures when an environment does not meet requirements and speeding up test runs by avoiding irrelevant tests. Drawbacks include added complexity in test suites, potential masking of defects if overused, and the need to maintain predicates.

See also: conditional test, skip, feature flag, environment marker.