v0.9.6

What's New

• Windows Desktop app automation - Karate Robot - also see the detailed install guide
• Revamped HTML report (see video)
• Intercept browser HTTP requests in Chrome (see video)
• configure callSingleCache - so that you don't need to wait for a "sign-in flow", every time you re-run a test in dev mode
• driver.inputFile() - Chrome-native file-upload
• WebDriver support for the new (Chromium based) Microsoft Edge browser
• Improved tree walking in UI tests, e.g. locateAll(), parent, children etc.
• Multiple mock files can be combined into one at run-time (thanks @michaelpro1)
• CLI testing support ! See this thread for details
• match can finally be used in JS with all the power you normally have in feature files, see this thread and some extras to introspect object / data types within JS blocks
• contains deep for recursive nested JSON matching (see example)

Breaking Changes

• match contains will not recurse nested items any more, use contains deep as explained above
• karate.stop() now takes a mandatory port number argument, so you can call the same (static) cURL command to resume, e.g. curl localhost:8080
• exists() API refactored for UI tests, see this thread for details
• a match with a primitive number on the right-hand-side could incorrectly pass, this should be very rare - see this thread for details
• again extremely unlikely and rare, but a backslash (\) character was getting swallowed in doc-string (triple-quote) sections, so in case you were escaping them, you don't need to any more (commit details)

For a list of all issues closed in this release, go here.

To keep track of news and releases, follow us on Twitter @KarateDSL or on LinkedIn by joining this group.

Contributors

Thanks to the following rock stars for contributions and pull-requests !
@10twenty4
@a-st
@abhi-rao
@babusekaran
@cueo
@michaelpro1
@maxandersen
@kchopperla
@KostasKgr
@ewexlerr
@joelpramos
@kirksl
@luizvaz

Vote for Karate !

Karate is in the running for "Best Open Source Project" in the HackerNoon "Noonies".

Show your appreciation for Karate by voting here: Best Open Source Project

And here for the lead-developer of Karate (Peter Thomas): Contributor of the Year - OPEN SOURCE.

Thanks !

v0.9.5

The Big One

This took a while ! The last release was in July 2019 - but it does indicate that 0.9.4 was super-stable and that Karate for API testing is quite feature-complete. So what's new ? Web Browser Automation !

A lot of work went into this area, and the feedback from early adopters who used 0.9.5.RCX has been extremely encouraging. And now 🥁 we consider it ready for use.

To know more about how Karate is different from (and better in our opinion than) the competition - please read this blog post: The world needs an alternative to Selenium - so we built one.

One additional point that is going to give us an edge over other browser-automation solutions is this - because Karate embeds a web-server (via the test-doubles capability) you can submit a self-contained snippet of HTML as a full-fledged project - to demo or replicate issues. The beauty of this is that it would run completely locally, yet perfectly replicate any exotic edge case. We put a lot of thought into Karate to make it easy for developers to build, extend and maintain, and if you find any gaps in the web-browser automation - we should be able to release minor / dot-releases pretty quickly.

Breaking Changes

The Debugger

What we used to call the "Karate UI" (implemented in JavaFX) has been retired.

Now we have what we feel is a game-changer - a debugger which is part of the Visual Studio Code extension for Karate created by Kirk Slota. This debugger is special - it can not only step-through code, but step backwards and hot-reload code. Note that this works for any Karate test, so API and UI automation is covered. See this video of the Karate-Runner in action. Thanks also to @peterquiel who contributed syntax-coloring support to the Karate-Runner.

Note that you can point the Karate-Runner to an existing Maven (or even Gradle) project, and it will work fine. The new ZIP Release is ideal for especially non-Java teams - who don't want to use Maven or Gradle.

We know of many .NET, JS and Python shops using the Karate standalone JAR - and the ZIP Release makes a very compelling case for Karate and UI automation. There is no need to compile code, and reports are built-in.

configure abortedStepsShouldPass

You will need to be aware of this only if you use the karate.abort() keyword and an old version of the cucumber-reporting library - and if you want steps after an "abort" to pass - #755

Notable Improvements

• Karate used to create a lot of log files on the file-system when running tests in parallel - and in rare cases, would exceed OS limits, not any more - #860
• karate.get() now takes a default value, which is very useful for conditional logic and "called" features where a variable has not been "pre-defined". Note that karate.get() is very flexible, it can evaluate even Json-Path and XPath - not just variable references
• Gatling tests would freeze in some cases, performance issues have been fixed - #845
• An ExecutionHook interface has been introduced for more control over the life-cycle and for teams that need to integrate with 3-rd party reporting solutions and the like, and you can inject your custom implementation via the parallel Runner - #855
• And you can now "mask" parts of the HTTP log to avoid sensitive data such as Authorization headers and passwords being persisted and leaked - #699
• Distributed Testing - that should solve for "scaling out" UI or Gatling tests
• Introducing Karate Robot (experimental) for desktop app automation and native mouse / keyboard events, you can navigate using images, see video - we know that many teams need this, there is a severe lack of solutions in this space - so please get in touch and contribute if you can !
• karate.log() now "pretty prints" JSON and XML, so you don't have to resort to things like JSON.parse() and JSON.stringify() in your JavaScript snippets. Note that you should never need to use things like JSON.parse() - and they cause problems in the long term.
• There is no need to use the @KarateOptions annotation for the parallel runner any more. Use the "builder" methods on the Runner class, which handles multiple features (or just directory / paths), tags, and the number of threads. Going forward, as a best-practice, you are recommended to not use the annotations any more - and if you use JUnit 5, you don't need it at all, see the example below
• JUnit 5 API - a little less verbose syntax via Karate.run(), see below:

For a list of all fixes in this release, see here.

Contributors

Thanks to @paaco, @Celeo, @peterquiel, @ghostwriternr, @sivachithambaram, @BadgerOps, @man007yadav, @Nishant-sehgal, @TamannaBhasin27, @benjaminqc, @babusekaran, @celcius112, @khanguyen88 and @kirksl for pull-requests and other contributions. You rock !

v0.9.4

Breaking Change

There is only one and only for those who use the standalone JAR file. When tests are run - the cucumber-json and junit-xml report output files will now be in target/surefire-reports not directly in the target directory. This prevents the inclusion of other JSON files into the report generation routine which would break the HTML report.

Notable Improvements

There are some bug fixes, and the main improvement is that the eval keyword is un-necessary (optional) for most cases - which makes Karate very close to pure JavaScript as a scripting language.

Also - the Maven archetype (quickstart) now uses JUnit 5 instead of JUnit 4 - which simplifies the code a lot for newcomers.

There is a bug in the quickstart, please read this as well: fix for 0.9.4 Maven archetype.

See complete list of fixes here.

eval keyword optional for most cases

Which includes any method call or operations on variables in scope and where you "don't care" about the returned value. Examples are:

# using any API on the "karate" helper
* karate.env

# where "foo" is of type function(){}
* foo()

# where "bar" is a variable in scope
* bar.baz()

# if statements for conditional logic
* if (responseStatus == 200) karate.call('delete-user.feature')

This greatly simplifies Karate mocks as evident in this diff below !

Note that now we recommend that you directly use JavaScript instead of the set keyword when needing to "update" an existing JSON variable. If you need to remove a JSON key where the key name is dynamically derived, use karate.remove() as shown above.

Note that these rules apply to the Left Hand Side of the match keyword - so you can do things like this now - note the combination of match and karate.filterKeys():

* def schema = { a: '#string', b: '#number', c: '#boolean' }
* def response = { a: 'x', c: true }
# very useful for validating a response against a schema "super-set"
* match response == karate.filterKeys(schema, response)
* match karate.filterKeys(response, 'b', 'c') == { c: true }
* match karate.filterKeys(response, ['a', 'b']) == { a: 'x' }

In initial versions of Karate, you had to split the last 2 match steps above into 2 steps.

New karate.filterKeys() API #810

And an example appears above. This is very useful for cases where you want to use a "super set" schema that is defined once and you want to re-use. Also in situations where you quickly want to "select" only a few keys out of a given JSON. See the documentation on JSON transforms for more.

New karate.start() API

To start a Karate mock directly from a feature file without needing to write Java code. Refer to the docs here.

New karate.os API

To get meta-data about the runtime operating system, that can be used to drive conditional logic - for example to run a slightly different set-up routine for Mac OS X versus Windows. See documentation here. Here is a representative example:

# looks for "common-windows.feature" or "common-macosx.feature"
* call read('common-' + karate.os.type + '.feature')

call read fileNameString

A short-cut to inject all key-values of a given JSON file into the variables context is now possible, more details in this comment.

Karate UI has a "pre step" hook option

Best explained in this video.

v0.9.3

Breaking Changes

• Karate UI no longer part of karate-core and has to be explicitly added to your Maven (or Gradle) dependencies if you want to use it - as karate-ui.
• WebSocket API changes, see the documentation here - and you call listen() on the socket instance, not on the karate object. You can now juggle multiple websocket connections within a Scenario. Custom headers can be added and you can change the default message limit, in case you are using large binary websocket payloads.
• The karate-netty Maven artifact has been retired. The Netty / mocks code has been part of karate-core since 0.9.0, and in fact if you use karate-apache (or karate-jersey) you don't need any additional dependency any more. If you were using only karate-netty in a project, change it to karate-apache. The karate-netty dependency used to include the net.masterthought:cucumber-reporting dependency, which may have been convenient - but now if you need that reporting solution, you have to add that dependency explicitly.
• a long pending issue where nested arrays in JSON created within JS would turn into JSON objects (instead of remaining as arrays) has been fixed - so in the rare chance that you have this happening in your existing tests, they might break.
• if you are using * configure ssl = { trustAll: true } - the true here is now a boolean, not a string #772

See complete / detailed list of fixes here.

Notable improvements

Gatling fixes #721

Some kinds of tests would not "complete" leaving some requests missing from the final report and perf stats. Also the tendency to "hang" is fixed.

Enhanced Scenario Outline #717

This is possibly one of the best innovations yet in the Cucumber improvements that Karate brings. Now the Scenario Outline is tightly integrated with Karate's JSON data-driven capabilities. Read about it in detail here: Scenario Outline Enhancements

Run Scenario by name and line-number #770 #773

You can now run a Scenario by name or line-number which is extremely convenient in development mode. While possible in Cucumber, this had been temporarily lost after we dropped the Cucumber-JVM engine.

New API methods on the karate object

• karate.repeat() - avoid nasty JS loops to do an action N times
• karate.mapWithKey() - convenient for the common case of converting an array of primitives into an array of "single key-value pair" JSON-s
• karate.set() - set multiple variables in one shot from a JSON / bag of key-values
• karate.merge() - merge 2 or more JSON / map-like objects
• karate.append() - append 2 or more objects or list-like objects into a single array / list
• karate.sizeOf() - future-proof way to get the size of an object / map or array / list without worrying about the Java type behind the scenes
• karate.keysOf() - future-proof way to get the keys of an object / map without worrying about the Java type behind the scenes
• karate.valuesOf() - future-proof way to get the values of an object / map (or array / list) without worrying about the Java type behind the scenes
• karate.appendTo() - useful for appending items into an existing variable that is expected to be list-like, without worrying about the Java type behind the scenes
• karate.exec() - convenient way to invoke a native OS command and scrape the console output

experimental Appium support / UI automation #743

Do try / contribute if you can !

Karate confirmed to work with Java 12 #724

Karate is one of the few automation frameworks that is Java 12 ready. Note that we have a migration to Graal planned that will ensure support for Java versions beyond 12.

v0.9.2

Important Fixes

This is a bug-fix release and there are no breaking changes from 0.9.1 (unless you use the Gatling integration, see below) which was released 2 months ago. The main reasons why you should upgrade are the following:

Dynamic Scenario Outlines miss some HTML logs #660

Only if you use Dynamic Scenario Outlines - the HTTP / console log was being missed for some scenarios in the HTML / JSON report.

Some failures in test execution hang Parallel Runner #667

Some kinds of catastrophic failures especially in the karate-config.js bootstrap - would cause the parallel runner to hang indefinitely.

JUnit runner syncs console output better to IDE / IntelliJ #690

In IntelliJ - clicking on the nodes in the IDE UI for JUnit would not show the corresponding section of console output.

Gatling integration now works on Java 9 and above #647

We upgraded the Gatling version we target to 3.X which means we are no longer limited to only Java 8. You need to upgrade the Gatling Maven plugin version, and depending on which Gatling features you have used - there may be API changes. Refer to this Github diff for details.

WebSocket Sub-Protocol Support #662

Added support for the sub-protocol part of the spec.

Karate UI log TextArea broken #659

Only if you use the Karate UI - the area in the UI where the log was supposed to collect was not working.

UI Automation Improvements

Also we improved the experimental UI automation API, with new driver.switchTo() and driver.value(set) operations.

For the complete list of fixes, go here.

v0.9.1

Important Fixes

This is a bug-fix release and there are no breaking changes from 0.9.0 which was released last month. The 2 main reasons why you should upgrade are the following:

HTML Report Concurrency Problem #629

When there were multiple Scenario-s within a feature, the logs could get mixed up. Note that this bug does not affect the accuracy of test results, but will make it harder to troubleshoot in some cases.

Un-helpful match error message #621

One of the changes in 0.9.0 unfortunately made the match error message a lot less user-friendly, instead of identifying the exact path to the mis-matched element, you would see a generic message like: all key-values did not match - and worse, a dump of all sibling data-elements, which could be quite verbose.

There are a few other fixes including a windows path issue for the standalone JAR, see the whole list here.

v0.9.0

The 0.9.0 release is a big one. Karate no longer uses Cucumber behind the scenes and the feature-file parser and execution-engine were re-written from scratch. 100% backwards compatibility has been maintained, all your existing tests will run fine - and even IDE support has been preserved.

This took some serious engineering effort, but was totally worth it ! We can now move fast and improve the engine without worrying about the evolution of Cucumber versions. For example, the parallel-runner now executes even Scenario-s within a Feature in parallel, and that includes data-driven Examples within Scenario Outline-s.

Which leads us to the only possible breaking change you may encounter - Scenarios will be executed in parallel by default. See below.

Breaking Change

There are absolutely no breaking changes for syntax and Java API, and it is highly likely your existing Karate tests would run as-is without any changes. But in case you have Scenario-s that depend on each-other (which obviously is a bad-practice and absolutely NOT recommended) you will have to use the @parallel=false tag to force them to run in sequence - when using the parallel runner. Just place the tag above the Feature level in your test-script so that it applies to all Scenario-s within that Feature. Read more.

While upgrading, use this opportunity to ensure that your tests are indeed independent and can run in any order !

TestNG Support Deprecated

The documentation has always warned that JUnit is strongly recommended, and we have been announcing this deprecation in advance. This is not going to be an issue because even in the rare chance that you have gone "all in" on TestNG, the Maven surefire plugin supports JUnit and TestNG in the same project. Note that JUnit 5 support has been introduced. Keep in mind that the parallel runner (which is what you will be using most, e.g. for CI) is pure-Java and it does not matter if the runtime is JUnit or TestNG.

Planned Deprecations

The next release will deprecate the @CucumberOptions annotation and the CucumberRunner class, please plan to switch to com.intuit.karate.KarateOptions and com.intuit.karate.Runner. And com.intuit.karate.Results will eventually replace KarateStats. All the examples and documentation have been updated. So this is the recommended pattern:

Results results = Runner.parallel(getClass(), 5);
assertTrue(results.getErrorMessages(), results.getFailCount() == 0);

In fact for tests in dev mode (not the parallel runner), if you start using JUnit 5 you may not need the @KarateOptions (previously @CucumberOptions) annotation any more.

On the command line, instead of cucumber.options - you can start using karate.options.

To be clear, we will only turn on deprecation warnings in the next release, the old stuff will still work in the next release (1.0) and will stop working (as per plan) only later, in the release after 1.0 - so in short, you don't need to change anything for now.

karate-netty now part of karate-core

Your existing projects are not affected, but now you no longer need to use the karate-netty artifact if you want to use mocks or test-doubles, all of that goodness is in the main JAR itself. In other words, when you use karate-apache, you get the test-doubles capabilities as well.

New and Notable

Parallel Scenarios

Already mentioned above, and there is a new HTML report that allows you to visualize the parallel efficiency: see video.

JUnit 5 support

Thanks to the JUnit team and @sormuras for his awesome support and PR-s ! You can have multiple methods in the same test-class which should reduce a lot of clutter in dev-mode. And the API is elegant, nice and DRY. Read more.

Re-vamped Karate UI

Great for demos and de-bugging tests, a big improvement is that you can even step through call-ed features. You can import Postman collections like before, but that capability is still considered experimental. Please do contribute if you can ! See video. Read more.

Thanks to @babusekaran for some PR-s !

Lower Case and Headers

As per the HTTP spec header names should be case-insensitive. You can force all header key-values to be lower-case:

* configure lowerCaseResponseHeaders = true

We also made it easy to take any JSON and brute-force all of it to lower-case, which can be useful in some situations:

* def response = karate.lowerCase(response)

Read more.

responseBytes and requestBytes

An additional built-in variable responseBytes will hold the response as a byte-array, useful when dealing with binary-content. And the match syntax even works with byte-arrays, no there's no need to do a custom array comparison any more:

And match responseBytes == read('test.pdf')

Similarly, for the test-doubles / karate-netty side, requestBytes holds the incoming request byte-array.

Call Tag Selector

You can now choose a single Scenario when using the call (or callonce) keyword. Just append it to the feature name like so:

call read('classpath:my-signin.feature@sometagname')

Read more.

Gatling

The above call tag selector concept allows you to better compose load tests out of a large suite of existing Karate tests. Two other big improvements are the ability to customize the "report name" of any HTTP request, and to even test any Java code, not just HTTP ! As an example, see the Karate-gRPC project. Read more.

Report Verbosity

Hide steps in the report when configured or show only steps that don't begin with the * prefix. Read more

WebSocket and Async

There are certainly not many testing frameworks that support websockets. And with just two API methods: karate.signal(result) and karate.listen(timeout) - you can easily set up tests to wait for async events such as message-queues.
Read more

Retry Support

No more messing around with JavaScript loops and an additional file to call, now provide a condition before the method step and Karate will do the rest. Read more.

Dynamic Scenario Outlines

Examples no longer have to have a fixed number of rows at run-time. Use JSON arrays, that can even be dynamic and created at run-time - but retain the same read-ability and report-friendliness of the Scenario Outline. Read more.

CSV File Support

Karate can now read CSV files out of the box - and as you can imagine this goes really well with the Dynamic Scenario Outlines described above. So if you read() a file with a *.csv extension, Karate will convert it into a JSON array, and a header row is always expected. Read more.

Image Embedding

You can now use karate.embed(bytes, mimeType) to embed any kind of content into the test output and these would be viewable in the HTML report. Read more.

Chrome Browser Automation

You may have heard of Puppeteer and "Headless Chrome" - and guess what, Karate has first-class support for Headless Chrome now ! This sets us up for UI automation (see the next section) but - Karate is probably one of the few libraries out there that gives you the capability to save HTML from a URL you choose - into PNG or even PDF. Read more.

UI Automation (experimental)

Yes, why not - provided API testing is feature-complete and mature. We strongly feel that if we get this right, and actually solve the problem of "flaky tests", Karate would be a serious force in the world of test-automation. In our opinion, there are quite a few things that give Karate an advantage:

• clean code base, LOTs of tests, one-click git-clone and maven build dev-experience, easy for contributors
• battle-tested parallel execution, that can be easily extended into a "grid" solution in future, see video
• UI to debug and step-through tests, that we ...

v0.8.0

Breaking Changes

This first one only applies if you are using the stand-alone JAR. Previously the command-line option -t was used to specify the feature file to be run - but now it is used to specify Cucumber tags. There are some big improvements - parallel execution and even reporting are built into the single binary ! Refer to the documentation for more details.

Second: the com.intuit.karate.Debug class has been removed - while refactoring the engine to get Gatling support to work, but we are pretty sure no one was using this. We can bring this back if needed.

Introducing: Karate-Gatling

Re-use API functional tests as performance tests !

We are releasing this ! This is the first version, but we have people who tried it report back and it seems to be stable. Here is a video of what to expect: link. And here is the documentation. Your feedback can make this better, and we are committed to release minor version upgrades when needed as we evolve this.

Notable Enhancements and Fixes

Parallel Runner Memory Usage

To pick one highlight - it is the greatly improved memory usage of the parallel runner. Earlier, teams that had many tests would run into an Out Of Memory error and had to reduce or switch-off log levels to work-around.

map, filter and forEach

Also map, filter and forEach operations have been introduced on the built-in karate JS helper object. This will make it easier to work with JSON arrays or list-like data - very useful for filtering or even transforming one kind of JSON into another. This demo file has some examples.

Stand-alone JAR has everything

This makes Karate more accessible for teams that are not really into Java and don't want to use a Java IDE or Maven project structure. The stand-alone JAR can now even run tests in parallel from the command-line and the only pre-requisite is a JRE. You can now recommend Karate for JavaScript, .NET or Python developers without holding back ! This is great for demos as well. Note that the binary has been renamed to karate-<version>.jar to signify that it has everything in it. Refer to the documentation for all the details.

karate-netty dependency bundles Netty dependencies

The test-doubles (karate-netty) project now "shades" the netty JAR which means you can combine Karate mocks into Maven or Gradle projects which already use netty - without any library conflict issues.

Closed Issues Register

• #329 Eclipse JUnit test results would show as "unrooted"
• #306 Karate UI improvements - thanks to @RavinderSinghMaan
• #319 Gradle conventions are honored for build output directory
• #337 Test-Doubles - introduced bodyPath helper to make it easier to route incoming requests based on payload content
• #341 XML attribute embedded expressions would not work for empty elements
• #342 Apache bug in HTTP headers needs upgrade
• #346 Complex JSON schema bug in match each
• #355 Dynamic XPath support for XML
• #370 Standalone JAR can now run multiple features in parallel and generate HTML reports !
• #378 karate.match() implemented, now you can programmatically do a match
• #379 JSON / HTML reporting improved for "called" features
• #381 Support for HTTP proxy exceptions - thanks to @xxxyyyz
• #387 Clean way to over-ride config in dev mode without having to check-in sensitive values
• #397 Option to disable / switch on-off HTTP logging during a test
• #407 remove had no effect on XML attributes
• #408 Removed hard-dependency on logback
• #415 multipart fields introduced that can take a JSON with multiple dynamic values
• #417 Java API to select features at run-time for parallel / execution
• #411 Clean way to stop karate-netty server via admin HTTP end-point
• #421 Cucumber Outlines within called features would abort on the first example that failed
• #439 Karate version now appears in the logs to help bug-reporters
• #452 #notpresent will work as a JsonPath or XPath match even if it is the only RHS

v0.7.0

This guide assumes you are upgrading from 0.6.2, please refer to older release notes if needed.

Karate has had a re-vamp of the JavaScript evaluation engine, which improves execution performance by more than 50%. And Karate has expanded into the area of API test-doubles. Karate is also now available as a single binary (see the link at the top of these release notes), which is useful for starting a mock-server, demos or exploratory testing.

In the process, some significant additions have been made to Karate's syntax plus a couple of carefully considered changes. The good news is that we estimate 80% of existing users will NOT face any issues. Even if you do run into breaking changes - you can breathe easy, as the fixes are very simple and likely to be addition of a single character, or at the most - a single line.

Important: Please do provide feedback if you run into any other issues ! Note that a good way to keep up to date with releases and other news is to follow us on Twitter @KarateDSL.

Breaking Changes

(1) You need to be on a Java version at least 1.8.0_112 or greater

This should not be an issue for most teams and it is quite likely that you are already on a recent enough version. But do check, and the problem that you can run into will look like this:

java.lang.RuntimeException: evaluation of karate-config.js failed:
	at com.intuit.karate.ScriptContext.<init>(ScriptContext.java:150)
        ...
	at com.intellij.rt.execution.junit.JUnitStarter.main(JUnitStarter.java:70)
Caused by: com.intuit.karate.exception.KarateException: javascript function call failed: 
ReferenceError: "karate" is not defined        

✅ Short Fix Description: Upgrade to the latest version of the Java 8 JRE.

(2) Karate Expressions Default to JS

And JsonPath (or XPath) that refers to a variable other than response needs to be pre-fixed with $ on the RHS

Karate used to attempt to 'auto-detect' JsonPath (and XPath) on the Right-Hand-Side of Karate Expressions. For example this used to work:

* def foo = bar[*].id

This had some non-ideal consequences, for example if you wanted to get the length of bar, you would have to 'force' JavaScript evaluation, by wrapping in parentheses:

* def len = (bar.length)

Now, Karate 'defaults' to always expecting JS on the R.H.S. This has multiple advantages, there is no more 'guesswork' and trial-and-error needed, and the parsing logic became simpler and runs faster. So the above two lines can be now written like this. Prefxing a variable with $ tells Karate to use JsonPath instead of JS:

* def foo = $bar[*].id
* def len = bar.length

Note that $ still represents the response and JsonPath in the form $.foo will continue to work like always.

Similarly for XML, / still represents the response. You will need to use the $varname form for XPath on a variable which is not the response, like so:

* def documentId = $myXml/root/EntityId

Note that there is no change to the get syntax. Just that $varname[*].id is now an alternative to get varname[*].id.

✅ Short Fix Description: All you need to do is prefix a $ where necessary.

(3) #null is stricter, key must be present

Karate used to treat all the following as 'equal' when doing a match.

• {}
• { foo: null }
• { foo: '#null' }

Not any more. So if you were using #null and you want to match even when the key is not present, just use the 'optional null' marker.

* def test = {}
* match test == { foo: '##null' }

Note that #present and #notpresent have been newly introduced and take care of all the possibilities.

✅ Short Fix Description: All you need to do is prefix a # where necessary or use '##null' instead of an expected null or just use #ignore.

(4) call will not re-use or "share" variables

There was a bug in the implementation of call where variables could be over-written by the 'called' routine even when not using 'shared scope'. The most likely situation where you may run into issues is when:

• you are using configure headers with a JS function in your 'main' feature
• the JS function depends on the value of a context variable (typically using karate.get())
• you attempt to set the value of this variable in the 'called' feature - which will not be 'seen' by the JS function because it is executing in a different 'sandbox' (of the parent / caller)
• you make an HTTP request in the 'called' feature that depends on the JS function working correctly, typically when you do more than one call as part of an authentication flow

If you had faithfully followed the 'sign-in' example in the main Karate documentation, you might have this issue and the documentation has been updated to make clear what the 'right thing to do' is. Just refer to the table at the end of the section on shared scope.

✅ Short Fix Description: Either duplicate the configure headers line in the 'called' feature (easy fix), or switch to using shared scope (recommended).

(5) Karate will send charset=utf-8 in the request Content-Type header by default

This is expected to be the intent almost all the time. You can over-ride this per-request by setting the header, for example * header Content-Type = 'application/xml;charset=ISO-8859-15'. To set the request charset 'globally', use the configure charset keyword.

In rare cases, the server may be unable to handle a charset appearing in the Content-Type header, and we encountered this once when the entity happened to be part of a multipart request. This actually can be considered as a bug in the server but you can work around this case by setting * configure charset = null before the HTTP request is made.

✅ Short Fix Description: Set * configure charset = null only if you run into a situation where the server doesn't like a charset appearing in the Content-Type header (which should ideally be fixed on the server).

(6) Cucumber native plugins if specified for the JUnit runner will be ignored

Most users will not be impacted by this. But if you use something like @CucumberOptions(plugin = {"pretty", "json:target/cucumber/cucumber-data"}) in conjunction with the JUnit runner, the value of plugin (or format) if specified will be ignored. With Karate, all you need is either the parallel runner (which emits the JUnit XML and the Cucumber standard JSON which most CI and third-party reporting tools can consume) or the HTML report.

✅ Short Fix Description: If you were relying on JSON like in the example above, switch to the parallel runner, which is more suited for API tests. Else you don't need to change anything, and the value of plugin will be silently ignored.

Notable Enhancements and Fixes

• #255 custom version string should be supported in the Content-Type header
• #256 non-json non-string fuzzy match does not work (fixed)
• #257 Karate now supports afterScenario and afterFeature 'hooks', and you can get access to test metadata such as the feature file name and scenario name via karate.info
• #259 Malformed JSON response stops test with error (fixed)
• #260 XML with DTD still does not parse correctly (fixed)
• ---- Introduced the copy keyword
• ---- Introduced the eval keyword
• #262 syntax failures and typos now will fail scenario
• #267 result of karate.read() of JSON within a JS function would not 'cross over' (fixed)
• #273 option to run a global one-time init routine, especially useful for auth karate.callSingle()
• #281 you can now (optionally) use a specified certificate for HTTPS / mutual authentication, thanks to @mattjm for the PR
• #282 NPE when first Scenario is Outline in 0.6.2
• ---- Parallel reporter now summarizes error messages at the end of a test-run making it much easier to troubleshoot a large suite if you only have access to the console log
• #298 Empty string supported as the Content-Type header (only supported in Apache)
• #300 Combination of form-field and header would re-set headers
• ---- Introduced configure charset which defaults to utf-8 so existing tests should work un-changed, also see [...

v0.6.2

Karate

We hope you like the new logo !

Possible Breaking Change

table keyword will omit keys with null values from resulting JSON

It is quite unlikely you will face issues with the new behavior, but. Empty cells or expressions that evaluate to null will result in the key being omitted from the JSON. To force a null value, wrap it in parentheses:

* def one = { baz: null }
* table json
    | foo     | bar    |
    | 'hello' |        |
    | one.baz | (null) |
    | 'world' | null   |
* match json == [{ foo: 'hello' }, { bar: null }, { foo: 'world' }]

New JUnit "dev-mode" HTML report

The main reason why you may want to upgrade. This should greatly improve the ease of trouble-shooting a Karate test in your IDE in dev-mode. You need to use the JUnit Runner. Here is a video of what to expect: link.

GraphQL Example Added

Karate is actually a perfect fit for testing GraphQL API-s and a new example was added to the demo suite to show-case this capability: graphql.feature.

Notable Enhancements and Fixes

#136 callonce now works when using IDE runner (Eclipse and IntelliJ)
#216 Apache HTTP Client does not follow POST redirects by default - fixed
#229 Apache HTTP Client not allowing cookies with dots in the 'domain' - fixed
#232 built-in variables __arg and __loop not set if using shared-scope - fixed
#223 HTTP response not recognised as JSON if it begins with a newline - fixed
#239 Failed scenarios in called features will now have Scenario name included in the exception / log
#244 XML with DTD would fail - fixed
#246 Parallel runner not honoring logback config - fixed
#248 Schema-like validation should support JSON chunk references which are optional - fixed
#226 Actual HTTP request made (especially headers and payload) can be now be retrieved within a test - which makes writing a framework over Karate easier. There's a new karate.prevRequest property on the built-in karate JS object

Pull requests

#253 Karate runner Java 8 updates - thanks to Srinivasan Sekar