Stubmatic: A Clean and Quick Way to Create Simulators

Stubmatic is an NPM repo which runs on your machine/server as separate service. It helps to stub any HTTP(s) call. So you can use it to stub RESTful or SOAP web services.

It is

• Easy to install:

   npm install stubmatic -g 

• Easy to set up:

   stubmatic init  

• And easy to start:

   stubmatic [-v] 

The basic simulator project can be set up in less than five minutes.

Suppose your project is making a call to some REST or SOAP based web service. There is a possibility that those web services are not ready to test, or they don’t have stubbed data which is required by your project to test all positive and negative scenarios. Many times, they can’t be used because of the 24x7 availability of servers or a particular version of those web services. Hence we are required to create simulators.

Because creating and maintaining simulators is a must-have for every project, but their effort is always ignored,Stubmatic is developed in a way that can really reduce this effort. You need not have any coding knowledge, just experience in the syntax ofStubmatic features and basic knowledge of regular expressions.

How it Works

To create a Stubmatic based simulator, you need to create a request-response mapping YAML file. You can break it into multiple YAML files, use default mappings, or use short notations to keep them small and organized.

Sample SOAP Request Mapping

-  request:
     method: POST
     url: /soap-simulator/services/ServiceName
     post: actionName[\s\S]*mobile.([0-9]+)
  response:
     headers:
           content-type: text/xml
     strategy: "first-found"
     files: ["stubs/<% post.1 %>/response.xml","stubs/ServiceName/actionName/default.xml"]

Sample REST Request Mapping

-  request:
     method: GET
     url: /rest-simulator/services/ServiceName/actionName/([0-9]+)
  response:
     headers:
           content-type: text/xml
     strategy: "first-found"
     files: ["stubs/<% url.1 %>/response.xml","stubs/ServiceName/actionName/default.xml"]

You can use default mapping to avoid commonly repeated parts in every mapping;

-  request:
     url: /rest-simulator/services/ServiceName/actionName/([0-9]+)
  response:
     files: ["stubs/<% url.1 %>/response.xml","stubs/ServiceName/actionName/default.xml"]

Let’s dive into the above mappings.

Suppose your project is making a request to some web service. You can specify that URL in mapping. Now either you can map one response for one request as follows:

-  request:
     url: /rest-simulator/balance/7123456789
  response:
     file: responses/7123456789.json

-  request:
     url: /rest-simulator/balance/7123456799
  response:
     file: responses/7123456799.json

Or you can have just one entry where you select the response file at runtime:

-  request:
     url: /rest-simulator/balance/([0-9]+)
  response:
     file: responses/<% url.1 %>.json

Sometimes, you may want to serve the default response when a response file for any mobile number is missing;

-  request:
     url: /rest-simulator/balance/([0-9]+)
  response:
     files: ["responses/<% url.1 %>.json","responses/default_balance.json"]

The above case serves default_balance.json when the first response file doesn’t exist. This is called the “first-found” strategy. There are few more strategies to select the response file at runtime.

You can capture some information from a request URL, body, or headers. You can use this captured information to select a response file dynamically or inside the response file to make the response dynamic, as shown in the above code snippet.

Features

You can either map request with some text:

-  request:
     url: /rest-simulator/healthcheck
  response:
     body: OK

Or with a file as mentioned in the above section. If it is a file, then the mapped response file can be simple text, XML, JSON, or anything else. You can specify the contentType attribute in the mappings to serve them as a file instead of part of the response body.

-  request:
     url: /rest-simulator/status
  response:
     file: responses/working.json
     contentType: application/json

In case you use some incorrect regular expression to match a request, there are many ways to debug. You can specify the -v argument while running Stubmatic to see on-screen logs, or you can specify the --logs argument to create log files. You can also use the debug=true query parameter while requesting the simulator. It gives you more detail about which mapping it matched to, the request URL, body and header parameters, etc.:

stubmatic [-v] [--logs] 

For a quick help:

stubmatic --help 

You can change the status code to any valid code: 200, 404, 500, etc.

You can use fixed or random latency to delay the response to test some negative scenarios or for performance testing.

-  request:
     latency: [500,800]
     status: 500
     url: /rest-simulator/status
  response:
     file: responses/not-working.json
     contentType: application/json

If the request goes to the Stubmatic based simulator with compression headers, then Stubmatic can respond back compressed output. Currently, it supports gzip and deflate responses. It is not applicable if you want to respond to  a file from the simulator.

You can keep the workspace more organized using dumps and DB sets. Dumps are like any ordinary file that can be included in other files. DB sets are value tables, which can be filled in response. These two together let you create a perfect response skeleton.

There is some basic support of markers and functions. So, for an instance, if you want to display some date (today, tomorrow, future, past) in a response, use something like:

-  request:
     url: /rest-simulator/dueDate/[0-9]+
  response:
     body: {{formatDate(TODAY+1m-2d,"YYYY/MM/dd")}}

You can see the complete list here.

There are many other features to mention. You can learn about them and other upcoming features from the GitHub repo. And for more information, here are some useful links to get you started: sample application, wiki, GitHub, Slideshare, QA.