spring-async-demo/awaitility/README.md

# awaitility

Companion code for the Awaitility article on [ankurm.com](https://ankurm.com). All intermediate
and reference-grade depth lives in the post itself (accordions / "going deeper" paragraphs), not
in a `docs/NN-topic.md` chapter folder — the one exception, as in the rest of this repository, is
`docs/output/`, which holds real captured transcripts and nothing else.

## What this is

Six real, runnable demonstrations of the same idea: a fixed `Thread.sleep(...)` in a test is a
guess about timing the test does not control, and `Awaitility.await()` replaces the guess with a
bounded poll loop. Each demonstration targets a different source of asynchrony:

| Test | What it waits for |
|---|---|
| `AwaitAsyncConfirmationTest` | A `void` `@Async` method with no `Future` to block on |
| `DefaultTimingTest` | Nothing — it proves Awaitility's own defaults (10s timeout, 100ms poll interval) against the real jar |
| `KafkaListenerAwaitTest` | An `@KafkaListener` consuming a record a `KafkaTemplate` just sent, against a real in-process `@EmbeddedKafka` broker |
| `ScheduledJobAwaitTest` | Three more executions of an already-running `@Scheduled(fixedRate = 150)` job |
| `UncaughtExceptionHandlerSwapTest` | Nothing — it proves `await()` temporarily installs its own `Thread.setDefaultUncaughtExceptionHandler` and restores the original afterward |
| `IgnoreExceptionsTest` | A resource that throws for its first 300ms, using `ignoreExceptionsInstanceOf(...)` to treat that as "not yet", not a failure |

Two more transcripts in `docs/output/` are real failures from tests that are *not* in the suite
above: `01-sleep-guesses-wrong.txt` (a fixed `Thread.sleep(100)` against a 220ms operation) and
`08-exception-propagates-immediately.txt` (the same resource as `IgnoreExceptionsTest`, minus
`ignoreExceptionsInstanceOf(...)`). Both were real `mvn test` runs, captured once, then the
failing test class was deleted — the mistake is preserved as a transcript, not as a permanently
red test.

## The pom.xml trap this module exists to document

The first version of this module's `pom.xml` depended on `org.springframework.kafka:spring-kafka`
directly, the way every pre-Boot-4.1 tutorial does. It compiled. Every `@SpringBootTest` using
Kafka then failed with an empty `ConcurrentLinkedQueue` and no error at context startup, because
in Boot 4.1.1 the Kafka autoconfiguration classes (`KafkaTemplate`, `ConsumerFactory`, the
`KafkaListenerEndpointRegistry` that `@KafkaListener` needs) moved out of the monolithic
`spring-boot-autoconfigure` jar into their own module, `org.springframework.boot:spring-boot-kafka`
— pulled in by the new `org.springframework.boot:spring-boot-starter-kafka`, not by `spring-kafka`
alone. See `pom.xml`'s own comments and the post for the full diagnosis.

## Versions

Read from `spring-boot-dependencies-4.1.1.pom` and `spring-boot-starter-test-4.1.1.pom` on Maven
Central, not from release notes: **JDK 25** (Temurin 25.0.4.1+1), **Spring Boot 4.1.1**,
**Spring Kafka 4.1.1**, **Awaitility 4.3.0** (already on the classpath via
`spring-boot-starter-test` — no explicit `<dependency>` for it anywhere in `pom.xml`).

## Quickstart

```
mvn test
```

11 tests, 0 failures. `KafkaListenerAwaitTest` starts a real in-process Kafka broker
(`@EmbeddedKafka`) and takes a few seconds; `DefaultTimingTest` deliberately waits out Awaitility's
real 10-second default timeout once, so the suite as a whole takes about 30 seconds.

## Captured output

| File | What it's from |
|---|---|
| `00-full-test-run.txt` | The full `mvn test` run, 11/11 green |
| `01-sleep-guesses-wrong.txt` | Real failure: a guessed `Thread.sleep(100)` against a 220ms operation (test since removed) |
| `02-await-finds-it.txt` | The fixed version: `await().untilAsserted(...)` against the same operation |
| `03-default-timeout-is-ten-seconds.txt` | `await().until(() -> false)` timing out at ~10,000ms with no override |
| `04-default-poll-interval-is-100ms.txt` | Real poll timestamps, ~100ms apart, with no override |
| `05-kafka-listener-await.txt` | `await()` for an `@KafkaListener` to consume a record just sent |
| `06-scheduled-job-await.txt` | `await()` for 3 more executions of an already-running `@Scheduled` job |
| `07-uncaught-exception-handler-swap.txt` | Proof that `await()` swaps and restores the JVM's default uncaught-exception handler |
| `08-exception-propagates-immediately.txt` | Real failure: an exception from the polled condition, with no `ignoreExceptionsInstanceOf(...)`, failing on the first poll (test since removed) |
| `09-ignore-exceptions-waits-it-out.txt` | The fixed version: the same resource, with `ignoreExceptionsInstanceOf(...)` |
| `10-missing-kafka-starter-failure.txt` | Real failure: the Kafka test with `spring-kafka` as a direct dependency instead of `spring-boot-starter-kafka` (pom.xml since fixed) |
| `11-pom-diagnosis.txt` | The real `curl`/`grep` transcript that found the Boot 4.1 Kafka module split against Maven Central's own POMs |

## What's sourced from documentation, not run here

Awaitility's own `@since` Javadoc tags, Spring Boot's own migration notes for the Kafka module
split, and the general shape of `@KafkaListener`/`@EmbeddedKafka` wiring are cited from the real
jars and POMs on Maven Central (see the post for exact artifact coordinates), not re-derived from
scratch in this module.

## Licence

MIT — see [LICENSE](../LICENSE).