Developer Guide

Prerequisites:

• Git
• JDK 17 (or higher) (even OpenJDK is fine)
• Eclipse or any Java IDE that supports Maven
  • for example in IntelliJ and NetBeans, you can directly "import" a folder with a pom.xml file in it as a "project", and things will just work
  • if you are behind a proxy, this article may be helpful
• Maven - optional, but recommended - especially to build the JAR-s / binaries

Git Clone:

git clone https://github.com/karatelabs/karate.git

Build

If you just want to build the binaries to test locally, and you have trouble installing (or want to avoid installing) Java and Maven, see Docker.

• change to the karate folder created when you cloned the project from GitHub
• make sure you switch to the right branch. most likely you want to do this:
  • git checkout develop
• to build the maven artifacts locally:
  • mvn clean install -P pre-release -pl -karate-robot
    • the -pl option with a - prefix to karate-robot is to exclude that module from the build, because it will download a lot of large JAR files by default
  • unit tests should never fail and if they do, please do consider debugging and letting us know the fix !
    • but if you get stuck, add -DskipTests at the end of the above command to proceed
  • this will locally "install" the karate-core, karate-junit5 and other Maven output artifacts, and then you can refer to them in a Java project
  • if you are only interested in e.g. karate-junit5, you can save time by doing this:
    • mvn clean install -P pre-release -pl karate-core,karate-junit5
• and finally, make sure that you update the version of the Karate dependencies (typically karate-junit5) in the pom.xml (or build.gradle) that you are testing to match what was just "built"
  • Gradle users will need to point to mavenLocal()

Build Standalone JAR

Note that this is optional if you only need the Maven (or Gradle) artifacts.

• After you ran the above command, change to the karate/karate-core folder
• mvn package -P fatjar
• you will get the JAR in karate/karate-core/target/karate-<version>.jar

Build Standalone Karate Robot JAR

Note that this is optional if you only need the Maven (or Gradle) artifacts.

• change to the karate/karate-robot folder
• edit the pom.xml
  • look for the fatjar profile, and tweak the maven-shade-plugin <exclusions> to only include the "platform" you want to build a JAR for
  • you can run mvn dependency:tree to get a sense of all possible platforms
• run mvn install -P fatjar

Gradle

To develop Karate you need to use Maven. If you are trying to build the karate-demo project and run into issues, please read this.

Docker

The "foolproof" way to build Karate using OpenJDK and Docker goes like this. The best part is you only need Docker to be installed !

Note that the -v "$HOME/.m2":/root/.m2 re-uses your local Maven JAR download "cache" (which saves time), but you can omit it if needed for a true "from scratch" experience. But you most likely should use it, because it makes sure the Java libraries (JAR files) are "installed" locally so that you can refer to them in your maven pom.xml.

If you are on Windows, refer to this for equivalents of the $(pwd) etc.

docker run -it --rm -v "$(pwd)":/src -w /src -v "$HOME/.m2":/root/.m2 maven:3-amazoncorretto-17 mvn clean install -P pre-release -pl -karate-robot,-karate-playwright

Again, if unit-tests fail (they ideally should not, and if you see some that do, please help us fix those !) you can add -DskipTests. This command should work for all Java versions, for e.g. instead of maven:3-jdk-11, use something else

Here is an example if you only want to build karate-junit5:

docker run -it --rm -v "$(pwd)":/src -w /src -v "$HOME/.m2":/root/.m2 maven:3-amazoncorretto-17 mvn clean install -P pre-release -pl karate-core,karate-junit5

To build the stand-alone JAR:

docker run -it --rm -v "$(pwd)":/src -w /src/karate-core -v "$HOME/.m2":/root/.m2 maven:3-amazoncorretto-17 mvn package -P fatjar

Docker Images

The karate-chrome Docker container can be built locally by running the build-docker.sh in the project root folder. Of course you need Docker installed and running.

Once you build the container and if you have made changes, you can (optionally) "tag" it locally if you need to test any code or config that points to the karatelabs/karate-chrome image:

docker tag karate-chrome karatelabs/karate-chrome:latest

Refer to the Docker wiki for more.