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.

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.

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.

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 can easily extend into a record-replay "IDE" solution in future, see video
• cross-browser support from day-one, see video
• deep webdriver protocol trace-ability, see video
• Karate's regression tests for UI automation use the Karate test-doubles to serve HTML (true "dog-fooding" :), which gives us a unique advantage, for e.g. we can simulate situations like slow-loading pages with ease
• and we think one of the keys to stable and speedy UI test-automation is to move test-doubles higher in the "test pyramid" - for example, think of testing only a chunk of your UI (not the whole end-to-end) after perhaps injecting cookies and mock HTTP end-points
• since we have Gatling support, we are in a unique position to apply it in creative ways to UI testing in the future
• Karate's unique approach to JavaScript embedding may be just what the doctor ordered for taming the HTML DOM and highly dynamic pages, AJAX and all
• And Karate's assertions for JSON and XML are built-in, no extra library required
• support for Websocket that solves for Chrome (the same approach as Puppeteer) and which can be applied for tighter control over non-Chrome browsers in the future
• Unified API that solves for web, desktop and mobile - aligned with the WebDriver W3C standard, see video

The UI automation capability is deemed experimental as of now and the API can change. We are releasing this so that you can experiment and perhaps be inspired to contribute because of all the above reasons ! Read more.

Pull Requests

A big thanks to: @zak905 @vmchukky @thinkerou @loren138 @selzlein @connormca @babusekaran @leozilla and @sormuras.

Issue Register

Here is the complete list of all fixes and enhancements.

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

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        

:white_check_mark: 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.

:white_check_mark: 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.

:white_check_mark: 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.

:white_check_mark: 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.

:white_check_mark: 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.

:white_check_mark: 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 #302
• #306 Improved JavaFX UI, thanks to @RavinderSinghMaan for the PR
• #309 Introduced match contains any
• #311 Improved JUnit dev-mode report, thanks to @athityakumar for the PR

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

Breaking Changes

Java API method signature change

Additional boolean argument, true to process (and false to skip) the evaluation of karate-config.js at the start.

_$ instead of $ for match each

In case you were using $ for cross-field validations combined with a match each, the concept of a 'self parent' was introduced, since you may still need the 'real' root $. Refer to the documentation.

Notable Enhancements & Fixes

No more Stack Trace bloat

Yes, finally. Making sense of the console logs used to be difficult when scripts failed, and Karate used to dump a lot of un-necessary stack-traces. Not any more. Failures now are reported in as few lines as possible, line-breaks are included to make it easier to read (instead of scrolling around for very long lines) and the offending line number and feature-file name are clearly shown. Do submit feedback if you see any opportunities to improve further !

__arg refers to call argument #206

Yes, we should have had this earlier. While all key-values are 'unpacked' into the context of the 'called' feature, it does make sense to be able to access the passed-in argument as-a-whole. Refer to the documentation. This is a nice companion to __loop which was introduced in the previous release.

SSL bypass fix #193

Handling SSL without needing a certificate was broken in some cases. In case you were having to use a certificate for HTTPS, do try setting * configure ssl = true and it should now work without needing a certificate.

Scripts can introspect Cucumber tags #191

You can ask Karate for the values of all tags in scope. And for advanced users, Karate now natively supports tags with values in the form @name=value1,value2. Tag 'inheritance' works as you expect since in Cucumber, you can have tags at the level of a Feature, Scenario or Scenario Outline and even for rows within Examples. The possibilities are best explained in this example: tags.feature

For even more advanced users, there is a way in which you can set up custom tag filtering. Thanks to Sunil Sishtla for the pull request.

print now takes comma delimited arguments #190

Which means you no longer need to use karate.pretty() in most cases. Refer to the documentation.

set keyword can append to JSON arrays #189

* def foo = {}
# you can update json arrays (or create them automatically)
* set foo.bar[0] = 5
* match foo == { bar: [5] }

# omit the array index to append
* set foo.bar[] = 6
* match foo == { bar: [5, 6] }

parallel runner console stats now includes the count of feature files

And decimal-places reined in.

====================================================
elapsed time: 3.62 | total thread time: 13.79
features:    31 | threads:   5 | efficiency: 0.76
scenarios:   70 | failed:    0 | skipped:    0
====================================================

!contains (not contains) for strings now works #201

!= (not equals) implemented

You won't need this most of the time, but still.

charset now supported in the Content-Type header #203

Experimental HTML report for JUnit

When you use the @RunWith(Karate.class) annotation, an HTML file will be generated in the target/surefire-reports directory. As of now, it is not useful - but we will be enhancing this to make troubleshooting in dev easier. The long-term goal is to have HTML reports 'native' to Karate that better reflect API-testing concerns.

Breaking Change

match is stricter: data-types have to match

For example, Karate will no longer treat '5' as equal to 5, 'true' as equal to true and vice-versa. So - this would have failed in previous versions.

* def foo = { a: '5', b: 5, c: true, d: 'true' }
* match foo !contains { a: 5 }
* match foo !contains { b: '5' }
* match foo !contains { c: 'true' }
* match foo !contains { d: true }

The new behavior is the right thing to do - especially for a test / assertion framework. There is a good chance that all your existing tests are OK, but think of this as a way to actually surface cases where the server-side is not treating data-types correctly.

Notable Enhancements

karate.eval() JS method introduced

Not recommended for daily use, but you now have the option to dynamically create javascript fragments and evaluate them, and mix them into the right-hand-side of a match expression. Useful if you want to build a custom framework over Karate.

Reporting: HTTP logs in-line and call-ed feature steps show up

Really improves the trouble-shoot-ability of Karate runs, even if in parallel. Variable values are also dumped on failure. Here is a short video. One more change is that the feature file package + file-name is used as the test-name instead of the text in the cucumber feature, which is way more useful and relevant for API test-suites.

Gradle instructions

See doc. Thanks to Mark Corkery for the pull request

Debug hook to improve IDE debug-ability

Experimental, but there is a new com.intuit.karate.Debug class designed to be easy to set conditional breakpoints in your IDE. Do let us know if it can be improved.

Built-in variable called __loop for each data-driven iteration within a call-ed feature

Useful especially for this common pattern: to look up a corresponding row from anytable or array in scope, typically a variable def-ined in the parent or call-ing feature.

Short-cut to denote Json-Path in right-hand-side expressions

Best explained in this table of Karate right-hand-side expression shapes.

Short-cut to get[n] single array element out of a Json-Path result

Again, best explained in this table.

set on steroids - build complex nested payloads from scratch

Quick sample in this gist. Works for XML as well. Refer to the documentation.

Removed dependency on commons-io and commons-lang3

Greatly reduces the risk of conflicts when integrating Karate into existing / legacy test-suites.

Implemented missing ^^ macro short-cut for contains only

Here is a nice summary of all syntax as a cheat-sheet.

Frequently Requested Demos

• Using JDBC via Java interop and querying a database from within a Karate script.
• Reading JSON and XML files from the file-system to use in match (or request)

Notable Fixes

#115 form field params should land in the URL on a GET #126 Karate UI would fail on Windows #155 Multiple optional ##(expr) removals in JSON would fail #157 graphql supported as a text-file extension (thanks to Sunil Sishtla) for the pull request. #163 Optional ##(expr) syntax was not substituting value correctly for non-match scenarios, for e.g. payload formation #173 multi-value params for apache - thanks to Matt Johnson for the pull request. #175 parallel-executor shuts down threads, avoiding thread / memory leaks #179 scenario failures no longer abort the whole feature, other scenarios would still run #178 configure followRedirects implemented - Karate can be told to not follow-redirects so that you can inspect the Location header if needed

Breaking Changes

There are a couple of breaking changes. Please read this section carefully so that your upgrade goes smoothly.

responseCookies instead of cookies

Hopefully most users would not be referring to cookies, but if you are - the 'built-in' variable name has been changed to be consistent with the others such as responseHeaders, responseStatus and the like, and to avoid confusion with the cookie and cookies keywords for setting up the request.

A simple find-and-replace (where necessary) is all you need to do. Here is the documentation.

table - strings need to be enclosed in quotes

Refer to the documentation - this makes sense, because Karate is all about dynamic data. If you need the traditional Cucumber table experience, just use the Scenario Outline and Examples like normal.

Notable Fixes

Headers (and cookies) set in the Background worked only for the first Scenario

Especially if you are mixing call or callonce with header or configure headers.

#103 - Apache client was skipping cookies on .com domains

Fixed.

#110 - File-upload now supports setting the filename

A new multipart file syntax was introduced. The old behavior where a file-stream passed to multipart field would 'short-cut' into a file-upload will still be supported (to reduce pain for those upgrading) - but we will deprecate this at a later date.

Enhancements

Failures in called scripts now log the called script name

Yes, this should have been done sooner.

call and callonce can update 'global' shared variables and config

This is a little subtle, but can dramatically reduce the 'noise' in your top-level script that does the main 'business' flow. You can move all the setup 'clutter' into called scripts. Refer to the documentation for more.

configure cookies introduced

Not something you would use often since responseCookies are auto-added to all subsequent requests. Unless response cookies were encountered in a 'called' script in which case the item above may be part of the answer. Refer to the documentation.

replace keyword added

This is very useful if you have to perform a lot of text-replace. Refer to the documentation

remove keyword added

For deleting JSON keys or entire XML nodes from a payload. Refer to the documentation.

HTTP Mock Servlet

A big one ! Test any Java servlet based controller (e.g. Spring MVC, Jersey JAX-RS) without booting a container. Refer to the documentation.

This also introduced an option to configure a custom HTTP Client implementation, details which are in the above link.

Type Conversion supports Java Beans (or POJO-s)

Yes you can convert any Java Bean into JSON or XML. Refer to the documentation

And if you need to go the other way, look at karate.toBean() in the next section.

karate built-in JS object

Has a few more operations available on it:

• karate.remove(name, path)
• karate.jsonPath(json, expression)
• karate.read(filename)
• karate.pretty(value)
• karate.prettyXml(value)
• karate.toBean(json, className)

Refer to the documentation

XML manipulation improvements

Especially for projects dealing with SOAP and namespaces. This file should be a handy reference: xml.feature.

contains macro shortcut

A missing piece in the JSON schema-like validation short-cuts. Refer to the last paragraph in this section of the documentation - Schema Validation.

Remove If Null

A common need, which is to fully remove a JSON key or XML node (or attribute) from a given baseline payload - that now has an elegant solution. Refer to the documentation.

Karate UI and Postman Import

This is another big one ! Details here.

Draft Spring REST Docs Support

If you are interested refer to this thread.

Thanks to @rishabhbitsg for the pull requests !