1.3.0 Upgrade Guide

ℹ️ 1.3.0.RC1 is available ! List of issues fixed.

Graal JS multi-thread issues are solved

This is a big deal, achieved after upgrading Graal to version 22.0.

Advanced users of Karate may have run into some edge cases when trying to pass a JavaScript function to called feature files, especially when callonce and karate.callSingle() are involved and tests are run in parallel. These issues were mostly solved in 1.1.0 and 1.2.0, but a few rare cases were still reported.

This issue is finally resolved along with some code clean-up and we are back to how things were in v0.9.X. You can freely pass JS functions all over the place.

Some JS behavior has changed

ℹ️ Ignore this if you have not referred to JS functions within other JS functions.

For details, see: https://github.com/karatelabs/karate/issues/2009#issuecomment-1228632313

Websocket support has changed

ℹ️ If you have not used the karate.webSocket() API, then you should not have any breaking changes in 1.3.0.RC1

This is a breaking change, but the pattern for editing your existing tests is quite straightforward. Here below is a before-and-after:

• the socket.listen(5000) call has to be replaced with * listen 5000 - where 5000 (here just an example) is the timeout in milliseconds
• the magic-variable listenResult holds the result of the captured websocket message
• more details are in the docs: https://github.com/karatelabs/karate/tree/develop#websocket

New karate.response and karate.request API

This specifically solves for retrieving a given header while ignoring the case. While Karate already had support for this in simple match statements and via the configure lowerCaseResponseHeaders option, there were advanced use-cases that required more control. You can find more details here. Here is an example:

karate.response.header('content-type').

This also makes mock request routing based on headers much easier, for e.g. karate.request.header('foo') == 'bar'.

Coming in 1.3.0 Final

ℹ️ This is not included in 1.3.0.RC1, to make it easier for teams to validate all the other fixes.

@setup life-cycle

This is an important change that adds a new life-cycle to scenarios. There is a description and discussion here.

The highlights are:

• adds a way for data to be set-up before a Scenario starts
• the focus is on returning data, so no "global" state modifications are allowed, which keeps things simple
• this was introduced specifically to make it easier to setup a JSON array (or function) for Dynamic Scenario Outlines
• so you can think of this as a scenario that acts as a "background" for a Scenario Outline (but can also be called from any Scenario)
• today the Dynamic Scenario Outline has an inconsistency, which is that the Background is only run once, but with this change, the Background will run before every Scenario whether it is
  • a normal Scenario
  • a row from a fixed set of Examples: in a "normal" Scenario Outline:
  • or a row generated at runtime by a dynamic Scenario Outline: <-- this is the breaking change

Heads Up

1.3.0 will be the last release of Karate that allows for usage of Java 8. From 1.4.0 onwards, Karate will have a minimum requirement of Java 11. Please comment here if you have any concerns.