In JUnit 5, what does the @ResourceLock annotation do, and when would you reach for it?

## The problem it solves With parallel execution enabled, any two test methods may be in flight at the same time. That is fine while tests are independent, but some state cannot be duplicated per test: a system property, the JVM default time zone, `System.out`, a file at a fixed path, a TCP port, a singleton cache, a row in a shared database. If one test mutates such a thing while another reads it, results become non-deterministic. There are two honest fixes. The first and better one is to eliminate the sharing — inject the dependency instead of mutating a global, use a per-test temporary directory, bind an ephemeral port. The second, for cases where the shared thing is genuinely global, is to tell JUnit about it so it can serialise exactly the tests that conflict. `@ResourceLock` is that second mechanism. ## Anatomy ```java @ResourceLock(value = "app.config.file", mode = ResourceAccessMode.READ_WRITE) ``` - **value** — the resource key. Any string. It is an identifier, not a path or a real handle; JUnit never touches the thing it names. - **mode** — `ResourceAccessMode.READ` or `READ_WRITE` (the default). `READ_WRITE` is exclusive; `READ` is shared with other `READ` holders of the same key. The annotation is repeatable — declare several and a node needing more than one resource acquires all of them. It can be placed on a test class, a `@Nested` class, or an individual test method. ## Scope and lifetime of the lock The lock is acquired **before** the annotated node starts and released **after** it completes, and it covers the node's entire subtree and lifecycle callbacks. Two consequences follow: 1. On a test method, the lock covers `@BeforeEach`, the test body and `@AfterEach`. That matters because the risky mutation is frequently in setup or teardown, not in the test body; a lock that only covered the body would leave the race in place. 2. On a class, the lock covers every method in that class — and since the annotated node's descendants are put on a single thread, the methods of a lock-annotated class do not run concurrently with each other either. Locking at class level is therefore a heavier hammer than it looks; prefer method-level locks when only some methods touch the resource. ## The key is a convention, not a discovery The most common beginner error is expecting magic: writing `@ResourceLock("database")` on one test and `@ResourceLock("db")` on another and wondering why they still collide. JUnit compares strings. Nothing enforces that the key corresponds to anything real. That is why `org.junit.jupiter.api.parallel.Resources` exists: it defines canonical constants for JVM-global resources — `SYSTEM_PROPERTIES`, `SYSTEM_OUT`, `SYSTEM_ERR`, `LOCALE`, `TIME_ZONE` — so that a test written by one team and a test written by another still agree on the key for "the JVM's system properties". For application-specific resources, define your own constants in a shared class rather than scattering string literals; a typo silently disables the protection, and nothing fails to alert you. ## Locking versus serialising Compare three ways of dealing with a shared resource: - **`@Execution(SAME_THREAD)`** — says the annotated node's children do not run concurrently *with each other*. It does **not** stop other classes running at the same time, so it does not protect global state at all. Using it as a fix for a cross-class race is a classic mistake. - **`@ResourceLock(key)`** — says "nothing else that declares this key runs at the same time". Scoped, cheap, and lets the rest of the suite proceed. - **Exclusive execution of a whole class** — says "nothing else in the suite runs at all". Correct but expensive, and reserved for state so pervasive you cannot name it. The middle option is the one that preserves throughput, which is the whole reason you turned parallelism on. ## Practical guidance - Annotate the smallest node that actually touches the resource. Method-level locks let a class's other tests keep running concurrently. - Use `READ` when the test only observes the resource; several readers then overlap. Reserve `READ_WRITE` for mutation. - Keep locked sections short. The lock is held for the whole node, so a slow test holding a hot key throttles everything that shares it. - Avoid declaring locks on a class *and* different locks on its methods; nested acquisition of different keys is the shape most likely to produce surprising stalls. - Treat every lock as documentation of a design smell. It records that two tests share mutable state. Sometimes that is unavoidable — the JVM default locale really is global — but often it is a hint that production code is reading configuration from a static instead of receiving it. ## Version note `@ResourceLock` and the `Resources` constants have been available since JUnit 5.3. Later versions added the ability to compute lock keys dynamically through a provider, which is useful when the resource depends on the test's parameters rather than being known at compile time.