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

v0.6.1

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.

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