Skip to content

Get Started: Other Runtime Options

Peter Thomas edited this page Aug 14, 2024 · 37 revisions

For all the options below, you can use the simple Karate GitHub Template as a sample project.

Standalone JAR

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.

Docker

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 test

For an explanation of the above command, refer: Docker

Docker and the Standalone JAR

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:

  • -it runs in interactive mode, and --rm removes the temporary image after use
  • use -v to mount the ./src folder as /src.
  • use -w to make /src the 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

NPM

There is official Karate support for NPM, this can make it easy to introduce Karate into some CI / CD pipelines.

JBang

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 RELEASE with 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.

Custom Fat JAR

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.