Package org.mockserver.client

Class TurnBuilder

java.lang.Object
org.mockserver.client.TurnBuilder
public class TurnBuilder extends Object
Sub-builder for configuring a single turn within an LLM conversation mock.

Provides fluent predicates for matching inbound requests and a response to return when all predicates match. Returns to the parent LlmConversationBuilder via andThen().

  • Method Details

    • whenTurnIndex

      public TurnBuilder whenTurnIndex(int n)
      Match when the conversation has exactly n assistant turns.
      Parameters:
      n - the turn index (0-based count of assistant messages)
      Returns:
      this builder

    • whenLatestMessageContains

      public TurnBuilder whenLatestMessageContains(String text)
      Match when the latest message's text content contains the given substring.
      Parameters:
      text - the substring to match
      Returns:
      this builder

    • whenLatestMessageMatches

      public TurnBuilder whenLatestMessageMatches(Pattern regex)
      Match when the latest message's text content matches the given regex.
      Parameters:
      regex - the regex pattern to match
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the regex fails to compile

    • whenLatestMessageContains

      @Deprecated public TurnBuilder whenLatestMessageContains(Pattern regex)
      Deprecated.
      misleading name — this overload matches by regex, not substring. Use whenLatestMessageMatches(Pattern). Retained for source compatibility; delegates to whenLatestMessageMatches.

    • whenLatestMessageRole

      public TurnBuilder whenLatestMessageRole(ParsedMessage.Role role)
      Match when the latest message has the given role.
      Parameters:
      role - the role to match
      Returns:
      this builder

    • whenContainsToolResultFor

      public TurnBuilder whenContainsToolResultFor(String toolName)
      Match when the conversation contains a tool result for a prior call of the named tool.
      Parameters:
      toolName - the tool name to look for
      Returns:
      this builder

    • whenSemanticMatch

      public TurnBuilder whenSemanticMatch(String expectedMeaning)
      Opt-in fuzzy semantic match: match when the latest message expresses the given intent, judged by a runtime LLM. Off by default and ignored unless mockserver.llmSemanticMatchingEnabled is set and a backend resolves. Non-deterministic — exploratory only, never for assertions.
      Parameters:
      expectedMeaning - the intent the latest message should express
      Returns:
      this builder

    • withNormalization

      public TurnBuilder withNormalization(NormalizationOptions normalization)
      Apply opt-in prompt normalisation before the whenLatestMessage… text predicates are evaluated, so cosmetic differences (whitespace, JSON key ordering, volatile ids/timestamps) do not block a match. Deterministic — the same prompt always normalises identically.
      Parameters:
      normalization - the normalisation options
      Returns:
      this builder

    • withChaos

      public TurnBuilder withChaos(LlmChaosProfile chaos)
      Apply a fault/chaos profile to this turn's response (probabilistic errors, mid-stream truncation, malformed SSE) for resilience testing.
      Parameters:
      chaos - the chaos profile
      Returns:
      this builder

    • respondingWith

      public TurnBuilder respondingWith(Completion completion)
      Set the completion to return for this turn.
      Parameters:
      completion - the completion response
      Returns:
      this builder

    • andThen

      public LlmConversationBuilder andThen()
      Return to the parent conversation builder for chaining additional turns.
      Returns:
      the parent LlmConversationBuilder

    • applyTo

      public Expectation[] applyTo(MockServerClient client)
      Shortcut: build and register all turns with the MockServerClient. Delegates to the parent builder's applyTo.
      Parameters:
      client - the MockServerClient
      Returns:
      the created expectations