WSSimulator is a new open source library that easily allows for you to simulate web service calls and their responses. Useful for when can not (or don’t want to) interact with web services but need to still test these points in your code without mocking objects.

When to use WSSimulator?

  • If you quickly need to serve up static repeatable content over HTTP.
  • In integration tests when real web service calls cannot be made (for example, when the producing service does not yet exist, costs prohibit calling the services within tests or the services are not accessible).
  • If you need to validate the structure of your outbound requests against a schema that an external service will be expecting.
  • To validate that your code can handle service failures.

Modern systems can easily interact with dozens of services

Getting Started

  • Java 8
  • The dependency from JCenter or the Standalone distro
  • Released under apache 2 and you can find the source code on

To simulate web service calls, you first need to describe a simulation. This process is painless as simulations are defined in a YAML format and are heavily opinionated so all you need to provide is simply a path and WSSimulator will default the other options.

Simple Simulation which shows that you only need to supply a path in order to launch WSSimulator
path: /hello
A More complete Simulation
path: /publish
consumes: application/xml
httpMethod: post
badRequestResponseCode: 500
response: <results>ok</results>
requestStructure: <?xml version="1.0" encoding="UTF-8"?>
                   <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
                       <xs:element name="customer" type="customerType"/>
                       <xs:complexType name="customerType">
                               <xs:element type="xs:string" name="name"/>
                               <xs:element type="xs:string" name="address"/>


There are 2 ways to use WSSimulator; as a standalone application or as an embedded library.

In Standalone Mode

WSSimulator is packaged here and supports execution on both *nix & windows systems;

  • For *nix systems
    • Unizip the file to a local directory
    • Then Call:
        ./wssimulator <options>
  • For Windows
    • Unizip the file to a local directory
    • Then Call:
    ./wssimulator.bat <options>

Standalone Example

./wssimulator -y /local/directory
./wssimulator -y /local/directory/simulation1.yml
./wssimulator -p80 -y /local/directory/simulation1.yml
./wssimulator "path:/helloworld"


  • -y Reference to a single yaml simulation file or a directory which will load all *.yml files within the target directory
  • -s Print out a sample YAML Simulation file
  • -p Set the HTTP Port to start the server on (1 to 65535)

Embedded Mode

In addition to standalone mode, WSSimulator can be be used within your java application as a Java dependency. The gateway class is called WSSimulator (same name as the library) and its holds a number of static helper methods that manages the launch of simulations for you.

Dependency Management

WSSimulator is hosted on jcenter

repositories {

    dependencies {
    compile "cognitivej:wssimulator:0.2.5"

Examples when using WSSimulator within your application

Example with JSON/XML Validation
public static void main(String[] args) throws URISyntaxException {
        WSSimulator.addSimulation(new File(ValidationExample.class.getResource("/json/json1.yml").toURI()));
        WSSimulator.addSimulation(new File(ValidationExample.class.getResource("/xml/xmlValidationExample.yml").toURI()));
SOAP Example (Launches valid WSDL & Endpoint Simulations)
public static void main(String[] args) throws URISyntaxException {
        WSSimulator.addSimulation(new File(SOAPExample.class.getResource("/soap/wsdl.yml").toURI()));
        WSSimulator.addSimulation(new File(SOAPExample.class.getResource("/soap/endpoint.yml").toURI()));

Further Examples can be found on here.


WSSimulator will validate request call when not the requestStructure and consumes fields are populated and currently supports XSD & JSON Schema validations. See Tests for validation examples.


WSSimulator can simulate random failures when the resilience field is set below 1 with a 0 value meaning that the simulation will always fail. resilienceFailureCode allows you to set the failure response code. See Tests for more examples.

Assumed Defaults if not passed

Http Port: 4567
Success Status: 201
Bad Request: 400
httpMethod: get
consumes: text/plain
resilience: 1
resilienceFailureCode: 501

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s