v0.6.0

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

v0.5.0

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 !

v0.4.3

The main driver for this release is the updated instructions on how to (optionally) integrate the 3rd party cucumber-reporting library instead of using the maven-cucumber-reporting plugin because of this issue. Refer to the karate-demo documentation for more.

Some documentation sections were improved and new sections added.

In addition the JSON structure validation (which is an alternative to JSON-schema) was improved, with the support for denoting optional fields by using ## instead of # as the validator 'macro' prefix. One more enhancement is to support the combination of a built-in validator and a self-validation 'predicate' expression. For example:

* def foo = ['bar', 'baz']
# should be an array of strings each of length 3
* match foo == '#[] #string? _.length == 3'

This visual is a good way to explain what is possible and how Karate provides a simpler yet more powerful alternative to JSON-schema.

v0.4.2

There are no changes that break backwards compatibility. Most of the changes are enhancements.

Notable Enhancements

#82 Powerful, elegant notation for 'in-line' match for arrays that is especially useful for JSON schema-like validations. Refer to the documentation.

#85 You can call Karate scripts via a Java API and also get hold of the data returned by the HTTP calls. This is useful for mixing Karate into for e.g. Selenium / WebDriver tests. Refer to the documentation for more.

(no id) Multiple fixes to XML handling, XPath can return node-lists, and round-trip conversion to Map and back is stable. Refer to the documentation - which includes a link to a detailed example *.feature file.

(no id / #88) Support for data-type conversion from XML <--> JSON and from any to String, useful in some situations - refer to the documentation.

#87 Parallel runner emits Cucumber JSON report (in addition to JUnit XML). So you have the option of generating very nice reports via 3rd party maven plugins. Refer to the demo documentation for more.

Here is an example report:

v0.4.1

There are no backwards-compatibility breaking changes.

Fixes

#72 comma-delimited param values encoded badly with +
#75 reading files in a 'called' feature was using parent (caller) context for embedded expression evaluation
#57 (re-opened) in some cases, a null response entity was causing a null pointer exception

Enhancements

#44 Yes now you can optionally pretty-print the JSON or XML response, look at the additional configure keywords introduced logPrettyResponse and logPrettyRequest. These are not switched on by default, and we recommend using them only in dev mode.
#71 The Apache HTTP client should now honor system settings for things like the HTTP Proxy
#67 'not contains' implemented with the !contains keyword

You can opt to remain on 0.4.0 unless you really want any of the above. There was no development on the karate-web (UI) since the last release, but this is going to resume soon.

v0.4.0

There are no breaking changes. The bump in minor version number is to represent the appearance of the web-UI (alpha) and some logger re-factoring that went in behind the scenes.

Notable Fixes

#61 JSON arrays returned by JS functions should work for match
#57 request body should be optional for DELETE
#54 setting a header should overwrite any existing ones not append

Enhancements

#56 params, headers, cookies and form-fields can be set in one-shot using JSON. This enables data-driven testing for some use-cases. For example, dynamic search-queries: dynamic-params.feature
#48 conditional building of XML is possible from JS, here is an example xml-and-xpath.feature

Bonus

Alpha version of Karate web-ui that allows you to step-through, edit, and re-play a step without having to re-start a test run from scratch. Download the JAR attached in this release. This video shows what to expect, with instructions: https://twitter.com/ptrthomas/status/861249247282319360

v0.3.1

There are no breaking changes.

New Feature

callonce for feature-level one-time set-up

This is an elegant solution for Cucumber's lack of a way to run some set-up routines only once per feature. Which has been a much-requested open-issue at the Cucumber project for a long time. Refer to the callonce keyword documentation for more.

Karate now has a nice list of features which it adds but which are missing in Cucumber.

Notable fixes

• Improved error logging if feature (or called features) have step failures
• fixed broken cookie handling for Jersey
• improved JUnit XML report routines for Karate 'native' parallel runner
• improved archetype to include empty src/main/java folder to stop Eclipse from complaining
• 'lenient' SSL host verification was broken for Apache

v0.3.0

Breaking Changes

HTTP Client Abstraction

The HTTP Client used by Karate is pluggable and can be switched between Apache and Jersey. This is a significant change that 'future-proofs' Karate, and opens up various options - for example a Spring MVC Mock implementation. The main advantage for users is that if you run into class conflicts you can just switch and not be blocked. For example, if you want to include Karate tests within the same Java project as your web-app, and your web-app depends on an older version of Jersey - just use the Apache implementation.

So now you need two dependencies:

Before:

<dependency>
	<groupId>com.intuit.karate</groupId>
	<artifactId>karate-junit4</artifactId>
	<version>0.2.9</version>
	<scope>test</scope>
</dependency>

After:

<dependency>
	<groupId>com.intuit.karate</groupId>
	<artifactId>karate-apache</artifactId>
	<version>0.3.0</version>
	<scope>test</scope>
</dependency>

<dependency>
	<groupId>com.intuit.karate</groupId>
	<artifactId>karate-junit4</artifactId>
	<version>0.3.0</version>
	<scope>test</scope>
</dependency>

Other than the change to cookies (see below) this does not impact any existing test scripts or syntax.

cookies are map-like

If you were using the value of a cookie, each cookie is now a map-like object not a plain-string and the value can be accessed using the value key.

Before:

And def time = cookies.time

After:

And def time = cookies.time.value

Pull Requests

#34 Binary response handling ( thanks @ambertests )

Other improvements

• new demo example for creating an array dynamically for a data-driven test
• new demo example for implementing test set-up routines that run only once similar to the JUnit @BeforeClass annotation

v0.2.9

There are no breaking changes.

Notable Fixes

#30 XPath functions can also be used via the get keyword. XML support is now considered complete and on par with JSON. XML attributes are handled correctly and error reporting shows the proper XPath as well
#29 Windows path quirks fixed, and the IDE / plugin support has been tested on both Eclipse and IntelliJ

'Big Decimal' handled correctly

The Nashorn JS engine auto-converts JavaScript numbers into BigDecimal in some cases (high precision decimals, negative numbers etc). This is now handled correctly. Equality checks work as expected.

Enhancements

yaml support with new keyword

Refer to the documentation.

text support with new keyword

Which avoids auto-converting to JSON - especially relevant for GraphQL. Refer to the documentation.

v0.2.8

There are no breaking changes.

Enhancements

• Fixed problems in 'parallel' JUnit XML report, scenario names, scenario outline names, package names now should reflect the reality better. Stats "roll-up" by package correctly now.
• Much better error reporting - now the log and exception thrown clearly shows the URI (and reason) when things like a connection timeout occur.
• HTTP status assertion failures also provide more detail, here again the URI and time taken etc.
• 'Global Configuration' now possible with the introduction of the 'karate.configure' method in JavaScript. See the example below.
• A common mistake is users thinking that the request keyword represents a variable and trying to do set or def on it. Karate will now provide a helpful error message.
• Payload logging is no more via the Java utils logging (JUL) which Jersey forces you into by default and which used to appear in System.err. What this means for users is that now logs will be correctly interspersed with test-execution - and troubleshooting logs (especially in JUnit reports) will be much more easier.
• Added slack support channel on the home page / documentation.
• More information in the Maven archetype especially for Eclipse users who may otherwise miss that the Cucumber-Eclipse plugin avoids the need for writing a Java test runner.
• Added demo example for calling Java from Karate scripts (part of the file-upload example).
• Parallel execution now considered production ready, and added an option to customize the report output directory.

Global Configuration

New karate.configure method which can be used in karate-config.js for 'global' configuration

karate.configure('connectTimeout', 5000);

The effect of the above would be to fail any HTTP call that does not connect within 5 seconds.
The key and value arguments for the karate.configure(key, value) method are the same as documented for configure.