1.0 upgrade guide

Preview Versions

0.9.9.RC4 (2021-02-09)

available on Maven Central
ZIP / JAR downloads
please plan some time (e.g. one sprint) in Feb 2021 to upgrade your existing test-suites as there will be some breaking changes
the more feedback you can provide earlier, the better !
while we stabilize this release, use this common issue thread to comment / keep track of things:
- https://github.com/intuit/karate/issues/1373
to keep track of releases use these options
- follow the project on twitter: https://twitter.com/KarateDSL
- join the LinkedIn group: https://www.linkedin.com/groups/10448828/

Build from Source

follow the developer guide and build from the develop branch

Improvements

Also see this article by Peter Quiel: 7 New Features in Karate Test Automation Version 1.0.

Support for all Java versions 8 and above

Achieved by moving to the Graal VM JS engine. This was a big risk we were facing when Oracle deprecated Nashorn which Karate was using extensively.

We have tested Karate on even Java 16 and it works ! Along with this migration, we were also able to clean up the code significantly - which means that Karate is well set to be around for a long, long time !

ECMAScript 2015 / ES6 - most notably the arrow operator

ES6 arrow functions
string interpolation within back-ticks
JS array behavior e.g. Array.map(), note that karate.map() is still an option

Improved error details for match failures

each level of the payload is reported as well-formed JSON (to make cutting and pasting easier)
JSON keys will be sorted so that the payloads "line up" as far as possible - which makes it easier to eyeball
the Json-Path (or XPath) of each "level" appears on the left, with a clear description of the mis-match

Improved error details for JavaScript failures

Yes we know. Especially for failures where karate-config.js was involved, the log messages could be woefully inadequate in some cases. That's a thing of the past now, with details of the JS source and feature names + line numbers.

Improved test-suite builder

the improvements to the Runner.builder() are subtle but you are likely to enjoy:

no more relying on System.setProperty()
set karate.env
set even the location of the karate-config.js
and even set system properties per test-suite
the goal here is to allow you to run 2 instances of karate.env in parallel if you wish

Multi-Part request details will appear in the HTML report / logs

No more guesswork as to what that multi-part request was doing behind the scenes. MIME message names, Content-Type headers and payload sizes displayed for each "part".

Playwright Support

see: https://twitter.com/ptrthomas/status/1307678474627244032

Java API

This means you can choose to use Java instead of Gherkin, and still get the benefits of Karate's rich HTTP, JSON, Match (assertions) and Driver (browser automation) capabilities.

Note that you will sacrifice some of the test-automation domain capabilities of Karate, such as HTML reports with in-line logging, and parallel-execution. But this is an option that may appeal to passionate Java developers who would like to mix and match with other frameworks such as TestNG. Some areas need more work, such as being able to re-use Java tests as performance tests, so please contribute if you can.

JS Functions for Data Driven Testing

see: https://twitter.com/KarateDSL/status/1343201222396821504

Distributed Testing

see: https://github.com/intuit/karate/wiki/Distributed-Testing

HTML Templating

see: https://twitter.com/KarateDSL/status/1338892932691070976 example: axe.feature

App Server (experimental)

see: https://twitter.com/ptrthomas/status/1338797269844312064

Retry Framework (experimental)

With some custom Java code you should be able to take any failed tests at the end of a Runner invocation and re-try them, and merge the results back into the final aggregated report. See example code.

Single Dependency

The karate-core Maven artifact contains everything you need, including the Apache HTTP Client which used to be a separate dependency. This simplifies certain use-cases, the one we are most excited about is being able to use jbang - and here are some examples of what is possible.

Note that Karate now bundles an HTTP Client, HTML templating, HTTP app-server, REST server, CLI executor and even web-browser automation into one mighty package - which opens up some very interesting automation possibilities.

Don't forget that Karate has additional dependencies for performance testing, mocking Java servlets and Windows desktop app automation as well.

Breaking Changes

Overall, it is quite likely that your API tests will run just like before, but see details of possible behavior changes.

Java Projects

only a single maven dependency is needed, karate-apache and karate-jersey do not exist any more
- which means that you need only karate-junit5 (or karate-junit4, or just karate-core if you don't want JUnit at all, see single dependency)
- so just remove the extra dependency from your pom.xml (typically karate-apache)
- Karate will include the Apache HTTP Client by default, but we "maven shade" it so that you never run into library conflicts
HTML reports (and other artifacts) will be in target/karate-reports (or build/karate-reports for Gradle)
- so if your CI was pointing to <build-dir>/surefire-reports, this has to be changed
the @KarateOptions annotation will be removed in the next version and has been marked as "deprecated"
- so try to switch to the Runner (example below)
the Cucumber JSON and JUnit XML files are NOT output by default
- use the builder methods on the Runner, there is also outputJunitXml(true)

        Results results = Runner.path("classpath:demo")
                .outputCucumberJson(true)
                .tags("~@ignore").parallel(5);

Standalone JAR

HTML reports (and other artifacts) will be in target/karate-reports (not target/cucumber-reports or target/surefire-reports)
The cucumber-reporting library is no longer used (the HTML report is Karate's built-in one)
The Cucumber JSON and JUnit XML are not generated by default, use -f cucumber:json or -f junit:xml (or both at the same time, comma-delimited works)

Mocks

a.k.a. karate-netty - the Java API to start a mock has changed / see diff
the CLI to start a mock is unified with karate-core (there is no more karate-netty)
so this will work: java -jar karate.jar -m mock.feature
the -w or --watch option is removed
you can even use the karate-core maven artifact via jbang, see this example
"Proxy Mode" or intercepting HTTPS does not work (but used to), refer open Armeria issue: https://github.com/line/armeria/issues/3168 - please contribute if you can !

Hooks

if you used the ExecutionHook it has API changes. now it is RuntimeHook and ScenarioContext has become ScenarioRuntime

To see an example (part of a larger example including Gradle, Gatling etc. by Kirk Slota) see this file KarateHook.

Mock Servlet

karate-mock-servlet has been re-factored to use a new HttpClientFactory abstraction.
- see diff 1
- see diff 2

Karate UI

the (rarely used) driver.dialog "getter" API that gets you the text content of a browser-native pop-up has been renamed to driver.dialogText

Other

if you were one of the rare few who implemented (or extended) a custom HttpClient - it has been refactored to be simpler, look at ArmeriaHttpClient as an example

Async

If you have async tests and are passing JS functions to Java listeners (e.g. message queues, gRPC) you need to use the new karate.toJava() API to "wrap" the function so that it is compatible with the JS engine (see image below)

And, the karate.listen() API has been removed, instead use the new listen keyword, and here is an example.

These changes are because of the new JS engine a) not allowing JS to be shared between two contexts and b) not allowing 2 threads to access the same context, refer: https://github.com/graalvm/graaljs/issues/59

Details and Examples

Breaking changes due to JS engine change

There are not too many, and it is highly likely that your tests will be fine.

This is a good, quick summary: see diff
And here is another one: see diff

Trailing semicolons in JS blocks not allowed

Before:

* def uuid = function(){ return java.util.UUID.randomUUID() + '' };

After:

* def uuid = function(){ return java.util.UUID.randomUUID() + '' }

JSON variables no longer mutable by called features

see diff

Scenario: called feature updates a nested element of 'foo' using the 'set' keyword
    * def foo = { key: 'value' }
    # improved in karate 1.0 - json cannot be mutated in called features
    * def result = call read('copy-called.feature')
    # so callers cannot mutate this context !
    * match foo == { key: 'value' }

`print` and `karate.log()` will fail if variables do not exist

For example if foo is not defined, this will not work:

* print 'value of foo:', foo

Note that you can do karate.get('foo', 'default') to specify a default value

Multi-Value params and headers

Use a JSON array, not just a comma-delimited list for header, param, form field etc.

before:

* param myParam = 'foo', 'bar'

after:

* param myParam = ['foo', 'bar']

Java API-s for Maps and Lists are no longer "visible" within JS blocks

    * def json = { a: 1, b: 2, c: 3 }
    * def map = karate.toBean(json, 'java.util.HashMap')
    # no longer possible
    * def count = map.size()
    * match count == 3

use karate.sizeOf(map) instead

and, list.add() will not work, use array.push() instead.

    * def foo = []
    * foo.push('a')
    * match foo == ['a']

also, list.contains() will not work, use array.includes() instead.

    * def allowed = ['Music', 'Entertainment', 'Documentaries', 'Family']
    * def actual = ['Entertainment', 'Family']
    * match each actual == '#? allowed.includes(_)'

and a very rare case but in case you were trying to use a java.util.Properties() directly, that won't work any more:

    * def stream = Utils.getAsJavaIoStream()
    * def props = new java.util.Properties()
    * props.load(stream)

JS Engine is stricter about "truthy" values

here below, function(x){ return x } is not good enough

    * def isNotZero = function(x){ return x != 0 }
    * def result = karate.filter([0, 1, 2], isNotZero)
    * match result == [1, 2]

Java in JS

Objects originating from Java but when you are within a JS block will not "behave" like JSON. This applies only if you are calling Java code within a JS file (typically karate-config.js). The karate.toJson() API can be used as a solution.

Also refer: https://github.com/intuit/karate/issues/1469

before: (keep in mind this is a block of JS code)

  var JavaDemo = Java.type('com.myco.JavaDemo');
  var jd = new JavaDemo();
  var configMapFailure = jd.doWork("fromJS");
  configMapFailure['project'] = {name: "DEMO PROJECT"}

Even though jd.doWork() returns a java.util.Map, the last line above will NOT work.