Working with MockServices in SoapUI

The SOAP Service Mocking functionality in SoapUI lets you create a standards compliant simulation of a WSDL based service just from its WSDL contract, which in soapUI is called a “MockService”. This can be run either directly from inside soapUI, with the included command-line runner, or even with a standard servlet container.

The usage scenarios for this are many:

  • Rapid Web Services Prototyping; generate a complete static mock implementation from a WSDL in seconds and add dynamic functionality using Groovy. This allows you to implement and test clients much faster than if you had needed to wait for the actual solution to get build.
  • Client testing or development; create mock implementations of desired operations and set up a number of alternative responses (including scripts, attachments and custom http headers). Clients can be developed against the MockService and tested without access to the live services. Responses can be cycled, randomized or selected with XPath expression from incoming request
  • Test Driven Development; Create Functional and Load Tests in soapUI against a MockService before or during the actual services being implemented

A MockService can simulate any number of WSDL contracts and the built in scripting functionality allows you to simulate basically any kind of desired behavior; fixed responses, random errors, dynamic results, etc. It is even possible to implement an entire service in soapUI and deploy it to a standard servlet container using the DeployAsWar functionality (although not recommended for production use).

A MockService complies with accepted WSDL, SOAP, or HTTP standards and a client should be able to use it just as if it was a real service.


Have multiple API interactions to mock? Try simplified service virtualization with ReadyAPI


1. The MockService model

MockServices provide their service simulation by exposing an arbitrary number of MockOperations which each in turn can contain any number of configured MockResponse messages, thus giving the following model:

  • MockService, contains
    • MockOperations, contains
      • MockResponses

An example MockService in soapUI looks as follows;

Mock Service Structure

Here the MockService contains four MockOperations which each contain a different number of MockResponse messages.

When a SOAP Request is received by the MockService and dispatched to a specific MockOperation, the corresponding MockResponse is selected based on the configured MockRequest Dispatcher, which we will dig in to a little further down in the documentation.

Each MockOperation corresponds to the WSDL Operation of a WSDL Service in your testing project, and the contained MockResponse messages are created from the schema associated with the operation. This doesn’t mean that a MockResponse has to comply with the associated schema, it can return any arbitrary XML or text message and you might for example configure it to return a response message for an entirely different operation, thus allowing you to test your clients’ ability to handle invalid and unexpected response messages.

Creating a MockService is straight forward, easiest is to generate it from an imported WSDL Service via the services’ right-click menu Generate MockService action. The opened dialog allows you to select which operations that should be mocked and which path or port to mount the MockService on:

Generate Mock Service Dialog

The path and port settings control the URL on which the MockService will be available, make sure that the selected port is not already taken by some other server software running on your system.

Quick tip: You can create multiple MockServices on the same port and path, soapUI will ask each in turn to dispatch an incoming request until the request is handled.

After setting the desired configuration and clicking OK, a MockService is added to the project, double-clicking it opens the MockService window:

Mock Service Window

The top contains an Operations tab showing the configured MockOperations, below that is the standard list of tabs for adding a description, properties and a number of scripts that can be used to enrich your mocks functionality:

  • Start Script : called when the MockService is started, use this to initialize any global resources or objects that will be used or part of the test
  • Stop Script: called when the MockService is stopped, use it for cleanups, custom reports, etc.
  • OnRequest Script: called when the MockService receives a request from an external client, use this to provide custom mocking behavior.
  • AfterRequest Script: called after a request to the MockService has been handled, use this for custom data collection or reporting.

The MockService Coverage tab shows Contract Coverage information for requests received by your MockService; see... for more details.

2. Running your MockService

When clicking the Run Button, the MockService is started immediately inside soapUI, you can see this if you click the jetty log tab at the bottom of the soapUI window;

jetty log

The MockService is now ready to handle incoming SOAP requests on the configured path and port. These will be dispatched to the corresponding MockOperation based on their content, if no matching MockOperation is available a standard SOAP Fault will be returned:

Mock Service fault on missing operation

Here we’ve sent a SOAP request to a MockService for an operation that has not been mocked, as indicated by the error.

2.1. Viewing dispatched Messages

The message-log at the bottom shows all messages that have been received by the MockService since it was last started; double-click an entry to see the actual contents of the request and the returned response, for example:

Mock Service log entry

In example above, the first request, [login] was opened to reveal the request and response for the login request.

Quick tip: You can disable the log by unchecking the Enable Option in the Message log viewer if you don’t need the data, This will save both memory and CPU performance.

3. Viewing the exposed contract

As described above, the service immediately starts listening for requests on the configured path and port when started. Additionally it also exposes the WSDL of the MockServic on the standard ?WSDL URL; for example entering http://localhost:8088/mockSampleServiceBinding?WSDL in a browser will show the WSDL:

Exposed WSDL

Please note that a MockOperation can potentially contain MockOperations from two different WSDL contracts, in which case the generated WSDL will be a wrapper WSDL that just imports the WSDLs for all contracts being mocked.

The WSDL exposed also contains the actual http address for the exposed MockService:

Default exposed Mock Service endpoint

If you want to access your MockServices from a remote machine via the WSDL, then this endpoint can be changed in Host field of the MockService options dialog. Renaming it to what you prefer:

Mock Service options: Host field

This results in the following endpoint being exposed in the WSDL:

Fixed Mock Service endpoint

4. MockService Request Dispatching

There are a number of available settings related to how soapUI dispatches incoming messages, all available via the MockService Properties tab in the bottom left:

Mock Service dispatch options

Use them as follows:

  • Match SOAP Version: requires the request to use the same SOAP Version as the configured MockOperation. If it is set to false a SOAP 1.2 request can be dispatched to a SOAP 1.1 MockOperation. You should set this to true if you need strict processing or want to test error handling on incorrect SOAP versions.
  • Require SOAP Action: this option controls if soapUI should inspect the SOAP Action HTTP Header for dispatching to the correct MockOperation as well as in the actual message content. Some clients do not send this header as required, so set this option to true only if you want strict processing or to test your clients’ error handling.
  • Dispatch-Responses: you might want to use the ReplyTo Header in a request when working with WS-Addressing to direct the response to a soapUI MockService. If this is the case soapUI will actually be receiving a response message, which is not supported unless this specific option is set to true, in which case soapUI will dispatch the request as if it was a request for the received response. Further, if the received response is a SOAP Fault, for example via the Fault-To header, an option in the MockService Options dialog is available for telling soapUI how to dispatch this since Fault messages usually are generic:

    MockService fault operation setting

    Select the MockOperation that you want to handle incoming Fault messages.

That's it for MockServices, now head along to the take on MockOperations and Responses!