Package org.mockserver.mock

Class Expectation

java.lang.Object
org.mockserver.model.ObjectWithReflectiveEqualsHashCodeToString
org.mockserver.model.ObjectWithJsonToString
org.mockserver.mock.Expectation
public class Expectation extends ObjectWithJsonToString
Author:
jamesdbloom

  • Constructor Details

  • Method Details

    • when

      public static Expectation when(String specUrlOrPayload, String operationId)
      Specify the OpenAPI and operationId to match against by URL or payload and string as follows: 

         // Create from a publicly hosted HTTP location (json or yaml)
   when("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml", "showPetById")

   // Create from a file on the local filesystem (json or yaml)
   when("file://Users/myuser/git/mockserver/mockserver-core/src/test/resources/org/mockserver/openapi/openapi_petstore_example.json", "showPetById");

   // Create from a classpath resource in the /api package (json or yaml)
   when("org/mockserver/openapi/openapi_petstore_example.json", "showPetById");

   // Create from an OpenAPI payload (json or yaml)
   when("{\"openapi\": \"3.0.0\", \"info\": { ...", "showPetById")

      Parameters:
      specUrlOrPayload - the OpenAPI to match against by URL or payload
      operationId - operationId from the OpenAPI to match against i.e. "showPetById"
      Returns:
      the Expectation

    • when

      public static Expectation when(String specUrlOrPayload, String operationId, int priority)
      Specify the OpenAPI and operationId to match against by URL or payload and string with a match priority as follows: 

         // Create from a publicly hosted HTTP location (json or yaml)
   when("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml", "showPetById", 10)

   // Create from a file on the local filesystem (json or yaml)
   when("file://Users/myuser/git/mockserver/mockserver-core/src/test/resources/org/mockserver/openapi/openapi_petstore_example.json", "showPetById", 10);

   // Create from a classpath resource in the /api package (json or yaml)
   when("org/mockserver/openapi/openapi_petstore_example.json", "showPetById", 10);

   // Create from an OpenAPI payload (json or yaml)
   when("{\"openapi\": \"3.0.0\", \"info\": { ...", "showPetById", 10)

      Parameters:
      specUrlOrPayload - the OpenAPI to match against by URL or payload
      operationId - operationId from the OpenAPI to match against i.e. "showPetById"
      priority - the priority with which this expectation is used to match requests compared to other expectations (high first)
      Returns:
      the Expectation

    • when

      public static Expectation when(String specUrlOrPayload, String operationId, Times times, TimeToLive timeToLive)
      Specify the OpenAPI and operationId to match against by URL or payload and string for a limit number of times or time as follows: 

         // Create from a publicly hosted HTTP location (json or yaml)
   when("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml", "showPetById", 5, exactly(TimeUnit.SECONDS, 90))

   // Create from a file on the local filesystem (json or yaml)
   when("file://Users/myuser/git/mockserver/mockserver-core/src/test/resources/org/mockserver/openapi/openapi_petstore_example.json", "showPetById", 5, exactly(TimeUnit.SECONDS, 90));

   // Create from a classpath resource in the /api package (json or yaml)
   when("org/mockserver/openapi/openapi_petstore_example.json", "showPetById", 5, exactly(TimeUnit.SECONDS, 90));

   // Create from an OpenAPI payload (json or yaml)
   when("{\"openapi\": \"3.0.0\", \"info\": { ...", "showPetById", 5, exactly(TimeUnit.SECONDS, 90))

      Parameters:
      specUrlOrPayload - the OpenAPI to match against by URL or payload
      operationId - operationId from the OpenAPI to match against i.e. "showPetById"
      times - the number of times to use this expectation to match requests
      timeToLive - the time this expectation should be used to match requests
      Returns:
      the Expectation

    • when

      public static Expectation when(String specUrlOrPayload, String operationId, Times times, TimeToLive timeToLive, int priority)
      Specify the OpenAPI and operationId to match against by URL or payload and string for a limit number of times or time and a match priority as follows: 

         // Create from a publicly hosted HTTP location (json or yaml)
   when("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml", "showPetById", 5, exactly(TimeUnit.SECONDS, 90))

   // Create from a file on the local filesystem (json or yaml)
   when("file://Users/myuser/git/mockserver/mockserver-core/src/test/resources/org/mockserver/openapi/openapi_petstore_example.json", "showPetById", 5, exactly(TimeUnit.SECONDS, 90));

   // Create from a classpath resource in the /api package (json or yaml)
   when("org/mockserver/openapi/openapi_petstore_example.json", "showPetById", 5, exactly(TimeUnit.SECONDS, 90));

   // Create from an OpenAPI payload (json or yaml)
   when("{\"openapi\": \"3.0.0\", \"info\": { ...", "showPetById", 5, exactly(TimeUnit.SECONDS, 90))

      Parameters:
      specUrlOrPayload - the OpenAPI to match against by URL or payload
      operationId - operationId from the OpenAPI to match against i.e. "showPetById"
      times - the number of times to use this expectation to match requests
      timeToLive - the time this expectation should be used to match requests
      priority - the priority with which this expectation is used to match requests compared to other expectations (high first)
      Returns:
      the Expectation

    • when

      public static Expectation when(HttpRequest httpRequest)
      Specify the HttpRequest to match against as follows: 

           when(
         request()
             .withMethod("GET")
             .withPath("/some/path")
     ).thenRespond(
         response()
             .withContentType(APPLICATION_JSON_UTF_8)
             .withBody("{\"some\": \"body\"}")
     );

      Parameters:
      httpRequest - the HttpRequest to match against
      Returns:
      the Expectation

    • when

      public static Expectation when(HttpRequest httpRequest, int priority)
      Specify the HttpRequest to match against with a match priority as follows: 

           when(
         request()
             .withMethod("GET")
             .withPath("/some/path"),
         10
     ).thenRespond(
         response()
             .withContentType(APPLICATION_JSON_UTF_8)
             .withBody("{\"some\": \"body\"}")
     );

      Parameters:
      httpRequest - the HttpRequest to match against
      priority - the priority with which this expectation is used to match requests compared to other expectations (high first)
      Returns:
      the Expectation

    • when

      public static Expectation when(HttpRequest httpRequest, Times times, TimeToLive timeToLive)
      Specify the HttpRequest to match against for a limit number of times or time as follows: 

           when(
         request()
             .withMethod("GET")
             .withPath("/some/path"),
         5,
         exactly(TimeUnit.SECONDS, 90)
     ).thenRespond(
         response()
             .withContentType(APPLICATION_JSON_UTF_8)
             .withBody("{\"some\": \"body\"}")
     );

      Parameters:
      httpRequest - the HttpRequest to match against
      times - the number of times to use this expectation to match requests
      timeToLive - the time this expectation should be used to match requests
      Returns:
      the Expectation

    • when

      public static Expectation when(HttpRequest httpRequest, Times times, TimeToLive timeToLive, int priority)
      Specify the HttpRequest to match against for a limit number of times or time and a match priority as follows: 

           when(
         request()
             .withMethod("GET")
             .withPath("/some/path"),
         5,
         exactly(TimeUnit.SECONDS, 90),
         10
     ).thenRespond(
         response()
             .withContentType(APPLICATION_JSON_UTF_8)
             .withBody("{\"some\": \"body\"}")
     );

      Parameters:
      httpRequest - the HttpRequest to match against
      times - the number of times to use this expectation to match requests
      timeToLive - the time this expectation should be used to match requests
      priority - the priority with which this expectation is used to match requests compared to other expectations (high first)
      Returns:
      the Expectation

    • withId

      public Expectation withId(String id)

      Set id of this expectation which can be used to update this expectation later or for clearing or verifying by expectation id.

      Note: Each unique expectation must have a unique id otherwise this expectation will update a existing expectation with the same id.

      Parameters:
      id - unique string for expectation's id

    • withIdIfNull

      public Expectation withIdIfNull(String id)

    • getId

      public String getId()

    • withPriority

      public Expectation withPriority(int priority)

      Set priority of this expectation which is used to determine the matching order of expectations when a request is received.

      Matching is ordered by priority (highest first) then creation (earliest first).

      Parameters:
      priority - expectation's priority

    • getPriority

      public int getPriority()

    • withPercentage

      public Expectation withPercentage(Integer percentage)

    • getPercentage

      public Integer getPercentage()

    • withChaos

      public Expectation withChaos(HttpChaosProfile chaos)

    • getChaos

      public HttpChaosProfile getChaos()

    • matchesByPercentage

      public boolean matchesByPercentage()

    • withCreated

      public Expectation withCreated(long created)

    • getCreated

      public long getCreated()

    • getSortableId

      public SortableExpectationId getSortableId()

    • getHttpRequest

      public RequestDefinition getHttpRequest()

    • getHttpResponse

      public HttpResponse getHttpResponse()

    • getHttpResponseTemplate

      public HttpTemplate getHttpResponseTemplate()

    • getHttpResponseClassCallback

      public HttpClassCallback getHttpResponseClassCallback()

    • getHttpResponseObjectCallback

      public HttpObjectCallback getHttpResponseObjectCallback()

    • getHttpForward

      public HttpForward getHttpForward()

    • getHttpForwardTemplate

      public HttpTemplate getHttpForwardTemplate()

    • getHttpForwardClassCallback

      public HttpClassCallback getHttpForwardClassCallback()

    • getHttpForwardObjectCallback

      public HttpObjectCallback getHttpForwardObjectCallback()

    • getHttpOverrideForwardedRequest

      public HttpOverrideForwardedRequest getHttpOverrideForwardedRequest()

    • getHttpForwardValidateAction

      public HttpForwardValidateAction getHttpForwardValidateAction()

    • getHttpForwardWithFallback

      public HttpForwardWithFallback getHttpForwardWithFallback()

    • getHttpSseResponse

      public HttpSseResponse getHttpSseResponse()

    • getHttpLlmResponse

      public HttpLlmResponse getHttpLlmResponse()

    • getHttpWebSocketResponse

      public HttpWebSocketResponse getHttpWebSocketResponse()

    • getGrpcStreamResponse

      public GrpcStreamResponse getGrpcStreamResponse()

    • getGrpcBidiResponse

      public GrpcBidiResponse getGrpcBidiResponse()

    • getBinaryResponse

      public BinaryResponse getBinaryResponse()

    • getDnsResponse

      public DnsResponse getDnsResponse()

    • getHttpError

      public HttpError getHttpError()

    • getBeforeActions

      public List<AfterAction> getBeforeActions()

    • getAfterActions

      public List<AfterAction> getAfterActions()

    • getSteps

      public List<ExpectationStep> getSteps()

    • withSteps

      public Expectation withSteps(ExpectationStep... steps)

    • withSteps

      public Expectation withSteps(List<ExpectationStep> steps)

    • validateSteps

      public String validateSteps()
      Validates the steps list for legal combinations:
      • Exactly one step must be marked as the responder (responder = true).
      • httpError cannot be combined with other steps (it must be the only step).
      • Each step must have exactly one action target set.
      • steps cannot be combined with beforeActions — use steps for the full ordered pipeline.
      • steps cannot be combined with a top-level primary response action — the responder step defines the action.
      • steps MAY coexist with afterActions — after-actions fire after the steps pipeline completes.
      Returns:
      null if valid, or an error message describing the violation

    • getHttpResponses

      public List<HttpResponse> getHttpResponses()

    • thenRespond

      public Expectation thenRespond(List<HttpResponse> httpResponses)

    • getResponseMode

      public ResponseMode getResponseMode()

    • withResponseMode

      public Expectation withResponseMode(ResponseMode responseMode)

    • withBeforeActions

      public Expectation withBeforeActions(AfterAction... beforeActions)

    • withBeforeActions

      public Expectation withBeforeActions(List<AfterAction> beforeActions)

    • withAfterActions

      public Expectation withAfterActions(AfterAction... afterActions)

    • withAfterActions

      public Expectation withAfterActions(List<AfterAction> afterActions)

    • withScenarioName

      public Expectation withScenarioName(String scenarioName)

    • getScenarioName

      public String getScenarioName()

    • withScenarioState

      public Expectation withScenarioState(String scenarioState)

    • getScenarioState

      public String getScenarioState()

    • withNewScenarioState

      public Expectation withNewScenarioState(String newScenarioState)

    • getNewScenarioState

      public String getNewScenarioState()

    • getCrossProtocolScenarios

      public List<CrossProtocolScenario> getCrossProtocolScenarios()

    • withCrossProtocolScenario

      public Expectation withCrossProtocolScenario(CrossProtocolScenario scenario)

    • withCrossProtocolScenarios

      public Expectation withCrossProtocolScenarios(List<CrossProtocolScenario> scenarios)

    • getAction

      public Action getAction()

    • getPrimaryAction

      public Action getPrimaryAction()

    • getPreResponderSteps

      public List<ExpectationStep> getPreResponderSteps()
      Returns the ordered list of side-effect steps (non-responder steps that appear before the responder in the steps list). Returns empty list when steps is null or empty, or when no non-responder steps precede the responder.

    • getPostResponderSteps

      public List<ExpectationStep> getPostResponderSteps()
      Returns the ordered list of side-effect steps that appear after the responder in the steps list (post-responder side-effects).

    • getSecondaryActions

      public List<Action> getSecondaryActions()

    • getTimes

      public Times getTimes()

    • getTimeToLive

      public TimeToLive getTimeToLive()

    • thenRespond

      public Expectation thenRespond(HttpResponse httpResponse)

    • thenRespond

      public Expectation thenRespond(HttpTemplate httpTemplate)

    • thenRespond

      public Expectation thenRespond(HttpClassCallback httpClassCallback)

    • thenRespond

      public Expectation thenRespond(HttpObjectCallback httpObjectCallback)

    • thenForward

      public Expectation thenForward(HttpForward httpForward)

    • thenForward

      public Expectation thenForward(HttpTemplate httpTemplate)

    • thenForward

      public Expectation thenForward(HttpClassCallback httpClassCallback)

    • thenForward

      public Expectation thenForward(HttpObjectCallback httpObjectCallback)

    • thenForward

      public Expectation thenForward(HttpOverrideForwardedRequest httpOverrideForwardedRequest)

    • thenForwardValidate

      public Expectation thenForwardValidate(HttpForwardValidateAction httpForwardValidateAction)

    • thenForwardWithFallback

      public Expectation thenForwardWithFallback(HttpForwardWithFallback httpForwardWithFallback)

    • thenRespondWithSse

      public Expectation thenRespondWithSse(HttpSseResponse httpSseResponse)

    • thenRespondWithLlm

      public Expectation thenRespondWithLlm(HttpLlmResponse httpLlmResponse)

    • thenRespondWithWebSocket

      public Expectation thenRespondWithWebSocket(HttpWebSocketResponse httpWebSocketResponse)

    • thenRespondWithGrpcStream

      public Expectation thenRespondWithGrpcStream(GrpcStreamResponse grpcStreamResponse)

    • thenRespondWithGrpcBidi

      public Expectation thenRespondWithGrpcBidi(GrpcBidiResponse grpcBidiResponse)

    • thenRespondWithBinary

      public Expectation thenRespondWithBinary(BinaryResponse binaryResponse)

    • thenRespondWithDns

      public Expectation thenRespondWithDns(DnsResponse dnsResponse)

    • thenError

      public Expectation thenError(HttpError httpError)

    • isActive

      public boolean isActive()

    • decrementRemainingMatches

      public boolean decrementRemainingMatches()

    • consumeMatch

      public boolean consumeMatch()

    • consumeMatchLocally

      public void consumeMatchLocally()
      Records a match consumption WITHOUT decrementing the node-local Times counter. Used when a clustered backend has already atomically decremented the shared remaining-times counter via CAS — the local Times object must not also decrement, or the node-local counter would diverge from the shared one.

      Updates matchCount, lastConsumedCount, and chaosFirstMatchEpochMillis exactly as consumeMatch() does. These are node-local runtime metrics that do not need to be shared across the cluster.

    • getMatchCount

      public int getMatchCount()

    • getChaosFirstMatchEpochMillis

      public long getChaosFirstMatchEpochMillis()
      Epoch-ms (from the controllable clock) of this expectation's first match, or 0 if it has not been matched yet. Anchors any time-based chaos outage window. Transient runtime state — not serialized, not cloned.

    • contains

      public boolean contains(HttpRequest httpRequest)

    • clone

      public Expectation clone()
      Overrides:
      clone in class Object

    • fieldsExcludedFromEqualsAndHashCode

      public String[] fieldsExcludedFromEqualsAndHashCode()
      Overrides:
      fieldsExcludedFromEqualsAndHashCode in class ObjectWithReflectiveEqualsHashCodeToString

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class ObjectWithReflectiveEqualsHashCodeToString

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class ObjectWithReflectiveEqualsHashCodeToString