And Consumer Driven Contracts made easy.

• Super-easy 'hard-coded' mocks (example)
• Stateful mocks that can fully simulate CRUD for a micro-service (example)
• Easy HTTP request matching by path, method, headers etc.
• Use the full power of JavaScript expressions for HTTP request matching
• SSL / HTTPS with built-in self-signed certificate
• Forward HTTP requests to other URL-s (URL re-writing)
• Usable as a standard HTTP proxy server - simplifying configuration set-up for consuming applications
• Start and stop mock servers in milliseconds
• Super-fast HTTP response times (~20ms) for typical in-memory CRUD / JsonPath (as long as you don't do I/O)
• Thread-safe - use concurrent consumers or async flows without fear
• Easy integration into Java / JUnit test-suites via API
• Server can dynamically choose free port
• Think of it as a scriptable 'API gateway' or 'AOP for web-services' - insert custom functions before / after an HTTP request is handled
• Just one file can script the above aspects, simplifying the mental-model you need to have for advanced scenarios such as Consumer Driven Contracts
• Easily integrate messaging or async flows using Java-interop if required
• Enables consumer or even UI dev teams to work in parallel as the provider service is being developed
• Stand-alone executable JAR (10 MB) which only requires a JRE to run, ideal for web-developers or anyone who needs to quickly experiment with services.
• Built-in CORS support for the ease of web-dev teams using the mock service
• Option to use an existing certificate and private-key for server-side SSL - making it easier for UI dev / browser consumers in some situations
• Configure a 'global' response header routine, ideal for browser consumers to add headers common for all responses - yet dynamic if needed
• Provider service dev team can practice TDD using the mock + contract-test
• The mock + contract-test serves as the ultimate form of documentation of the 'contract' including payload / schema details.

For the last point above - Karate will have Spring REST Docs support built-in in the future, please help contribute to completing this if you can !

This documentation is work in progress while this project evolves. But here is an end-to-end demo that should provide sufficient detail for those interested.

Note that you can use this as a stand-alone JAR executable which means that you don't even need to compile Java or use an IDE. If you need to embed the mock-server into a JUnit test, you can easily do so.

Note that this includes the karate-apache dependency for convenience.

<dependency>
    <groupId>com.intuit.karate</groupId>
    <artifactId>karate-netty</artifactId>
    <version>${karate.version}</version>
    <scope>test</scope>
</dependency>  

We use a simplified example of a Java 'consumer' which makes HTTP calls to a Payment Service (provider) where GET, POST, PUT and DELETE have been implemented. The 'provider' implements CRUD for the Payment.java 'POJO', and the POST (or create) results in a message (Shipment.java as JSON) being placed on a queue, which the consumer is listening to.

ActiveMQ is being used for the sake of mixing an asynchronous flow into this example, and with the help of some simple utilities, we are able to mix asynchronous messaging into a Karate test as well as the test-double.

Karate mocking a Queue has not been implemented for the last two flows (5) but can easily be derived from the other examples. So in (5) the Consumer is using the real queue.

It is worth calling out why Karate on the 'other side of the fence' (handling HTTP requests instead of making them) - turns out to be remarkably effective, yet simple.

• 'Native' support for expressing JSON and XML payloads
• Embedded Expressions are perfect for those parts of the payload that need to be dynamic, and JS functions can be 'in-lined' into the JSON or XML
• Manipulate or even transform payloads
• Validate payloads, using a simpler alternative to JSON schema if needed
• Karate is all about making HTTP calls, giving you the flexibility to call 'downstream' services if needed
• In-memory JSON and JsonPath solves for 'state' and filtering if needed
• Mix custom JavaScript (or even Java code) if needed - for complex logic
• Easily 'seed' data or switch environment / config on start
• Read initial 'state' from a JSON file if needed

If you think about it, all the above are sufficient to implement any micro-service. Karate's DSL syntax is focused on exactly these aspects, thus opening up interesting possibilities. It may be hard to believe that you can spin-up a 'usable' micro-service in minutes with Karate - but do try it and see !

Karate-Netty is available as a single, executable JAR file, which includes even the karate-apache dependency. This is ideal for handing off to UI / web-dev teams for example, who don't want to mess around with a Java IDE. All you need is the JRE (at least version 1.8.0_112 or greater).

You can download the latest version of this JAR file from Bintray, and it will have the name: karate-netty-<version>-all.jar.

Tip: Rename the file to karate.jar to make the commands below easier to type !

You can view the command line help with the -h option:

java -jar karate-netty-<version>-all.jar -h

To start a mock server, the 2 mandatory arguments are the path of the feature file 'mock' -m and the port -p

java -jar karate-netty-<version>-all.jar -m my-mock.feature -p 8080

For SSL, use the -s flag. If you don't provide a certificate and key (see next section), it will automatically create cert.pem and key.pem in the current working directory, and the next time you re-start the mock server - these will be re-used. This is convenient for web / UI developers because you then need to set the certificate 'exception' only once in the browser.

java -jar karate-netty-<version>-all.jar -m my-mock.feature -p 8443 -s

If you have a custom certificate and private-key (in PEM format) you can specify them, perhaps because these are your actual certificates or because they are trusted within your organization:

java -jar karate-netty-<version>-all.jar -m my-mock.feature -p 8443 -c my-cert.crt -k my-key.key

Convenient to run a standard Karate test on the command-line without needing to mess around with Java or the IDE ! Great for demos or exploratory testing.

Note that if you are depending on external Java libraries or custom code to be compiled, this won't work.

java -jar karate-netty-<version>-all.jar -t my-test.feature

If your test depends on the karate.env environment 'switch', you can specify that using the -e (env) option:

java -jar karate-netty-<version>-all.jar -t my-test.feature -e e2e

If karate-config.js exists in the current working directory, it will be used. You can specify a full path by setting the system property karate.config. Note that this is an easy way to set a bunch of variables, just return a JSON with the keys and values you need.

java -jar -Dkarate.config=somedir/my-config.js karate-netty-<version>-all.jar -t my-test.feature

And you can even set or over-ride variable values via the command line by using the -a (args) option:

java -jar karate-netty-<version>-all.jar -t my-test.feature -a myKey1=myValue1 -a myKey2=myValue2

The 'default' command actually brings up the Karate UI. So you can 'double-click' on the JAR or use this on the command-line:

java -jar karate-netty-<version>-all.jar

You can also open an existing Karate test in the UI via the command-line:

java -jar karate-netty-<version>-all.jar -u -t my-test.feature

A default logback.xml is present within the stand-alone JAR. To customize logging, set the system property logback.configurationFile to point to your custom config:

java -jar -Dlogback.configurationFile=my-logback.xml karate-netty-<version>-all.jar -t my-test.feature

Here is the 'out-of-the-box' default which you can customize.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
  
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>karate.log</file>
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>    
   
    <logger name="com.intuit.karate" level="DEBUG"/>
   
    <root level="warn">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>
  
</configuration>

Writing a mock can get complicated for real-life API interactions, and most other frameworks attempt to solve this using declarative approaches, such as expecting you to create a large, complicated JSON to model all requests and responses. You can think of Karate's approach as combining the best of both the worlds of declarative and imperative programming. Combined with the capability to maintain state in the form of JSON objects in memory, and Karate's native support for Json-Path, XML and embedded expressions - you have a very powerful toolkit at your disposal. And Karate's intelligent defaults keep things dead simple.

The Karate 'server' life-cycle is simple and has only 2 phases - the Background and Scenario. You can see that the existing Gherkin format has been 're-purposed' for HTTP request handling. This means that you get the benefit of IDE support and syntax coloring for your mocks.

Refer to this example: demo-mock.feature.

This is executed on start-up. You can read files and set-up common functions and 'global' state here. Note that unlike the life-cycle of 'normal' Karate, the Background is not executed before each Scenario.

A server-side Feature file can have multiple Scenario sections in it. Each Scenario is expected to have a JavaScript expression as the content of the Scenario description.

On each incoming HTTP request, the Scenario expressions are evaluated in order, starting from the first one within the Feature. If the expression evaluates to true, the body of the Scenario is evaluated and the HTTP response is returned.

It is good practice to have the last Scenario in the file with an empty description, (which will evaluate to true) so that it can act as a 'catch-all' and log or throw an error / 404 Not Found in response.

A map-like' object of all query-string parameters and the values will always be an array. Use the convenience built-iun function paramValue(name) which is convenient as it will return a single (string) value if the size of the array is 1, which is what you need most of the time.

Refer to this example: payment-service-proxy.feature.

Refer to this example: payment-service-proxy.feature.