Skip to content

9d · Simulated integrations

An HTTP_CALL, LLM_CALL or AGENT step never reaches the network in a test: without a stub it fails at once, with a message naming the stub to add. With one, the engine renders the request exactly as in production, and the stubbed response goes through the step’s own successStatus, retryOn and output mapping. From IntegrationsTest.java:

The hotel’s API — and the key it receives

Section titled “The hotel’s API — and the key it receives”
@Test
void sendsTheSameIdempotencyKeyOnEveryAttempt(WorkflowTestRuntime runtime) {
var hotel = runtime.whenHttpCall("rooms")
.thenRespond(503, "busy") // retried: 5xx is in retryOn
.thenRespond(201, "{\"id\": \"H-42\"}");
var booking = runtime.start("rooms-booking-http", "HTTP-1",
Map.of("rooms", "[{\"number\": \"101\", \"type\": \"double\"}]"));
runtime.advanceTime(java.time.Duration.ofMinutes(1));
assertThat(booking).isCompleted()
.hasVariable("roomBookings", "[{\"status\": \"COMPLETED\", \"value\": \"H-42\"}]");
assertThat(hotel.requests()).hasSize(2)
.allSatisfy(request -> assertThat(request.get("headers"))
.isEqualTo(Map.of("Idempotency-Key", "HTTP-1-101")));
}

The hotel is busy once, then books the room. The test checks what matters for not booking twice: both attempts carried the same Idempotency-Key, built from the business key and the room. hotel.requests() is every request the step rendered — method, path, headers, body.

The step makes one call per room. A scoped stub answers some of them apart from the others — by iteration (whenIteration(1)), by item (whenItemHas("number", "102")) or by request (whenRequest(…)) — with answers of its own. Room 102 is refused; the hotel offers 104 instead, and the guest accepts:

@Test
void aRoomTheHotelTurnsDownIsReplacedByTheAlternativeTheGuestAccepts(WorkflowTestRuntime runtime) {
var hotel = runtime.whenHttpCall("rooms").thenRespond(201, "{\"id\": \"H-1\"}"); // every room…
hotel.whenItemHas("number", "102").thenRespond(409, "sold out"); // …but 102: a 4xx is final
runtime.whenHttpCall("find-alternatives")
.thenRespond(200, "[{\"number\": \"104\", \"type\": \"suite\", \"instead\": \"102\"}]");
var alternatives = runtime.whenHttpCall("book-alternatives").thenRespond(201, "{\"id\": \"H-4\"}");
runtime.whenStep("ask-guest").thenComplete();
var booking = runtime.start("rooms-booking-http", "HTTP-2", Map.of("rooms", Rooms.THREE_DOUBLES));
assertThat(booking).isWaitingAt("wait-for-guest");
runtime.sendMessage("guest-answer", "HTTP-2", Map.of("answer", "accept"));
assertThat(booking).isCompleted().hasPassedSteps("booked-with-alternatives").hasNoCompensations();
assertThat(booking).iterations("rooms").hasOnlyFailed("Room 102").hasNoneCompensated();
assertThat(alternatives.requests()).singleElement()
.satisfies(request -> assertThat(String.valueOf(request.get("body"))).contains("104"));
}

Nothing was undone — hasNoneCompensated() — and the alternative was booked with a request of its own. If the guest cancels instead, the compensation runs over HTTP too:

@Test
void theGuestCancellingCancelsTheBookedRoomsOverHttp(WorkflowTestRuntime runtime) {
var hotel = runtime.whenHttpCall("rooms").thenRespond(201, "{\"id\": \"H-1\"}");
hotel.whenItemHas("number", "102").thenRespond(409, "sold out");
runtime.whenHttpCall("find-alternatives").thenRespond(200, "[]");
var cancel = runtime.whenHttpCall("cancel-room").thenRespond(204);
runtime.whenStep("ask-guest").thenComplete();
var booking = runtime.start("rooms-booking-http", "HTTP-3", Map.of("rooms", Rooms.THREE_DOUBLES));
runtime.sendMessage("guest-answer", "HTTP-3", Map.of("answer", "cancel"));
assertThat(booking).isCompensated().hasCompensated("rooms");
assertThat(booking).iterations("rooms")
.hasOnlyFailed("Room 102")
.hasCompensated("Room 101", "Room 103");
assertThat(cancel.requests()).extracting(request -> request.get("path"))
.containsExactlyInAnyOrder("/bookings/by-ref/HTTP-3-101", "/bookings/by-ref/HTTP-3-103");
}

The DELETEs went to exactly the two rooms that were booked. Each scope consumes (and repeats) its own answers, so hotel.whenIteration(0).thenRespond(503, "busy").thenRespond(201, …) would make that room retry while the others are booked at once.

@Test
void classifiesTheRequestAndDraftsTheEmail(WorkflowTestRuntime runtime) {
var classify = runtime.whenLlmCall("classify-request")
.thenAnswer("{\"category\": \"accessibility\", \"needsStaff\": true, \"summary\": \"wheelchair\"}");
runtime.whenLlmCall("draft-confirmation").thenAnswer("Dear Erin, your booking is confirmed.");
runtime.whenStep("notify-guest").thenComplete();
var booking = runtime.start("special-request", "LLM-1", Map.of("guest", "Erin",
"specialRequest", "I use a wheelchair", "rooms", Rooms.THREE_DOUBLES));
assertThat(booking).isCompleted()
.hasVariable("requestCategory", "accessibility")
.hasVariable("confirmationEmail", "Dear Erin, your booking is confirmed.");
assertThat(String.valueOf(classify.lastRequest().get("prompt"))).contains("I use a wheelchair");
}

The stubbed answer goes through the step’s output expressions (json.category) — so the test checks the mapping, and lastRequest() checks the prompt the engine actually rendered.

The stub is validated against the step’s responseSchema, as a real model’s answer is. Stub {"category": "spa"} and the test fails, saying what the schema refuses — category is not in the enum, needsStaff and summary are missing — instead of passing on an answer production would never accept. To test what happens when the model does answer badly, say so: thenInvalidAnswer("…") fails the call with LLM_INVALID_OUTPUT, and the step retries as it would in production.

AGENT cannot run in the workshop app (it needs the IA catalogue), but it runs in a test: the kit plays both the catalogue and the agent runtime. The definition is test-only, in src/test/flows/special-request-agent.ec.yaml.

@Test
void anAgentCanBeHeldForHumanReview(WorkflowTestRuntime runtime) {
runtime.whenAgent("prepare-request")
.thenReviewRequired()
.thenOutput("{\"actions\": [\"reserve an accessible room\"]}");
var booking = runtime.start("special-request-agent", "AGENT-1",
Map.of("guest", "Erin", "specialRequest", "I use a wheelchair"));
assertThat(booking).hasStatus(ProcessStatus.PAUSED)
.hasStepStatus("prepare-request", StepExecutionStatus.REVIEW_REQUIRED);
runtime.resolveAgentReview(booking, "prepare-request");
assertThat(booking).isCompleted().hasVariable("preparation");
}

The process pauses while the agent’s outcome is under review, and goes on only once the runtime resolves it.

The hotel booking does not wait for messages or accept updates, so it needs none of these — but when your process does, the kit drives them the same way: sendMessage(name, correlationKey, variables), publishEvent(destination, type, data), and update(process, "changeDates", payload) with assertions on the outcome. See Testing Workflows.