How to Submit an Issue

Stuck ? Or found a bug ?

If something is not working the way you expect and you have failed to get any satisfactory responses on Stack Overflow or other community channels, it is quite likely that you have not provided enough information for others or for the project developers to understand the issue and help you. Note that screenshots and videos are typically not useful - we need working code.

In such cases, the best way to get help and solve your problem is to file an issue and include a Minimal, Complete and Verifiable example.

Instructions

• use the Maven quick-start to create a skeleton project
  • if you use Gradle, please use the build file from this wiki page (and use the folder-structure and files from the Maven quick-start)
  • for Gatling: you can choose to use the examples/gatling project as a base
  • for UI / web-browser automation: use the examples/ui-test project as a base
  • if using the standalone JAR, use the ZIP Release as a base - you can remove the JAR file to reduce the size, but please mention the exact version number
• modify the freshly created project to demonstrate the issue. make sure it is Minimal, Complete and Verifiable (please refer to this link). Feel free to delete the content in the quick-start demo feature file and re-use only the parts you really need, for convenience
• "Minimal" also means that your pom.xml (or build.gradle) should ideally be in the form generated by the quickstart or copied from the examples, many people get this wrong - so please ensure that you do this ! Please don't just cut and paste your existing pom.xml - your issue will be promptly rejected
  • you can add one or two libraries only if you are sure that you are facing a problem integrating some 3rd party API - but this is highly unlikely
  • and please don't add any extra maven plugins without good reason, they can be the source of problems
• make sure that the project does not contain information such as private URL-s, passwords or data that you don't want to make public
  • public test API-s such as httpbin.org, postman-echo and jsonplaceholder.typicode.com can be used to simulate specific HTTP scenarios
  • for more complex scenarios, we recommend that you use Karate mocks, and here is a detailed guide (no Java knowledge is required)
  • or you can choose to copy parts of the karate-demo project, see this excellent example
• compress the project into a single ZIP file (or alternatively check it into a public GitHub project or equivalent)
• while creating a ZIP file, make sure the target ( or build) folder is not included or empty by doing: mvn clean (or gradle clean) - or if using the stand-alone JAR, you can use the -C command-line option
• and also please don't include IDE specific files such as .project, .classpath, .settings, .idea, .vscode etc.
• file an issue and attach the ZIP file (or link to the public project)
• provide a clear description of the issue and what the expected behavior is
• please provide the exact command to run and reproduce the problem locally - this is very important !
  • e.g. mvn clean test or mvn clean test -Dtest=TestRunner

FAQ

Why should I submit a working Maven (or Gradle) project ?

Especially when the issue reported involves the inter-play of multiple feature files, JSON and karate-config.js, the only way to be sure about what's going on is for the entire flow to be replicated. This is also important to ensure that the issue is not because of an old version of Karate being used, or because a library dependency conflict is causing the problem (which very often is the case). It makes it much easier for the project developers to replicate your issue (and confirm that it is fixed) when a full, working Java / Maven project is submitted. It also makes it easier for you, because you don't have to waste time explaining what could be most effectively communicated via a working example.

That said, if the problem can be demonstrated in a single snippet of Karate-script (which we can just cut, paste and run - and no external variables or files are needed), you can try submitting an issue without the quick-start. The project developers would let you know if it is sufficient or not.

This is also to help you. It is quite likely that when you focus on replicating the problem in a fresh project, and boil things down into a minimal example, you will quickly figure out what may have been a simple mistake or an issue with your environment.