This is a sample Spring Boot web-application that exposes some functionality as web-service end-points. And includes a set of Karate examples that test these services as well as demonstrate various Karate features and best-practices.
Note that this is not the best example of a skeleton Java / Maven project, as it is designed to be part of the Karate code-base and act as a suite of regression tests. For a good “starter” project, please use one of these:
| ||Simple GET requests and multiple scenarios in a test.|
| ||Multiple examples of header management including dynamic setting of headers for each request using a JS file ( |
| ||HTML form POST example. Typically you use the response to get an authentication token that can be used to build headers for subsequent requests. This example also demonstrates getting past an end-point protected against CSRF.|
| ||Great example of embedded-expressions (or JSON / XML templating). Also shows how to set the |
| ||Reading a complex payload expected response from a file. You can do the same for request payloads as well.|
| ||The above example reads a file with embedded expressions and this one reads normal JSON and XML for use in a |
| ||GraphQL example showing how easy it is to prepare queries and deal with the highly dynamic and deeply nested JSON responses - by focusing only on the parts you are interested in|
| ||Multi-part file-upload example, as well as comparing the binary content of a download. Also shows how to assert for expected response headers. Plus an example of how to call custom Java code from Karate.|
| ||How to easily use Java interop to make a JDBC / database call from a Karate test. Here is the utility-class code - which depends on Spring JDBC: |
| ||Another example of how to call Java code showing how you can pass JSON data around.|
| ||Karate’s simpler approach to schema-validation compared with an actual JSON-schema example taken from json-schema.org. If you really want to perform JSON-schema validation, this example shows you how you can easily do so using Java interop and the json-schema-validator, but should you really ?|
| ||Along with |
| ||Examples for both SOAP 1.1 and 1.2, also showing how you can read request payloads and even expected response XML from files. Note that examples of how to manipulate XML are linked from the main documentation - for example this one: |
| ||Multiple examples of data-driven testing including using a |
| ||The Karate enhanced |
| ||Using CSV for a data-driven dynamic scenario outline.|
| ||So you like Karate’s data-driven and assertion capabilities ? Try Karate for unit testing Java code ! You can re-use the glue code in multiple tests.|
| ||How you can re-use a sequence of HTTP calls in a |
| ||This example loads JSON data from a file and uses it to call a |
| ||This is a great example of how Karate combines with Cucumber and JsonPath to give you an extremely readable data-driven test. Karate’s |
| ||Shows how to dynamically create a JSON array and then use it to call a |
| ||Cucumber has a limitation where |
| ||How to write websocket tests, also see |
| ||If you need to call a Karate test from Java code you can do so using the Java API. This is useful in some situations, for example if you want to mix API-calls into a Selenium / WebDriver test.|
| File | Demonstrates ———-| ——–
karate-config.js | Shows how the
readTimeout so that your tests ‘fail fast’ if servers don’t respond. For advanced users - you can even run a ‘global’ init routine using
karate-config-contract.js | When your project gets complex, you can over-ride config per environment (
karate.env). Refer to the documentation on environment specific config.
TestBase.java | This is specific to Spring Boot, but this code takes care of starting the embedded app-server and dynamically chooses a free port. The chosen port value is passed to the above config routine via a Java
DemoTest.java | This Java class is strategically placed at the root of the directory structure containing
*.feature files. Note how the
@KarateOptions annotation allows you to skip any
*.feature files if they have
@ignore at the start.
DemoTestParallel.java | Karate has a utility to run tests in parallel and this does not depend on JUnit, TestNG or even Maven. A JUnit XML report file and Cucumber JSON report file would be generated for each feature executed. You can easily configure your CI with the location of these files so that you get proper test-reports after a build. This is the recommended way of running Karate as part of an automated build or CI pipeline. Here, the (optional) third-party cucumber-reporting library is being used (see details below).
pom.xml | Look out for how the
maven-surefire-plugin can be configured to point to what is basically your ‘test-suite’. You may not even need to do this if you follow the recommended naming conventions and folder structure, and then Maven defaults would work as you would expect. Note that this demo application has many dependencies that you will not need for a typical Karate project.
To generate the Gradle wrapper (as is usual for Gradle):
After that use the Gradle wrapper to run the tests:
This is optional and if you use the parallel runner as described above, the JUnit XML emitted is sufficient for most CI tools (e.g. Jenkins) to generate test reports and determine whether the build passed or failed. But the advantage of the approach below is that it includes HTTP request and response logs in-line with the report (see video).
Since the maven-cucumber-reporting plugin has an issue where reports will not be generated if the build fails, we recommend that you directly use the cucumber-reporting library programmatically in combination with the Karate parallel runner. Here is how:
net.masterthought:cucumber-reporting jar as a dependency in
<dependency> <groupId>net.masterthought</groupId> <artifactId>cucumber-reporting</artifactId> <version>3.8.0</version> <scope>test</scope> </dependency>
If you don’t already have log4j (v2) in the mix, place this minimal config on the classpath as
log4j2.properties (in the same folder as
log4j.rootLogger = INFO, CONSOLE log4j.appender.CONSOLE = org.apache.log4j.ConsoleAppender log4j.appender.CONSOLE.layout = org.apache.log4j.PatternLayout
Refer to the code in the demo:
DemoTestParallel.java, specifically the
And here is the output, which goes into
target/cucumber-html-reports if you follow the above steps:
This report is recommended especially because the HTTP request and response payloads are embedded. You can even see the results of
pom.xml, code coverage using Jacoco is also demonstrated. Since this is set-up as a Maven profile, instrumentation and code-coverage reporting would be performed only when you use the
coverage profile. Note that code-coverage data (binary) would be saved to this file:
So to run tests and perform code-coverage:
mvn clean test -Pcoverage
And the HTML reports would be output to
As this demo example shows - if you are able to start your app-server and run Karate tests in the same JVM process, code-coverage reports for even HTTP integration tests will be very easy to generate. This is even easier with the karate-mock-servlet as you don’t even need to boot an app-server.
You should be able to use the same approach for other platforms. Note that there are plenty of ways to start a Karate test via the command-line, such as the standalone JAR.