Karate OAS Demo

Summary

• a “smart” mock that can validate request payloads against the OAS
• old versions of the OAS or Swagger files are also supported
• custom rules can be added - e.g. upperLimit <= lowerLimit
• you can tweak behavior or vary the response based on state (or stage within an end-user flow)
• mock should run "locally" (localhost)
• mock can be easily included within a CI / CD pipeline

Prerequisites

This is a normal Java / Maven project. Java 11 is required.

If you want to generate the spec.js for other Open API or Swagger spec files, you need a PRO licence of the Karate Labs IntelliJ plugin.

Demo 1 - Petstore

OAS file: https://petstore3.swagger.io

• test.feature - This is the user flow as a Karate test
  • Note that it has a "full cycle": create (POST), read (GET), update (PUT), remove (DELETE)
  • The same test can be used as-is against a "real" implementation of the server, by switching the URL
• petstore.js - This is the machine-generated mock file that encodes all the information from the Open API spec file petstore.yaml
  • All request payloads have been converted into Karate schema validators
  • Examples for all response payloads have also been created from the OAS spec
• rules.js - This is the part written by hand, but simple and just a few lines
  • note how it over-rides behavior for 2 paths, /pet and /pet/{petId}
  • this adds state-awareness to the mock, for example the GET will return what was POST-ed in a previous call
  • Note how the status code is handled for a DELETE (201) and a not-found scenario (404).
  • There is no-limit to the logic you can add, as long as you are willing to write some simple JS
  • Since rules.js is de-coupled, you can re-generate the core petstore.js from the OAS file whenever it changes
• mock.js - This is the "entry point" for the mock. This code is "generic" and can be the same for any Open API or Swagger file. Note that Karate JavaScript mocks are being used (not the *.feature file based approach). The first line points to petstore.js and can be customized if needed.

Running

Just execute ApiRunner as a JUnit test. It invokes the mock.js entry point.

Here is the result. Note how you can view the flow of multiple API calls, human-friendly comments and the details of the HTTP request and response.

Demo 2 - ASTM UTM

• OAS spec: https://github.com/astm-utm/Protocol/blob/master/utm.yaml

• test.feature

  • Here the test makes 2 calls, but one with a request payload that fails a business rule

• spec.js - This is the machine-generated mock file

• rules.js

  • we implemented a cross-field validation which is concisely represented in JS as follows:
    • if (altitude_lower.value >= altitude_upper.value) errors.push('altitude_lower should be lower than altitude_upper')

Running

Just execute ApiRunner as a JUnit test. Note how the second call failed with a readable error message.

Demo 3 - Travel "Flow"

Similar to the Petstore demo, this shows how a sequence of API calls can be documented.

• test.feature
• rules.js

What is interesting here is the human-friendly HTML that can be added to the report to describe the API further. The HTML templates (offers-get.html and orders-post.html) can dynamically refer to the HTTP response or any variable in the test.

Demo 4 - Oracle Hospitality

Swagger file: https://github.com/oracle/hospitality-api-docs/blob/main/rest-api-specs/property/rsv.json

• test.feature
• spec.js - machine-generated mock file
• rules.js

Further Reading

• API Contract Testing - Visual Guide