Karate
-## Web-Services Testing Made `Simple.`
+## Test Automation Made `Simple.`
[](https://mvnrepository.com/artifact/com.intuit.karate/karate-core) [](https://travis-ci.org/intuit/karate) [](https://github.com/intuit/karate/releases) [](https://github.com/intuit/karate/wiki/Support) [](https://twitter.com/KarateDSL)
-Karate is the only open-source tool to combine API test-automation, [mocks](karate-netty) and [performance-testing](karate-gatling) into a **single**, *unified* framework. The BDD syntax popularized by Cucumber is language-neutral, and easy for even non-programmers. Besides powerful JSON & XML assertions, you can run tests in parallel for speed - which is critical for HTTP API testing.
+Karate is the only open-source tool to combine API test-automation, [mocks](karate-netty), [performance-testing](karate-gatling) and even [UI automation](karate-core) into a **single**, *unified* framework. The BDD syntax popularized by Cucumber is language-neutral, and easy for even non-programmers. Powerful JSON & XML assertions are built-in, and you can run tests in parallel for speed.
-You can easily build (or re-use) complex request payloads, and dynamically construct more requests from response data. The payload and schema validation engine can perform a 'smart compare' (deep-equals) of two JSON or XML documents, and you can even ignore dynamic values where needed.
-
-Test execution and report generation feels like any standard Java project. But there's also a [stand-alone executable](karate-netty#standalone-jar) for teams not comfortable with Java. Just write tests in a **simple**, *readable* syntax - carefully designed for HTTP, JSON, GraphQL and XML.
+Test execution and report generation feels like any standard Java project. But there's also a [stand-alone executable](karate-netty#standalone-jar) for teams not comfortable with Java. You don't have to compile code. Just write tests in a **simple**, *readable* syntax - carefully designed for HTTP, JSON, GraphQL and XML. And you can mix API and [UI test-automation](karate-core) within the same test script.
## Hello World
@@ -141,6 +139,7 @@ And you don't need to create additional Java classes for any of the payloads tha
| 
-The demo also features [code-coverage using Jacoco](karate-demo#code-coverage-using-jacoco). Some third-party report-server solutions integrate with Karate such as [ReportPortal.io](https://github.com/reportportal/agent-java-karate).
+The demo also features [code-coverage using Jacoco](karate-demo#code-coverage-using-jacoco), and some tips for even non-Java back-ends. Some third-party report-server solutions integrate with Karate such as [ReportPortal.io](https://github.com/reportportal/agent-java-karate).
## Logging
> This is optional, and Karate will work without the logging config in place, but the default console logging may be too verbose for your needs.
@@ -811,6 +821,41 @@ This approach is indeed slightly more complicated than traditional `*.properties
And there is no more worrying about Maven profiles and whether the 'right' `*.properties` file has been copied to the proper place.
+### Restrictions on Global Variables
+Non-JSON values such as Java object references or JS functions are supported only if they are at the "root" of the JSON returned from [`karate-config.js`](#karate-configjs). So this below will *not* work:
+
+```javascript
+function fn() {
+ var config = {};
+ config.utils = {};
+ config.utils.uuid = function(){ return java.util.UUID.randomUUID() + '' };
+ // this is wrong, the "nested" uuid will be lost
+ return config;
+}
+```
+
+The recommended best-practice is to move the `uuid` function into a common feature file following the pattern described [here](#multiple-functions-in-one-file):
+
+```javascript
+function fn() {
+ var config = {};
+ config.utils = karate.call('utils.feature')
+ return config;
+}
+```
+
+But you can opt for using [`karate.toMap()`](#karate-tomap) which will "wrap" things so that the nested objects are not "lost":
+
+```javascript
+function fn() {
+ var config = {};
+ var utils = {};
+ utils.uuid = function(){ return java.util.UUID.randomUUID() + '' };
+ config.utils = karate.toMap(utils);
+ return config;
+}
+```
+
## Switching the Environment
There is only one thing you need to do to switch the environment - which is to set a Java system property.
@@ -883,7 +928,7 @@ Advanced users who build frameworks on top of Karate have the option to supply a
## Script Structure
Karate scripts are technically in '[Gherkin](https://docs.cucumber.io/gherkin/reference/)' format - but all you need to grok as someone who needs to test web-services are the three sections: `Feature`, `Background` and `Scenario`. There can be multiple Scenario-s in a `*.feature` file, and at least one should be present. The `Background` is optional.
-> Variables set using [`def`](#def) in the `Background` will be re-set before *every* `Scenario`. If you are looking for a way to do something only **once** per `Feature`, take a look at [`callonce`](#callonce). On the other hand, if you are expecting a variable in the `Background` to be modified by one `Scenario` so that later ones can see the updated value - that is *not* how you should think of them, and you should combine your 'flow' into one scenario. Keep in mind that you should be able to comment-out a `Scenario` or skip some via [`tags`](#tags) without impacting any others. Note that the [parallel runner](#parallel-execution) will run `Scenario`-s in parallel, which means they can run in *any* order.
+> Variables set using [`def`](#def) in the `Background` will be re-set before *every* `Scenario`. If you are looking for a way to do something only **once** per `Feature`, take a look at [`callonce`](#callonce). On the other hand, if you are expecting a variable in the `Background` to be modified by one `Scenario` so that later ones can see the updated value - that is *not* how you should think of them, and you should combine your 'flow' into one scenario. Keep in mind that you should be able to comment-out a `Scenario` or skip some via [`tags`](#tags) without impacting any others. Note that the [parallel runner](#parallel-execution) will run `Scenario`-s in parallel, which means they can run in *any* order. If you are looking for ways to do something only *once* per feature or across *all* your tests, see [Hooks](#hooks).
Lines that start with a `#` are comments.
```cucumber
@@ -1068,7 +1113,7 @@ A few special built-in variables such as `$` (which is a [reference to the JSON
A [special case](#remove-if-null) of embedded expressions can remove a JSON key (or XML element / attribute) if the expression evaluates to `null`.
#### Rules for Embedded Expressions
-They work only within JSON or XML. And the expression *has* to start with `"#(` and end with `)` - so note that string-concatenation may not work quite the way you expect:
+* They work only within JSON or XML and when on the Right Hand Side of a `def` or `match` or when you [`read()`](#reading-files) a JSON or XML file. And the expression *has* to start with `"#(` and end with `)` - so note that string-concatenation may not work quite the way you expect:
```cucumber
# wrong !
@@ -1106,7 +1151,7 @@ And def lang = 'en'
> So how would you choose between the two approaches to create JSON ? [Embedded expressions](#embedded-expressions) are useful when you have complex JSON [`read`](#reading-files) from files, because you can auto-replace (or even [remove](#remove-if-null)) data-elements with values dynamically evaluated from variables. And the JSON will still be 'well-formed', and editable in your IDE or text-editor. Embedded expressions also make more sense in [validation](#ignore-or-validate) and [schema-like](#schema-validation) short-cut situations. It can also be argued that the `#` symbol is easy to spot when eyeballing your test scripts - which makes things more readable and clear.
### Multi-Line Expressions
-The keywords [`def`](#def), [`set`](#set), [`match`](#match), [`request`](#request) and [`eval`](#eval) take multi-line input as the last argument. This is useful when you want to express a one-off lengthy snippet of text in-line, without having to split it out into a separate [file](#reading-files). Here are some examples:
+The keywords [`def`](#def), [`set`](#set), [`match`](#match), [`request`](#request) and [`eval`](#eval) take multi-line input as the last argument. This is useful when you want to express a one-off lengthy snippet of text in-line, without having to split it out into a separate [file](#reading-files). Note how triple-quotes (`"""`) are used to enclose content. Here are some examples:
```cucumber
# instead of:
@@ -1289,7 +1334,7 @@ For those who may prefer [YAML](http://yaml.org) as a simpler way to represent d
```
### `yaml`
-A very rare need is to be able to convert a string which happens to be in YAML form into JSON, and this can be done via the `yaml` type cast keyword. For example - if a response data element or downloaded file is YAML and you need to use the data in subsequent steps.
+A very rare need is to be able to convert a string which happens to be in YAML form into JSON, and this can be done via the `yaml` type cast keyword. For example - if a response data element or downloaded file is YAML and you need to use the data in subsequent steps. Also see [type conversion](#type-conversion).
```cucumber
* text foo =
@@ -1321,7 +1366,7 @@ Karate can read `*.csv` files and will auto-convert them to JSON. A header row i
In rare cases you may want to use a csv-file as-is and *not* auto-convert it to JSON. A good example is when you want to use a CSV file as the [request-body](#request) for a file-upload. You could get by by renaming the file-extension to say `*.txt` but an alternative is to use the [`karate.readAsString()`](#read-file-as-string) API.
### `csv`
-Just like [`yaml`](#yaml), you may occasionally need to convert a string which happens to be in CSV form into JSON, and this can be done via the `csv` keyword.
+Just like [`yaml`](#yaml), you may occasionally need to [convert a string](#type-conversion) which happens to be in CSV form into JSON, and this can be done via the `csv` keyword.
```cucumber
* text foo =
@@ -1483,7 +1528,6 @@ Then status 202
```
## Type Conversion
-
> Best practice is to stick to using only [`def`](#def) unless there is a very good reason to do otherwise.
Internally, Karate will auto-convert JSON (and even XML) to Java `Map` objects. And JSON arrays would become Java `List`-s. But you will never need to worry about this internal data-representation most of the time.
@@ -1760,7 +1804,11 @@ Note that any cookies returned in the HTTP response would be automatically set f
Also refer to the built-in variable [`responseCookies`](#responsecookies) for how you can access and perform assertions on cookie data values.
## `form field`
-HTML form fields would be URL-encoded when the HTTP request is submitted (by the [`method`](#method) step). You would typically use these to simulate a user sign-in and then grab a security token from the [`response`](#response). For example:
+HTML form fields would be URL-encoded when the HTTP request is submitted (by the [`method`](#method) step). You would typically use these to simulate a user sign-in and then grab a security token from the [`response`](#response).
+
+Note that the `Content-Type` header will be automatically set to: `application/x-www-form-urlencoded`. You just need to do a normal `POST` (or `GET`).
+
+For example:
```cucumber
Given path 'login'
@@ -1950,16 +1998,22 @@ You can adjust configuration settings for the HTTP client used by Karate using t
`readTimeout` | integer | Set the read timeout (milliseconds). The default is 30000 (30 seconds).
`proxy` | string | Set the URI of the HTTP proxy to use.
`proxy` | JSON | For a proxy that requires authentication, set the `uri`, `username` and `password`, see example below. Also a `nonProxyHosts` key is supported which can take a list for e.g. `{ uri: 'http://my.proxy.host:8080', nonProxyHosts: ['host1', 'host2']}`
+`localAddress` | string | see [`karate-gatling`](karate-gatling#configure-localaddress)
`charset` | string | The charset that will be sent in the request `Content-Type` which defaults to `utf-8`. You typically never need to change this, and you can over-ride (or disable) this per-request if needed via the [`header`](#header) keyword ([example](karate-demo/src/test/java/demo/headers/content-type.feature)).
`retry` | JSON | defaults to `{ count: 3, interval: 3000 }` - see [`retry until`](#retry-until)
`outlineVariablesAuto` | boolean | defaults to `true`, whether each key-value pair in the `Scenario Outline` example-row is automatically injected into the context as a variable (and not just `__row`), see [`Scenario Outline` Enhancements](#scenario-outline-enhancements)
`lowerCaseResponseHeaders` | boolean | Converts every key and value in the [`responseHeaders`](#responseheaders) to lower-case which makes it easier to validate for e.g. using [`match header`](#match-header) (default `false`) [(example)](karate-demo/src/test/java/demo/headers/content-type.feature).
-`httpClientClass` | string | See [karate-mock-servlet](karate-mock-servlet)
-`httpClientInstance` | Java Object | See [karate-mock-servlet](karate-mock-servlet)
-`userDefined` | JSON | See [karate-mock-servlet](karate-mock-servlet)
-`responseHeaders` | JSON / JS function | See [karate-netty](karate-netty#configure-responseheaders)
-`cors` | boolean | See [karate-netty](karate-netty##configure-cors)
-
+ `abortedStepsShouldPass` | boolean | defaults to `false`, whether steps after a [`karate.abort()`](#karate-abort) should be marked as `PASSED` instead of `SKIPPED` - this can impact the behavior of 3rd-party reports, see [this issue](https://github.com/intuit/karate/issues/755) for details
+`logModifier` | Java Object | See [Log Masking](#log-masking)
+`httpClientClass` | string | See [`karate-mock-servlet`](karate-mock-servlet)
+`httpClientInstance` | Java Object | See [`karate-mock-servlet`](karate-mock-servlet)
+`userDefined` | JSON | See [`karate-mock-servlet`](karate-mock-servlet)
+`responseHeaders` | JSON / JS function | See [`karate-netty`](karate-netty#configure-responseheaders)
+`cors` | boolean | See [`karate-netty`](karate-netty#configure-cors)
+`driver` | JSON | See [UI Automation](karate-core)
+`driverTarget` | JSON / Java Object | See [`configure driverTarget`](karate-core#configure-drivertarget)
+
+> If you are mixing Karate into an existing Java project via Maven or Gradle, it can happen that the version of the Apache HTTP client used by Karate conflicts with something in the existing classpath. This can cause `* configure ssl = true` to fail. Read [this answer on Stack Overflow](https://stackoverflow.com/a/52396293/143475) for more details.
Examples:
```cucumber
@@ -2011,6 +2065,33 @@ And this short-cut is also supported which will disable all logs:
* configure report = false
```
+Since you can use `configure` any time within a test, you have control over which requests or steps you want to show / hide.
+
+### Log Masking
+In cases where you want to "mask" values which are sensitive from a security point of view from the output files, logs and HTML reports, you can implement the [`HttpLogModifier`](karate-core/src/main/java/com/intuit/karate/http/HttpLogModifier.java) and tell Karate to use it via the [`configure`](#configure) keyword. Here is an [example](karate-demo/src/test/java/demo/headers/DemoLogModifier.java) of an implementation. For performance reasons, you can implement `enableForUri()` so that this "activates" only for some URL patterns.
+
+Instantiating a Java class and using this in a test is easy (see [example](karate-demo/src/test/java/demo/headers/headers-masking.feature)):
+
+```cucumber
+# if this was in karate-config.js, it would apply "globally"
+* def LM = Java.type('demo.headers.DemoLogModifier')
+* configure logModifier = new LM()
+```
+
+Or globally in [`karate-config.js`](#karate-configjs)
+
+```js
+var LM = Java.type('demo.headers.DemoLogModifier');
+karate.configure('logModifier', new LM());
+```
+
+Since `karate-config.js` is processed for every `Scenario`, you can use a singleton instead of calling `new` every time. Something like this:
+
+```js
+var LM = Java.type('demo.headers.DemoLogModifier');
+karate.configure('logModifier', LM.INSTANCE);
+```
+
### System Properties for SSL and HTTP proxy
For HTTPS / SSL, you can also specify a custom certificate or trust store by [setting Java system properties](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#InstallationAndCustomization). And similarly - for [specifying the HTTP proxy](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html).
@@ -2032,12 +2113,12 @@ Key | Type | Required? | Description
Example:
```
# enable X509 certificate authentication with PKCS12 file 'certstore.pfx' and password 'certpassword'
-* configure ssl = { keyStore: 'classpath:certstore.pfx', keyStorePassword: 'certpassword', keyStoreType: 'pkcs12' };
+* configure ssl = { keyStore: 'classpath:certstore.pfx', keyStorePassword: 'certpassword', keyStoreType: 'pkcs12' }
```
```
# trust all server certificates, in the feature file
-* configure ssl = { trustAll: true };
+* configure ssl = { trustAll: true }
```
```
@@ -2045,6 +2126,8 @@ Example:
karate.configure('ssl', { trustAll: true });
```
+For end-to-end examples in the Karate demos, look at the files in [this folder](karate-demo/src/test/java/ssl).
+
# Payload Assertions
## Prepare, Mutate, Assert.
Now it should be clear how Karate makes it easy to express JSON or XML. If you [read from a file](#reading-files), the advantage is that multiple scripts can re-use the same data.
@@ -2120,7 +2203,7 @@ If you are wondering about the finer details of the `match` syntax, the left-han
* variable name - e.g. `foo`
* a 'named' JsonPath or XPath expression - e.g. `foo.bar`
* any valid function or method call - e.g. `foo.bar()` or `foo.bar('hello').baz`
-* or anything wrapped in parantheses which will be evaluated - e.g. `(foo + bar)` or `(42)`
+* or anything wrapped in parentheses which will be evaluated - e.g. `(foo + bar)` or `(42)`
And the right-hand-side can be any valid [Karate expression](#karate-expressions). Refer to the section on [JsonPath short-cuts](#jsonpath-short-cuts) for a deeper understanding of 'named' JsonPath expressions in Karate.
@@ -2428,6 +2511,14 @@ In some cases where the response JSON is wildly dynamic, you may want to only ch
# * match foo == { bar:1, baz: 'hello' }
```
+Note that `match contains` will "recurse", so any nested JSON chunks will also be matched using `match contains`:
+
+```cucumber
+* def original = { a: 1, b: 2, c: 3, d: { a: 1, b: 2 } }
+* def expected = { a: 1, c: 3, d: { b: 2 } }
+* match original contains expected
+```
+
Also note that [`match contains any`](#match-contains-any) is possible for JSON objects as well as JSON arrays.
### (not) `!contains`
@@ -2545,6 +2636,10 @@ The `match` keyword can be made to iterate over all elements in a JSON array usi
* match each data.foo contains { baz: "#? _ != 'z'" }
* def isAbc = function(x) { return x == 'a' || x == 'b' || x == 'c' }
* match each data.foo contains { baz: '#? isAbc(_)' }
+
+# this is also possible, see the subtle difference from the above
+* def isXabc = function(x) { return x.baz == 'a' || x.baz == 'b' || x.baz == 'c' }
+* match each data.foo == '#? isXabc(_)'
```
Here is a contrived example that uses `match each`, [`contains`](#match-contains) and the [`#?`](#self-validation-expressions) 'predicate' marker to validate that the value of `totalPrice` is always equal to the `roomPrice` of the first item in the `roomInformation` array.
@@ -3004,6 +3099,17 @@ Then status 201
And assert responseTime < 1000
```
+## `responseType`
+Karate will attempt to parse the raw HTTP response body as JSON or XML and make it available as the [`response`](#response) value. If parsing fails, Karate will log a warning and the value of `response` will then be a plain string. You can still perform string comparisons such as a [`match contains`](#match-text-or-binary) and look for error messages etc. In rare cases, you may want to check what the "type" of the `response` is and it can be one of 3 different values: `json`, `xml` and `string`.
+
+So if you really wanted to assert that the HTTP response body is well-formed JSON or XML you can do this:
+
+```cucumber
+When method post
+Then status 201
+And match responseType == 'json'
+```
+
## `requestTimeStamp`
Very rarely used - but you can get the Java system-time (for the current [`response`](#response)) at the point when the HTTP request was initiated (the value of `System.currentTimeMillis()`) which can be used for detailed logging or custom framework / stats calculations.
@@ -3022,7 +3128,7 @@ This makes setting up of complex authentication schemes for your test-flows real
Here is an example JavaScript function that uses some variables in the context (which have been possibly set as the result of a sign-in) to build the `Authorization` header. Note how even [calls to Java code](#calling-java) can be made if needed.
-> In the example below, note the use of the [`karate.get()`](#karate-get) helper for getting the value of a dynamic variable. This is preferred because it takes care of situations such as if the value is `undefined` in JavaScript. In rare cases you may need to *set* a variable from this routine, and a good example is to make the generated UUID "visible" to the currently executing script or feature. You can easily do this via [`karate.set('someVarName', value)`](#karate-set).
+> In the example below, note the use of the [`karate.get()`](#karate-get) helper for getting the value of a dynamic variable (which was *not set* at the time this JS `function` was *declared*). This is preferred because it takes care of situations such as if the value is `undefined` in JavaScript. In rare cases you may need to *set* a variable from this routine, and a good example is to make the generated UUID "visible" to the currently executing script or feature. You can easily do this via [`karate.set('someVarName', value)`](#karate-set).
```javascript
function fn() {
@@ -3057,9 +3163,9 @@ A JavaScript function or [Karate expression](#karate-expressions) at runtime has
Operation | Description
--------- | -----------
-karate.abort() | you can prematurely exit a `Scenario` by combining this with [conditional logic](#conditional-logic) like so: `* if (condition) karate.abort()` - please use [sparingly](https://martinfowler.com/articles/nonDeterminism.html) !
+karate.abort() | you can prematurely exit a `Scenario` by combining this with [conditional logic](#conditional-logic) like so: `* if (condition) karate.abort()` - please use [sparingly](https://martinfowler.com/articles/nonDeterminism.html) ! and also see [`configure abortedStepsShouldPass`](#configure)
karate.append(... items) | useful to create lists out of items (which can be lists as well), see [JSON transforms](#json-transforms)
-karate.appendTo(name, ... items) | useful to append to a list-like variable (that has to exist) in scope, see [JSON transforms](#json-transforms)
+karate.appendTo(name, ... items) | useful to append to a list-like variable (that has to exist) in scope, see [JSON transforms](#json-transforms) - the first argument can be a reference to an array-like variable or even the name (string) of an existing variable which is list-like
karate.call(fileName, [arg]) | invoke a [`*.feature` file](#calling-other-feature-files) or a [JavaScript function](#calling-javascript-functions) the same way that [`call`](#call) works (with an optional solitary argument)
karate.callSingle(fileName, [arg]) | like the above, but guaranteed to run **only once** even across multiple features *and* parallel threads (recommended only for advanced users) - refer to this example: [`karate-config.js`](karate-demo/src/test/java/karate-config.js) / [`headers-single.feature`](karate-demo/src/test/java/demo/headers/headers-single.feature)
karate.configure(key, value) | does the same thing as the [`configure`](#configure) keyword, and a very useful example is to do `karate.configure('connectTimeout', 5000);` in [`karate-config.js`](#configuration) - which has the 'global' effect of not wasting time if a connection cannot be established within 5 seconds
@@ -3070,12 +3176,12 @@ Operation | Description
karate.filter(list, predicate) | functional-style 'filter' operation useful to filter list-like objects (e.g. JSON arrays), see [example](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/js-arrays.feature), the second argument has to be a JS function (item, [index]) that returns a `boolean`
karate.filterKeys(map, keys) | extracts a sub-set of key-value pairs from the first argument, the second argument can be a list (or varargs) of keys - or even another JSON where only the keys would be used for extraction, [example](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/js-arrays.feature)
`karate.forEach(list, function)` | functional-style 'loop' operation useful to traverse list-like (or even map-like) objects (e.g. JSON / arrays), see [example](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/js-arrays.feature), the second argument has to be a JS function (item, [index]) for lists and (key, [value], [index]) for JSON / maps
-karate.get(name) | get the value of a variable by name (or JsonPath expression), if not found - this returns `null` which is easier to handle in JavaScript (than `undefined`)
+karate.get(name, [default]) | get the value of a variable by name (or JsonPath expression), if not found - this returns `null` which is easier to handle in JavaScript (than `undefined`), and an optional second argument can be used to return a "default" value, very useful to set variables in called features that have not been pre-defined
karate.info | within a test (or within the [`afterScenario`](#configure) function if configured) you can access metadata such as the `Scenario` name, refer to this example: [`hooks.feature`](karate-demo/src/test/java/demo/hooks/hooks.feature)
karate.jsonPath(json, expression) | brings the power of [JsonPath](https://github.com/json-path/JsonPath) into JavaScript, and you can find an example [here](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/js-arrays.feature).
karate.keysOf(object) | returns only the keys of a map-like object
karate.listen(timeout) | wait until [`karate.signal(result)`](#karate-signal) has been called or time-out after `timeout` milliseconds, see [async](#async)
-karate.log(... args) | log to the same logger (and log file) being used by the parent process, logging can be suppressed with [`configure printEnabled`](#configure) set to `false`
+karate.log(... args) | log to the same logger (and log file) being used by the parent process, logging can be suppressed with [`configure printEnabled`](#configure) set to `false`, and just like [`print`](#print) - use comma-separated values to "pretty print" JSON or XML
karate.lowerCase(object) | useful to brute-force all keys and values in a JSON or XML payload to lower-case, useful in some cases, see [example](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/lower-case.feature)
karate.map(list, function) | functional-style 'map' operation useful to transform list-like objects (e.g. JSON arrays), see [example](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/js-arrays.feature), the second argument has to be a JS function (item, [index])
karate.mapWithKey(list, string) | convenient for the common case of transforming an array of primitives into an array of objects, see [JSON transforms](#json-transforms)
@@ -3096,13 +3202,17 @@ Operation | Description
karate.setXml(name, xmlString) | rarely used, refer to the example above
karate.signal(result) | trigger an event that [`karate.listen(timeout)`](#karate-listen) is waiting for, and pass the data, see [async](#async)
karate.sizeOf(object) | returns the size of the map-like or list-like object
+karate.stop() | will pause the test execution until a socket connection is made to the port logged to the console, useful for troubleshooting UI tests without using a [de-bugger](https://twitter.com/KarateDSL/status/1167533484560142336), of course - *NEVER* forget to remove this after use !
+karate.target(object) | currently for web-ui automation only, see [target lifecycle](karate-core#target-lifecycle)
karate.tags | for advanced users - scripts can introspect the tags that apply to the current scope, refer to this example: [`tags.feature`](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/tags.feature)
karate.tagValues | for even more advanced users - Karate natively supports tags in a `@name=val1,val2` format, and there is an inheritance mechanism where `Scenario` level tags can over-ride `Feature` level tags, refer to this example: [`tags.feature`](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/tags.feature)
karate.toBean(json, className) | converts a JSON string or map-like object into a Java object, given the Java class name as the second argument, refer to this [file](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/type-conv.feature) for an example
karate.toJson(object) | converts a Java object into JSON, and `karate.toJson(object, true)` will strip all keys that have `null` values from the resulting JSON, convenient for unit-testing Java code, see [example](karate-demo/src/test/java/demo/unit/cat.feature)
+karate.toList(object) | rarely used - when still within a JS block, you need to convert a JSON array into a Java `List`
+karate.toMap(object) | rarely used - when still within a JS block, you need to convert a JSON object into a Java `Map`, or you are setting up [complex global variables](#restrictions-on-global-variables)
karate.valuesOf(object) | returns only the values of a map-like object (or itself if a list-like object)
karate.webSocket(url, handler) | see [websocket](#websocket)
-karate.write(object, path) | writes the bytes of `object` to a path which will *always* be relative to the "build" directory (typically `target`), see this example: [`embed-pdf.js`](karate-demo/src/test/java/demo/embed/embed-pdf.js) - and this method returns a `java.io.File` reference to the file created / written to
+karate.write(object, path) | *normally not recommended, please [read this first](https://stackoverflow.com/a/54593057/143475)* - writes the bytes of `object` to a path which will *always* be relative to the "build" directory (typically `target`), see this example: [`embed-pdf.js`](karate-demo/src/test/java/demo/embed/embed-pdf.js) - and this method returns a `java.io.File` reference to the file created / written to
karate.xmlPath(xml, expression) | Just like [`karate.jsonPath()`](#karate-jsonpath) - but for XML, and allows you to use dynamic XPath if needed, see [example](karate-junit4/src/test/java/com/intuit/karate/junit4/xml/xml.feature).
# Code Reuse / Common Routines
@@ -3116,6 +3226,8 @@ When you have a sequence of HTTP calls that need to be repeated for multiple tes
Here is an example of using the `call` keyword to invoke another feature file, loaded using the [`read`](#reading-files) function:
+> If you find this hard to understand at first, try looking at this [set of examples](karate-demo/src/test/java/demo/callfeature/call-feature.feature).
+
```cucumber
Feature: which makes a 'call' to another re-usable feature
@@ -3228,6 +3340,16 @@ Variable | Refers To
Refer to this [demo feature](karate-demo) for an example: [`kitten-create.feature`](karate-demo/src/test/java/demo/calltable/kitten-create.feature)
+### Default Values
+Some users need "callable" features that are re-usable even when variables have not been defined by the calling feature. Normally an undefined variable results in nasty JavaScript errors. But there is an elegant way you can specify a default value using the [`karate.get()`](#karate-get) API:
+
+```cucumber
+# if foo is not defined, it will default to 42
+* def foo = karate.get('foo', 42)
+```
+
+> A word of caution: we recommend that you should not over-use Karate's capability of being able to re-use features. Re-use can sometimes result in negative benefits - especially when applied to test-automation. Prefer readability over re-use. See this for an [example](https://stackoverflow.com/a/54126724/143475).
+
### `copy`
For a [`call`](#call) (or [`callonce`](#callonce)) - payload / data structures (JSON, XML, Map-like or List-like) variables are 'passed by reference' which means that steps within the 'called' feature can update or 'mutate' them, for e.g. using the [`set`](#set) keyword. This is actually the intent most of the time and is convenient. If you want to pass a 'clone' to a 'called' feature, you can do so using the rarely used `copy` keyword that works very similar to [type conversion](#type-conversion). This is best explained in the last scenario of this example: [`copy-caller.feature`](karate-junit4/src/test/java/com/intuit/karate/junit4/demos/copy-caller.feature)
@@ -3294,6 +3416,24 @@ Shared | [`call-updates-config.feature`](karate-demo/src/test/java/demo/headers/
> Once you get comfortable with Karate, you can consider moving your authentication flow into a 'global' one-time flow using [`karate.callSingle()`](#karate-callsingle), think of it as '[`callonce`](#callonce) on steroids'.
+#### `call` vs `read()`
+Since this is a frequently asked question, the different ways of being able to re-use code (or data) are summarized below.
+
+Code | Description
+---- | -----------
+`* def login = read('login.feature')``* call login` | [Shared Scope](#shared-scope), and the
`login` variable can be re-used +`* call read('login.feature')` | short-cut for the above
without needing a variable +`* def credentials = read('credentials.json')`
`* def login = read('login.feature')`
`* call login credentials` | Note how using [`read()`](#reading-files)
for a JSON file returns *data* -
not "callable" code, and here it is
used as the [`call`](#call) argument +`* call read('login.feature') read('credentials.json')` | You *can* do this in theory,
but it is not as readable as the above +`* karate.call('login.feature')` | The [JS API](#karate-call) allows you to do this,
but this will *not* be [Shared Scope](#shared-scope) +`* def result = call read('login.feature')` | [`call`](#call) result assigned to a variable
and *not* [Shared Scope](#shared-scope) +`* def result = karate.call('login.feature')` | exactly equivalent to the above ! +`* def credentials = read('credentials.json')`
`* def result = call read('login.feature') credentials` | like the above,
but with a [`call`](#call) argument +`* def credentials = read('credentials.json')`
`* def result = karate.call('login.feature', credentials)` | like the above, but in [JS API](#karate-call) form,
the advantage of the above form is
that using an in-line argument is less
"cluttered" (see next row) +`* def login = read('login.feature')`
`* def result = call login { user: 'john', password: 'secret' }` | using the `call` keyword makes
passing an in-line JSON argument
more "readable" +`* call read 'credentials.json'` | Since "`read`" happens to be a
[*function*](#calling-javascript-functions) (that takes a single
string argument), this has the effect
of loading *all* keys in the JSON file
into [Shared Scope](#shared-scope) as [variables](#def) !
This *can* be [sometimes handy](karate-core#locator-lookup). +`* call read ('credentials.json')` | A common mistake. First, there
is no meaning in `call` for JSON.
Second, the space after the "`read`"
makes this equal to the above. + ### Calling Java There are examples of calling JVM classes in the section on [Java Interop](#java-interop) and in the [file-upload demo](karate-demo). Also look at the section on [commonly needed utilities](#commonly-needed-utilities) for more ideas. @@ -3465,6 +3605,14 @@ In some rare cases you need to exit a `Scenario` based on some condition. You ca * if (responseStatus == 404) karate.abort() ``` +Using `karate.abort()` will *not* fail the test. Conditionally making a test fail is easy with JavaScript: + +```cucumber +* if (condition) throw 'a custom message' +``` + +But normally a [`match`](#match) statement is preferred unless you want a really descriptive error message. + Also refer to [polling](#polling) for more ideas. ## Commonly Needed Utilities @@ -3590,7 +3738,7 @@ A little-known capability of the Cucumber / Gherkin syntax is to be able to tag ```cucumber Scenario Outline: examples partitioned by tag * def vals = karate.tagValues -* match vals.region[0] == '
Before
+ Waiting
+
+
diff --git a/examples/ui-test/src/test/java/ui/test.feature b/examples/ui-test/src/test/java/ui/test.feature
new file mode 100644
index 000000000..51821db94
--- /dev/null
+++ b/examples/ui-test/src/test/java/ui/test.feature
@@ -0,0 +1,17 @@
+Feature: ui test
+
+Scenario Outline:
+ GET /cats | GET /hardcoded
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/examples/zip-release/src/demo/web/google.feature b/examples/zip-release/src/demo/web/google.feature
new file mode 100644
index 000000000..66f1b6ae9
--- /dev/null
+++ b/examples/zip-release/src/demo/web/google.feature
@@ -0,0 +1,20 @@
+Feature: web-browser automation
+ for help, see: https://github.com/intuit/karate/wiki/ZIP-Release
+
+Background:
+ * configure driver = { type: 'chrome' }
+
+Scenario: try to login to github
+ and then do a google search
+
+ Given driver 'https://github.com/login'
+ And input('#login_field', 'dummy')
+ And input('#password', 'world')
+ When submit().click("input[name=commit]")
+ Then match html('#js-flash-container') contains 'Incorrect username or password.'
+
+ Given driver 'https://google.com'
+ And input("input[name=q]", 'karate dsl')
+ When submit().click("input[name=btnI]")
+ # this may fail depending on which part of the world you are in !
+ Then waitForUrl('https://github.com/intuit/karate')
diff --git a/karate-apache/pom.xml b/karate-apache/pom.xml
index 6256a307c..371e5a98b 100755
--- a/karate-apache/pom.xml
+++ b/karate-apache/pom.xml
@@ -5,13 +5,13 @@
+
+# Index
+
+port | default
executable | description ----- | ---------------- | ---------------------- | ----------- +The recommendation is that you prefer `chrome` for development, and once you have the tests running smoothly - you can switch to a different WebDriver implementation. + +type | default port | default executable | description +---- | ------------ | ------------------ | ----------- [`chrome`](https://chromedevtools.github.io/devtools-protocol/) | 9222 | mac: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
win: `C:/Program Files (x86)/Google/Chrome/Application/chrome.exe` | "native" Chrome automation via the [DevTools protocol](https://chromedevtools.github.io/devtools-protocol/) [`chromedriver`](https://sites.google.com/a/chromium.org/chromedriver/home) | 9515 | `chromedriver` | W3C Chrome Driver [`geckodriver`](https://github.com/mozilla/geckodriver) | 4444 | `geckodriver` | W3C Gecko Driver (Firefox) [`safaridriver`](https://webkit.org/blog/6900/webdriver-support-in-safari-10/) | 5555 | `safaridriver` | W3C Safari Driver [`mswebdriver`](https://docs.microsoft.com/en-us/microsoft-edge/webdriver) | 17556 | `MicrosoftWebDriver` | W3C Microsoft Edge WebDriver +[`iedriver`](https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver) | 5555 | `IEDriverServer` | IE (11 only) Driver [`msedge`](https://docs.microsoft.com/en-us/microsoft-edge/devtools-protocol/) | 9222 | `MicrosoftEdge` | *very* experimental - using the DevTools protocol [`winappdriver`](https://github.com/Microsoft/WinAppDriver) | 4727 | `C:/Program Files (x86)/Windows Application Driver/WinAppDriver` | Windows Desktop automation, similar to Appium [`android`](https://github.com/appium/appium/) | 4723 | `appium` | android automation via [Appium](https://github.com/appium/appium/) [`ios`](https://github.com/appium/appium/) | 4723 |`appium` | iOS automation via [Appium](https://github.com/appium/appium/) -## Locators +# Distributed Testing +Karate can split a test-suite across multiple machines or Docker containers for execution and aggregate the results. Please refer to the wiki: [Distributed Testing](https://github.com/intuit/karate/wiki/Distributed-Testing). + +# Locators The standard locator syntax is supported. For example for web-automation, a `/` prefix means XPath and else it would be evaluated as a "CSS selector". ```cucumber -And driver.input('input[name=someName]', 'test input') -When driver.submit("//input[@name='commit']") +And input('input[name=someName]', 'test input') +When submit().click("//input[@name='commit']") ``` platform | prefix | means | example ----- | ------ | ----- | ------- web | (none) | css selector | `input[name=someName]` web
android
ios | `/` | xpath | `//input[@name='commit']` -web | `^` | link text | `^Click Me` -web | `*` | partial link text | `*Click Me` +web | `{}` | [exact text content](#wildcard-locators) | `{a}Click Me` +web | `{^}` | [partial text content](#wildcard-locators) | `{^a}Click Me` win
android
ios| (none) | name | `Submit` win
android
ios | `@` | accessibility id | `@CalculatorResults` win
android
ios | `#` | id | `#MyButton` ios| `:` | -ios predicate string | `:name == 'OK' type == XCUIElementTypeButton` -ios| `^` | -ios class chain | ``^**/XCUIElementTypeTable[`name == 'dataTable'`]`` +ios| `^` | -ios class chain | `^**/XCUIElementTypeTable[name == 'dataTable']` android| `-` | -android uiautomator | `-input[name=someName]` -## Keywords -Only one keyword sets up UI automation in Karate, typically by specifying the URL to open in a browser. And then you would use the built-in [`driver`](#js-api) JS object for all other operations, combined with Karate's [`match`](https://github.com/intuit/karate#prepare-mutate-assert) syntax for assertions where needed. +## Wildcard Locators +The "`{}`" and "`{^}`" locator-prefixes are designed to make finding an HTML element by *text content* super-easy. You will typically also match against a specific HTML tag (which is preferred, and faster at run-time). But even if you use "`{*}`" (or "`{}`" which is the equivalent short-cut) to match *any* tag, you are selecting based on what the user *sees on the page*. + +When you use CSS and XPath, you need to understand the internal CSS class-names and XPath structure of the page. But when you use the visible text-content, for example the text within a `