Get Started: Other Runtime Options
For all the options below, you can use the simple Karate GitHub Template as a sample project.
All of Karate (core API testing, parallel-runner / HTML reports, mocks and web / UI automation) is available as a single, executable JAR file.
The only pre-requisite (if not using jbang) is the Java Runtime Environment. Note that the "lighter" JRE is sufficient, not the full-blown JDK (Java Development Kit). There is a good chance that you already have it installed. You can confirm this by typing java -version on the command line. Java version 17 or above is required.
Refer to the first part of this video for how to install Java: Karate Kick Start - The TODO Sample and Demo Project
Look for the latest release on GitHub and scroll down to find the "Assets". Look for the file with the name: karate-<version>.jar. Download it to the root of your project folder, and rename the file to karate.jar to make commands easier to type.
You can view the command line help with the -h option:
java -jar karate.jar -h
To run a feature (if you need a quick, short demo, use httpbin.feature):
java -jar karate.jar httpbin.feature
Reports can be found in target/karate-reports/, the main file is karate-summary.html.
You can run all tests within a directory if you provide a directory path:
java -jar karate.jar some/folder
You can have multiple features (separated by spaces) or even folder paths as the last part of the command. Karate will run all feature files found in sub-directories. You can even run tests in parallel.
For a complete description of all command line options, refer to: Usage. You can also customize or add more JAR files to the classpath or set up a batch file for convenience.
Wrapping Karate into a Docker container is simple, most teams just base off a Maven container.
If you already have a Maven project, this is how you can run tests without installing Java or Maven, and all you need is Docker installed:
docker run -it --rm -v "$(pwd)":/src -w /src -v "$HOME/.m2":/root/.m2 maven:3-amazoncorretto-17 mvn testFor an explanation of the above command, refer: Docker
This simple minimalistic Dockerfile is sufficient to package a Java Runtime Environment and the Karate Standalone JAR.
Here we are using an eclipsetemurin Docker image as a base.
FROM eclipse-temurin:17-jre
RUN curl -L -o karate.jar https://github.com/karatelabs/karate/releases/download/v1.5.0/karate-1.5.0.jar
The Docker recipe is very simple, just download karate.jar into the root of the docker image. To build a docker image called karate-jre locally, you can do this:
docker build -t karate-jre .Now to run a set of Karate tests in a src folder within the current directory (outside the docker image) you can do this:
docker run -it --rm -v "$(pwd)/src":/src -w /src karate-jre java -jar /karate.jar .If you are on Windows, refer to this for equivalents of the $(pwd) etc.
The explanation of the above command is as follows:
-
-itruns in interactive mode, and--rmremoves the temporary image after use - use
-vto mount the./srcfolder as/src. - use
-wto make/srcthe working directory - now the command
java -jar /karate.jar .will run all feature files in the current folder (which is.) - note that test reports will appear in
./src/target
All the possible Karate command-line options are explained here: Usage.
You can easily customize the above recipe, for example you could bundle your tests within the docker image. One nice thing about the above example is that the test reports are created outside the image, so you can view them even after the docker process stops.
There are some tips, tricks and recipes in this thread: https://github.com/karatelabs/karate/issues/396
There is official Karate support for NPM, this can make it easy to introduce Karate into some CI / CD pipelines.
- First install npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
- Then follow the instructions here: karate-npm
Note that you can easily run Karate or even install applications based on Karate using jbang. It will take care of setting up a local Java runtime, which is really convenient. Note that jbang itself is super-easy to install and there is even a "Zero Install" option.
With jbang installed, you can do this (since a jbang-catalog.json is present within the karatelabs/jbang-catalog GitHub repository :
jbang karate@karatelabs -h
What's really interesting is that you can install karate as a local command-line application !
please replace
RELEASEwith the exact / version of Karate you intend to use if applicable
jbang app install --name karate io.karatelabs:karate-core:RELEASE:all
And now the command karate will be available in your terminal (after opening a new one or having re-loaded environment settings).
Which would make using Karate as easy as this !
karate -h
You can script complex automation, using the Java API that Karate makes available. So if you have a file called myscript.java written as a jbang script, you can install it as a system-wide command called myscript like this:
jbang app install --name myscript myscript.java
Refer to the JBang example for how to add extra Java libraries to the classpath. Refer to the jbang documentation for more options.
Some teams need the convenience of the Standalone JAR but also need to customize the classpath by adding Java libraries or more commonly by adding custom Java code which has been compiled. The recommendation is that a Maven project should be used for preparing a single binary. When this Maven project is "built" - the resulting artifact can be distributed to teams that don't want to use Maven or compile Java. A typical use-case is a team that prefers to use karate-npm or a front-end team that works on JavaScript or Typescript but needs to run Karate API mocks to support development.
A Maven project that emits a single "fat jar" that includes all custom code and transient dependencies is easy using the Maven shade plugin. Typically the "shade" setup is configured as a Maven profile. Here is a very simple example that fits within the root <project> tag of the pom.xml:
<profiles>
<profile>
<id>fatjar</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<finalName>karate-fat</finalName>
<artifactSet>
<includes>
<include>*:*</include>
</includes>
</artifactSet>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.intuit.karate.Main</mainClass>
</transformer>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>To build the "fat jar" for the above example:
mvn package -P fatjar
This will result in target/karate-fat.jar being created. You can easily configure a different name. This JAR file requires only a JRE to run (not the full-blown JDK) and you can easily prepare a Docker container embedding both - for ease of use.
