In Karate's JUnit integration, what is the `@Karate.Test` annotation, where may it be placed, and what must the annotated method return?

## What the annotation actually is Strip away the convenience and `@Karate.Test` is three lines of Java: - `@Target(ElementType.METHOD)` — it goes on a **method**, never on a class. Putting it on a class does not compile. - `@Retention(RetentionPolicy.RUNTIME)` — visible to JUnit at discovery time. - `@TestFactory` — the meta-annotation that does all the work. Because `@TestFactory` is meta-annotated onto it, JUnit treats the annotated method exactly as if you had written `@TestFactory` yourself. `@Karate.Test` is sugar with a name that reads well next to Karate code; it grants no capability that `@TestFactory` does not already provide. ## Why the return type matters A `@TestFactory` method must return something JUnit can turn into dynamic tests — a `Stream`, `Collection`, `Iterator` or `Iterable` of `DynamicNode`. Karate's JUnit `Karate` class **implements `Iterable<DynamicNode>`**, so returning it satisfies that contract directly: ```java class OrdersRunner { @Karate.Test Karate testOrders() { return Karate.run("orders").relativeTo(getClass()); } } ``` `Karate.run("orders")` is a shortcut for a new instance with that path set, and `relativeTo(getClass())` anchors it to the annotated class's own package so the feature file can sit beside the Java file. Iterating the returned object is what starts execution: each feature becomes a container node and each scenario a test node, which is why the IDE shows a tree that expands into individual scenarios rather than one opaque green tick. ## The two entry points, and which is which | | `@Karate.Test` | `Runner.path(...).parallel(n)` | |---|---|---| | shape | annotated method returning `Karate` | plain Java inside an ordinary `@Test` | | reporting | one JUnit node per feature and scenario | one JUnit result for the whole suite | | failure surfacing | JUnit fails the individual node | you assert on the returned failure count | | typical use | running and debugging in an IDE | the CI entry point | They are not competitors. A project commonly has both: small annotated methods next to the feature packages for development, and one parallel runner class that CI invokes. The dividing line used to be sharper. **On Karate 1.x the JUnit entry point is deliberately single-threaded** — its `threads(int)` returns the underlying builder rather than the `Karate` object, which breaks the chain and stops you handing a thread count to something JUnit is going to iterate. **Karate 2.x removes that restriction**: its JUnit class exposes `threads(int)` returning itself, and streams results back as scenarios complete. If you are on 1.x and want parallelism, the parallel runner is the only route. ## What Karate does *not* ship This is where the interview usually goes next, and the answer is a list of absences: - **No JUnit Platform `TestEngine`.** Karate never registers an engine, so nothing discovers `.feature` files on its own. A Java method must name them. - **No suite annotation of its own.** There is no Karate equivalent of a `@Suite`-style class annotation that points at feature directories. - **No `@RunWith`-style runner** in the modern API. Everything goes through `@TestFactory` or through plain Java in a `@Test` body. - **No step-definition scanning**, so the annotation carries no glue or package argument — only a path. The consequence is that Karate's JUnit integration is unusually thin. It is one annotation, one class implementing `Iterable<DynamicNode>`, and JUnit's own dynamic-test feature doing the rest. ## Practical notes - **The method's visibility can be package-private**, like any Jupiter test method; it does not need to be `public`. - **Name the method after what it runs.** JUnit uses the method name as the parent node's display name, so `testOrders` reads better than `test1` when a scenario fails three levels down. - **`relativeTo(getClass())` is what keeps the path short.** Without it you are back to `classpath:` paths, which is fine but less convenient for a file sitting beside the class. - **One annotated method per feature area** keeps the IDE tree readable and lets you run a slice by clicking its gutter icon. - **Do not point CI at these.** They are per-package and single-purpose; a suite-wide run wants the parallel runner and its aggregate failure count. ## Reading one in review When you meet an annotated method in a codebase, three checks tell you whether it does what its author thought: 1. **Is the annotation on a method?** It cannot compile on a class, but a reviewer scanning quickly can still misread a class-level `@Karate.Test` in a diff that never built. 2. **Is the return value the configured object?** Building a `Karate` instance, configuring it, and then returning a different one is an easy slip in a method with two chains, and it fails silently by running the wrong path. 3. **Does the path resolve from the anchor?** `relativeTo(getClass())` anchors to the annotated class's package. Move the Java file without moving the feature file and the method finds nothing — which, as with any empty selection, is a fast green rather than an error.