User Guide
Xplorer makes calling HTTP APIs easy and fun - and you can chain multiple calls to tell a story. Watch Video 1 | Watch Video 2.
One of the highlights is how you can view JSON as an easy-to-read grid. Xplorer is a great way to show-off what your APIs can do to business users. You can also view payloads as raw-text, with syntax-coloring.
Both Request and Response are shown side by side for convenience. You can add user-friendly labels to each API call for even better readability. Scripting support allows you to scale from simple hard-coded requests to dynamic URLs, headers and payloads and un-limited "chained" calls.
The application runs locally - which means that all your data is secure, you can test APIs that run on localhost or within your network, and you won't be blocked by CORS restrictions.
Here is a summary of features:
|
Note For a detailed feature list and roadmap, |
Download the ZIP file corresponding to your OS from the latest from the Releases Page.
| Windows | Mac M1 - M4 | Mac Intel | Linux |
|---|---|---|---|
| win32-x86_64 | macosx-aarch64 | macosx-x86_64 | (contact us) |
Note
A native installer is on the roadmap. If you face issues or if you want us to add support for your OS, please raise open a ticket or contact us.
Extract the ZIP into a directory of your choice. Then, depending on whether you are on Windows or Mac, follow the instructions below.
| Windows | Mac / Linux |
|---|---|
Directly click and open start.bat
|
Open a Terminal in the karate-xplorer folder and run ./start
|
| The first time, it may take a minute for the window to appear, so be patient | You can now close the Terminal without issues |
Use the [Help > Samples] menu to choose from a set of built-in samples that show you the power of Xplorer.
Click on Run All (to run all requests) or the
If you want the URL to be set "globally" you can do this via a global Config Variable. Use the [Options > Show Configuration] menu to open the right panel and view or edit the environment variables.
Chaining can be done by directly referring to specific parts of the previous response. This can be done using expressions in this form: ${response.body.someName}.
For example, here we use a value from the previous response as a path parameter. The placeholder-substitution system uses the "dollar" and "curly braces" convention, for example: ${foo}
Placeholder substitution is supported for all the following:
URL | Path | Body | Headers | Params
Examples of how you can dynamically set headers are shown below:
Header manipulation is essential for getting past many authorization schemes.
Here below are examples of how to shape query parameters:
You can "save" data that persists for the whole sequence. This is commonly needed to perform CRUD via REST-ful HTTP calls.
For example you can use the After section to evaluate expressions. These are small snippets of simple JavaScript. Here we save id and booking for future reference. Note that the booking comes from the request ! This avoids the need for extensive cut-and-paste and can save you a lot of time.
The Before and After "action" phase can also be used to configure key behavior of the HTTP client. A very common need is to set all (future) headers to include an Authorization token. Here is one way to do it where we grab a property called access_token out of the response.
Values entered in
BeforeandAfterexpressions are pure JS expressions and don't need round-brackets or placeholders.
The next line then sets up all future headers to include { Authorization: 'Bearer ' + token } which is a simple JavaScript expression with string-concatenation.
Use the action type Set Config for the behavior settings. Make sure you hit Save after any changes.
A set of built-in functions are designed for common needs such as generating UUIDs or for date and time manipulations.
You can find a reference guide here: Built In Functions.
Here we are updating JSON by evaluating an expression. We change one value within the booking payload in the Before section.
Karate Xplorer has a short-cut to insert a variable into a payload or anywhere expressions are supported.
- If an expression is enclosed in round-brackets, it will be converted to JSON at run-time.
- The expression has to begin and end with round-brackets
This is most commonly used to set the Request:Body.
See how easy it is to re-use a variable that happens to be JSON. Look at the Body below set to (booking).
You can dynamically change JSON payloads using Karate-style JSON templating via variable substitution - for e.g. { foo: '#(bar)' }.
Here is an example of changing the totalPrice using the bookingPrice variable:
You can add multiple variables that will be initialized at the start of a run. The term xp.url is a "special" config variable that will be used as a "default" if no URL is provided for an individual call.
You can mix and match for convenience. For example you can change the URL for one single request, experiment with it and then change it back (or have it empty). You can also have xp.url defined as an Environment Variable as shown in the next example.
The example below shows how we can also set the data-type. Here, bookingPrice is expressed as a number by using round-brackets. You do the same for boolean values.
And in the rare case where you want to set a value to null, use: (null).
Variables or anything set up dynamically using Before and After actions can be any kind of JavaScript variable. That means strings, numbers, booleans, JS Objects, JS Arrays and even JS functions. Even the arrow notation is supported, which can keep concise the setting up of sophisticated dynamic behavior.
You can manage all environments in one view.
Switching then becomes a matter of using the drop-down in the top menu-bar.
The [File > Save] menu gives you the option to save the sequence currently being edited to your local-drive.
Karate Xplorer sequence files have to have the .kxp extension.
Note
To be able to use or convert imported data in Xplorer requires a paid subscription.
This is a tab in the right panel which can be opened via the menu [Options > Show Configuration]. Click on the [Open File] button to import any valid file.
Once imported you can click on each row-item of the API data imported and add it to your Xplorer sequence. You also have the option to directly export as a Karate test script without going through Xplorer. This is convenient for teams e.g. migrating from Postman or other HTTP clients. Watch the last part of this short video for a preview: Xplorer Highlights.
You can use the Export tab to export the Xplorer sequence you are working on as a Karate test. This is a great way for business-users to hand off flows to the development team for formal test-automation in CI/CD. You can now get the capabilities of HTML reports and performance testing.
You can re-format the response JSON (or any variable in scope) using a simple HTML templating system built-in to Xplorer. This is useful especially when dealing with JSON arrays. In fact there is an action specifically focused on rendering a JSON array into an HTML table.
See it in action below. Note how you can flatten a nested structure using path expressions if needed, see the use of company.name below.
Refer to the built-in demo samples, that even show rendering of images. For a quick intro to the templating system, refer HTML Templating. Also refer to this video of a practical use of the HTML Output system, making it easy for business users to understand a given system via APIs without having to depend on developers: Insurance Domain Example.