RestReplay Documentation

1. RestReplay Introduction

RestReplay is a utility to send REST requests to the services layer (including JSON, XML, and multipart XML requests), read responses, and compare
the resulting payloads with templates. 

At the end of a run, RestReplay produces a report, such as this self-test sample report, which shows you a summary and detail of all the calls to your services layer.  The reports have both a high-level view for administration and monitoring, and a low-level view useful for debugging issues or communicating results to developers or QA.

RestReplay was designed to fit into Continuous Integration tools such as Maven and Jenkins.  You can run RestReplay continuously, for service layer monitoring.  Developers can run RestReplay during a developer build, and Build Administrators can run RestReplay on commit, tag, or push events, to ensure a build produces a services layer that survives integration testing.

RestReplay is designed for simple, file-based, DRY configuration, that is programmable by beginning programmers. (It also has APIs for advanced users who wish to drive the tests from Java, or extend test types by writing plugins.)  For most users, however, look through our self-test source code for full examples of running tests, chaining tests, looping tests, and validating result IDs.  RestReplay is also designed to be configured many ways, for many kinds of projects.  A good, safe bet is to follow the style in our self-test.  See: self-test sample report and self-test source code.

All configuration parameters are covered below, in the order of the configuration XML files, after the discussion of the command line.  You can use the handy links in the Quick Reference cards on this page to jump to the different elements to read syntax and examples.

RestReplay lets you automate entire workflows over your REST layer.  You can automate tests to login, request resources and APIs, extract data from the response, such as resource IDs, and use these IDs in subsequent tests.  For example, each of these would be a test within one testGroup called OrderFlow: 

• OrderFlow
  
• POST to login,
  
• PUT a new order and extract the ID returned,
  
• GET the latest list of orders,
• GET the invoice for the order ID,
  
• DELETE the order,
  
• GET the order to make sure it is gone. 
  

RestReplay executes the tests in this order you specify, and lets you pass variables in and out of each test.  Each test can also have a small bit of code to count json arrays, dig in with jsonp or XPath, etc.  These are documented below.

Most things are done for you by the framework, so you just specify the URL, the type of request, and create files for any POST or upload content, and hit Go!  RestReplay runs your request, and  reports on the result.  Many times, success in testing and monitoring is just knowing that a particular sequence of HTTP transactions succeeded.   For these kinds of testing, there is no programming.  You'll merely replace values with variables that you define, such as ${ORDER_ID}, as you wire the tests together. 

Using the examples in our self-test, the documentation below, the Jexl Documentation, and our Javadoc, you can also program RestReplay to do more complicated workflows.

1.a. Features

• Completely configurable via XML.
• Abstracts each transaction with server as a "test".
• Tests are easily configured to:
• loop a number of times
• re-run over a list of values for one variable, or multiple variables
• mutate requests to send automatically variable data such as dates
• mutate requests to remove required and optional fields to test service schema compliance
• All request payloads and expected response payload templates are stored as files within the deployed test. Note that only JSON and XML respons payloads are stored, not HTML.
• Multiple tests can be grouped in a testGroup element, and each test may refer to previous tests within testGroup. 
• This naturally models workflows from UX hitting a  REST services layer, e.g. a resource is created in one test, then its ID, available in the response, is used by the next test to modify that resource.
• TestGroups are run by Master control files, which let you centralize environments, e.g. testing against dev, qa, production.
• Optional Automatic cleanup of resources allocated within a testGroup.
• Send and receive JSON and XML payloads or MIME-multipart payloads.
• Variable expansion in: URLs, headers, request payloads, and response payloads.
• Javascript(Rhino) and Jexl2 for scripting and expression evaluation.
• Simple reporting of results on console and in surefire reports.
• Full reporting of results in html report output directory.
• Java programmatic interface for driving the tests and testGroups, and for finer control of reporting and cleanup.

1.b Overview

RestReplay is run from the command line (or ant, maven, or Jenkins).  It reads your configuration files, and along with startup parameters, determines which testGroups and which tests to run.  Along the way, it initializes and evaluates any variables you have set up, such as hosts, ports, resource IDs, logins, and so on. 

It runs the tests in the order you define, synchronously.  As each test is run, it exports variables which become available to subsequent tests.  Also after each test, the response is evaluated for schema correctness, and any Validator you have defined can run using Jexl or Javascript code. Read more about the runtime workflow at 1.d.1 Runtime.

So you can think of it following stories, or use cases, or workflows, exercising your services layer. 

After the tests have run, RestReplay compiles a directory of stand-alone reports that drill down from your high level view (the Master) to the detail view (the individual testGroup/test reports).  Tweaking the RunOptions gives you control over the output on the command line, and also in the HTML report.  These reports do not depend on anything else, and can be archived, since they show stats, results, documentation of your APIs, and contain all the input and output payloads.  See: self-test sample report

After the tests have run, you can check the code coverage of your services layer with external tools such as EclEmma / JaCoCo, and also use other queries to check the state of your datastores. 

RestReplay tests your services, but it also drives them exactly as a user or bot would, so think of the next steps in your integration testing.

1.c Concepts

See the Reference Documentation for syntax, structure, discussion, and examples of code.  This section covers concepts that are common to many of the configurable and scriptable elements documented in the Reference Documentation.

1.c.1 Expressions

Expressions are defined using Jexl syntax.

Expressions are always evaluated in a context. (Actually, a series of nested contexts, similar to Javascript scoping.  RestReplay automatically provides these contexts, for each testGroup, eachTest, and each evaluation.)  Some values and tools will always be available in the context, such as "kit", "tools", and "this".  For running tests, all previously run tests are available, by ID, in the context.  So any value sent to or received from a service, either from URLs, Headers, or payloads, can be retrieved using an expression.  You can place values into the context with the var element.

An expression is evaluated just before it is used.  (Subsequent evaluations use the latest values available from referenced data sources.) An expression in a test will not be evaluated until that test is run.  Expressions stored elsewhere and referenced (such as Master vars, and headers) are also evaluated just as the test is run.   Exported vars are evaluated after the test is run, and retain their values for the rest of the run through the testGroup.

Expressions are strings.  They are surrounded by bash-like braces: ${ORDER_ID}  looks up the value of the expression ORDER_ID.  If ORDER_ID is defined in the "context" then its value is returned.  Say ORDER_ID is set to a string: "abc123" , then the expression's value is like so:

Now we could use this value in an expression to get a resource by URL:

and RestReplay will hit the service:

You can also have more complicated expressions, like:

These expressions were used in vars, explained here

See also: 3.a.4 Jexl Script for an example of using a more complicated Jexl expression.

1.c.2 Values in Contexts

In Jexl Expressions

serviceResult	org.dynamide.restreplay.ServiceResult - also stored as "this". Contains all vars and results, as well as IDs, timing, stati, etc.
this	org.dynamide.restreplay.ServiceResult - also stored as "serviceResult".
serviceResultsMap	Map<String, org.dynamide.restreplay.ServiceResult> - a map of all previously run tests in this same testGroup, kept in insertion order of the tests run. Key is the ID of the test element. The special values thisand result are also available in the serviceResultsMap, and point to the current serviceResult.
tools	org.dynamide.util.Tools
kit	org.dynamide.restreplay.Kit
this.mutator.getIndex()	- zero-based index of which mutation loop this is.
__FILE__	String name of the validator file. (only available in validators)
this.LoopIndex	If this test is run as a loop, then you can know the zero-based loop index by calling this.LoopIndex

Javascript contexts get the same objects.  Additionally, the following methods are useful in javascript.  Note that "this" in Javascript is NOT the serviceResult.

kit.newStringArray(int)	var stringArray = kit.newStringArray(r.count); for (var i=0; i<r.count; i++){ stringArray[i] = r.orders[i].order_id; }
serviceResult.result	The body of the response. If it is JSON, you can turn it into a javascript object with: var r = JSON.parse(serviceResult.result);
serviceResult.mutator.getIndex()	zero-based index of which mutation loop this is.
serviceResult.mutator.getMutationId()	Unique string name of this mutation, formatted by the mutator.

You may specify that a test should loop. You supply either the loop="" attribute, or the <loop> element, with an expression that returns a number, an array, a Collection, or a Map (see Loop examples) The loop value is a Jexl expression, or an integer. For example:

• 10
• ${['a', 'b', 'c']}
• ${{'key-a':'a', 'key-b':'b', 'key-c':'c']}
• ${[200, 404, 202]}
• ${otherTest.exportedVarCollection}
• ${[{'a':'aVal', 'b':'bVal'},{'c':'cVal', 'd':'dVal'}]}

For maps:
   loop.value == loop[loop.key]
For arrays:
   loop.value == loop[loop.index]
                    

1.c.3 Common Useful Methods in Contexts

Note that the variable named "this" is equivalent to serviceResult in the following examples, e.g. these two statements are identical:

• this.addExport("myexport", "Foo Bar")
• serviceResult.addExport("myexport", "Foo Bar").

this.addExport(key,value)	Creates a var as an export, available to subsequent tests. Exports added with this.addExport() get tracked automatically if called from a Validator, and the list of exports added per validator is shown in the detail report as an Alert from the validator. The values of these exports can then be seen in the variables row (exports are a different background color--see Legend at bottom of page). See the discussion under 3.a.1.DELETE for an example of using addExport().
this.testID
this.testGroupID
this.testIDLabel
this.idFromMutator
this.fullURL
this.deleteURL
this.mutator.getIndex()	zero-based index of which mutation loop this is.
this.mutator.getMutationId()	Unique string name of this mutation, formatted by the mutator.
this.mutationID	Same as this.getMutationId()
kit.dates.*

1.c.4 Vars

The vars/var tag appears in several places in the configuration file trees.
They use the same rules discussed under /restReplay/testGroup/vars/var.

Vars in different xml config elements have different scoping rules.

Here are the places vars can exist:

    /restReplay/testGroup/vars/var
    /restReplay/testGroup/test/vars/var
    /restReplay/testGroup/test/exports/vars/var
    /restReplayMaster/vars/var
    /restReplayMaster/env/vars/var
    /restReplayMaster/run/vars/var

See also: 3.a.4 Jexl Script for an example of using a more complicated Jexl expression as a var.

Here is the list of vars shown above in the discussion on 1.c.1 Expressions

1.c.5 Headers

See: /restReplay/testGroup/headers/header

1.c.6 Expected Codes

See /restReplay/testGroup/test/expected/code

1.c.7 Mutators

See /restReplay/testGroup/test/mutator

1.c.8 Looping

You can loop tests two ways with RestReplay.  First, you can use <test ID="myLoopyTest" loop="2">...</test> to loop a test.  Of course, the value provided to the loop parameter can be a Jexl Expression, so you can run the loop a variable number of times:

<test ID="deleteOrders" loop="${size(ordersListTest.ORDER_IDS)}">

See a full example in 3.a.1 DELETE

You can also loop using a VarMutator.

1.c.9 AutoDelete

1.d.1 Runtime

At runtime, RestReplay consults parameters passed in on the command line, or from maven surefire, or from java:exec which uses parameters found in the pom.xml project file under options for the exec-maven-plugin plugin.

RestReplay then determines which master file to use. This file points to testGroups in control files that contain tests.

The default behavior of RestReplay is to look for a directory, called the RestReplay directory. This is defined using -testdir parameter.

When running inside maven surefire, this is pre-defined to be a resource directory in the source code module. Maven defines a variable called basedir, which points at the project directory for the current pom.xml. In the pom.xml file, you can point maven exec:java at the testdir (called "tests" in this example) like so:

Within the RestReplay directory, there are various master files, some control files, and directories for each service. You can select a particular master with the command line parameter -master

Most services should define their control file within their directory, e.g.

For development, you may define your own master. See "2.c. Running"
For integration testing, use the predefined master file called master.xml.

Within a control file, RestReplay finds testGroup elements as specified on the command line or in the master file, and then runs these testGroup elements.

For each testGroup, a namespace is set up that will contain the results of all tests run in that testGroup, and any variables defined as the test runs. This namespace contains variables that dereference to java objects, so Strings, Date objects, etc. may be put into the namespace. For every test, RestReplay creates a named object of type org.dynamide.restreplay.ServiceResult, so that after that test has run, you may pull fields out of the ServiceResult object, such as responseCode, fullURL, location, and calculated fields such as from the Location: header.

You may also use methods on the ServiceResult object that give you XPath access to any field in any part either sent or recieved from the server in that test.

ServiceResult methods and fields:

For each "test" node in a testGroup, RestReplay sets up a request, using the URI (which may contain expressions), the http method, and any parts specified for a POST or a PUT. The parts are read from text files in a directory relative to the RestReplay base directory, and may contain/define variables which get passed in. The value of these variables is evaluated in the control file just prior to the test node being run. So previous tests may be referenced. The parts are expanded for any expressions, and then put together in the appropriate http sequence and submitted to the server. The response from the server is then made available to the test to check using the "response" node. Note that only JSON and XML responses are reported, not HTML. The "response" node allows you to specify a template file to compare, and any  variables declared will be evaluated just prior to comparing the response from the server to the response template file.

After the testGroup has run, RestReplay will perform cleanup. You may control cleanup via the "autoDeletePOSTS" attribute of "testGroup".

• If true, then RestReplay does a DELETE on each resource allocated.
• If false, RestReplay does no automatic DELETEs.

You may also programmatically call RestReplay, in which case you can programmatically control cleanup of individual tests. See "2.c.4 Cleanup"

Finally, results are aggregated and spit out to the command line console, and/or to reports. You can customize how verbose these results are using the "dump" node in the master file.  Regardless of dump settings, all results go to the stand-alone html reports.

If all testGroups and all tests succeed, then RestReplay tells maven surefire that the suite succeeded. Otherwise, maven surefire is told that the suite failed. In this case, you may examine the console, or look at the maven surefire report, which will contain a tabular summary of all testGroups and tests. You may have to click "show all results" in the maven surefire report.

RestReplay also creates a stand-alone report. Look at the command line output where RestReplay will report the location of this HTML report, e.g. something of this form:

This reports directory starts with an index file named after any master file you have run, which links to individual control file results.

1.e Tools

RestReplay reports include sections that help developers debug their test cases. On the Master page, you can optionally turn on the ResourceManager Summary. You can also optionally provide an onSummary event, which can be used to spit out all the APIs called, for example. On the detail pages, the EvalReport is always included.

1.e.1 EvalReport

The EvalReport shows all evaluations of variables whilst running tests. The output is organized in the order that tests are run. To see detail all the way into expressions containing expressions, click the link at the top of the EvalReport called "Show EvalReport Detail".

For each TestGroup.Test, there is a link to the test output, the vars and references are shown, then all evaluations are shown with expansions/substitutions. Each expansion shows its context, then its raw value, then its expanded value. Vars are any legal variable names that are accessed, whilst references are expressions that are evaluated that may point to imports or other tests. (See the Legend at the bottom of the report page for more info on how the EvalReport is presented.)

By tracing these vars and references, you can refactor your tests so that each Test or TestGroup imports and exports variables, rather than expressions that create messy dependencies. (A clean dependency is when testA exports a variable, and testB imports that variable but testB does not have a complicated expression that digs info out of testA.)

1.e.2 ResourceManager Summary

The ResourceManager Summary shows every resource that is pulled from the file system or the class path (which can reference resources stored in the RestReplay jar file). Relative resource names are reported, plus attributes related to how that resource was found.

• base - The path to the testdir or jar file
• foundPath - The full, resolved path to the resource
• source - [FILE,CLASSPATH,STREAM,URL,ZIP,NOTFOUND] What type of resource / where found
• context - What phase of testing asked for this resource
• doc - either the full path of the resource, or the name of the root element in an XML Document
• cached - After two references, resources are cached in memory

1.e.2 onSummary event

There is an example of how to write this script in the source distribution under RestReplay/src/main/resources/restreplay/_self_test/s/master-self-test-onSummary.js By using this onSummary script, you can spit out all the APIs called during a run.
Documentation is here: /restReplayMaster/event

2. Reference Documentation

2.a. Installation

RestReplay is downloaded as a jar, so you simply put this jar on your classpath and run it, with some options. Alternatively, you can integrate RestReplay into your Maven build. To run it on Jenkins, just make RestReplay.jar available on the Jenkins job's classpath, and use the command line parameters.

To see the structure of the testdir that will hold your tests, un-jar the RestReplay.jar file, and look for the subdirectory src/main/resources/restreplay/. This is our -testdir. In it we have defined a project called _self-test. The _self-test project has working, precise tests that cover most of our functionality. To write tests, you'll want to look at a body of tests, such as our _self-test which has great examples, and uses the organizational features of RestReplay. You should also have a -testdir, and have some organization that stores tests by groups that make sense for your project. Feel free to mimic the structure of _self-test. But know that RestReplay can run this _self-test from the classpath, that is, from the copy inside the jar file. So if you don't obscure the name _self-test, then you can always run our test suite on startup, which simply tests that everything works from RestReplay, over http to a local, temporary test service it spins up. You can copy, and or override the _self-test to do your bidding if you need a custom setup. This works because the tests are found on your -testdir path first, and if not, are looked up from the jar file. In this same way, the reports use our CSS file, which you can override once you see the path from the jar file. So in our jar file is the resource src/main/resources/restreplay/_includes/reports-include.css, which you can override with a copy in your -testdir directory structure like so, where TEST_DIR is the directory where you have told RestReplay is the root of all your tests:
TEST_DIR/_includes/reports-include.css

2.b. Configuration

2.b.1 General Rules

General Variable Syntax: starts with letter or underscore (_), contains letters, numbers, underscore. No other special characters, especially not the dollar-sign ($).

For an ID attribute to be valid, please use General Variable Syntax.

Element names should also follow the General Variable Syntax.

General Filename syntax: please stick to General Variable Syntax plus hyphen (-) and period (.).

Filenames may contain the delimiter / to denote directories. These will be transformed into platform-specific directory separators.

2.c Running

You can run RestReplay on the command-line, or from the command-line of maven surefire.

To run from the command line, using a jar distribution, then this example would run the environment local using the directory /.tests for control files and will put reports in /.tests/reports. From that directory, it will find the master control file, master.xml .

This would run RestReplay, telling it where to find tests, and which master to run.  It also passes in an environment ID, which selects per-environment settings from the master file's <env> section.

To run using the maven surefire test, which will find _self_test/master-self-test.xml on the path or in the Jar file:

Or, to override the port that the self-test will open, use:

To run using the maven surefire test pointed at a master, e.g. master.xml in ./tests/, simply:

or define your own master file, which you create:

2.c.1 Command-line parameters

Here are some more examples of running on the command line.

In this run, we are hitting the control file pi/pitoken.xml with no master file.  So we specify testGroup, test within that control file.

In this run, we are running with a -master and a -control, AND a -testGroup.  This runs only that testGroup, but picks up vars and headers from the master. (Since no /restReplayMaster/run element is used, there are no vars from /restReplayMaster/run/vars.

In this run, we are sending reports to a different directory (./myreports) than the default (tests/reports)

2.c.2 XML configuration parameters in master file

Click on an element to jump to documentation for that element and its attributes.

  <restReplayMaster>
      <dump/>
      <auths>
          <auth>
      </auths>
      <runOptions>
          <connectionTimeout>
          <socketTimeout>
          <errorsBecomeEmptyStrings>
          <acceptAlertLevel>
          <skipMutators>
          <skipMutatorsOnFailure>
          <dumpMasterSummary>
          <dumpRunOptions>
          <dumpResourceManagerSummary>
          <reportResourceManagerSummary>
          <reportResponseRaw>
          <reportPayloadsAsXML>
          <failTestOnErrors>
          <failTestOnWarnings>
          <outputServiceResultDB>
      </runOptions>
      <vars>
          <var />
      </vars>
      <envs>
          <vars>
            <var />
          </vars>
      </envs>
      <event />
      <run />
          <vars>
              <var />
          </vars>
      </run>
  </restReplayMaster>

online: 
    http://www.motobit.com/util/base64-decoder-encoder.asp.
                  
    https://www.base64encode.org/


javascript in browser: 
    function utf8_to_b64(str) {
        return window.btoa(unescape(encodeURIComponent("myusername:mypassword")));
    }
    utf8_to_b64("myusername:mypassword");
   
dynamide:   
    (new com.dynamide.util.Base64Encoder("myusername:mypassword")).processString();

{rest-replay-base-directory}/runOptions.xml is the best place to do site-wide settings for RestReplay.
It contains a <runOptions> root element.

All of these options can be controlled in a master file, too.
In this case, your master file contains <runOptions> under the root element <restReplayMaster>

When overriding RunOptions in a master file, consider these two development scenarios:
            1) you are developing locally, and are setting per-test cases while you run tests,
               and you may or may not check in your changes.
                  In this case, change any settings you like as close to the testCase as you can in the chain:
                        runOptions > master > testGroup > testCase
                  But feel free to change runOptions.xml and your master file, which ever is easiest.
	          Before committing your code, validate that you no longer need those options, 
                     or consider coordinating the change with the team, since these settings affect many tests.

            2) you are committing this master to source control, so that it gets picked up by automated builds.
                   In this case, you should have a reason, coordinated with your team, 
                   for overriding the default file (runOptions.xml) or the master for each project.

    Options:
        "connectionTimeout"
        "socketTimeout"
            The most reasonable override in a master file's RunOptions is the timeouts:
            these may vary by service, or host
            so one clean organization of test would be by services
            or known clusters of hosts with particular timeouts.
            You could have one control file, say, "master-edge-services.xml",
            with one testGroup, "timeCriticalServices", and in that testGroup put all the services from,
            say, a time-critical cluster.  In that control file,
            set the RunOption timeouts to be low.  In the Master, set the timeouts to be more "normal".
            All the other tests will run with "normal", and tests in master-edge-services.xml
            in testGroup "timeCriticalServices" will run with low timeouts.

        "errorsBecomeEmptyStrings" would be set locally if you were debugging.

        "dumpResourceManagerSummary" should probably be best left
           to the central location in the file (runOptions.xml)
           since it controls output to the console.

        "skipMutators" will skip processing for Mutators.  Mutators take one test and replays it with modified payloads.


    The heirarchy is:
       RunOptions : class defaults
         runOptions.xml : default for all tests
           my-master.xml :  overrides properties for this master.
                            You can have many masters and run them all from the command line
                            or test suite by using the startup command-line parameter:
                                -master relative-path-to-master-file
                            or for maven, surefire, etc:
                                -Dmaster=relative-path-to-master-file

2.c.3 XML configuration parameters in control file

Click on an element to jump to documentation for that element and its attributes.

  <restReplay>
      <auths>
          <auth></auth>
      </auths>
      <testGroup>
          <comment />
          <imports />
          <protoHostPort />
          <vars />
          <headers />
          <test>
              <comment />
              <method />
              <uri />
              <filename />
              <expected>
                <code />
              </expected>
              <mutator>
                  <expected>
                    <code />
                  </expected>
              </mutator>
              <vars>
                  <var />
              </vars>
              <exports>
                  <vars>
                      <var />
                  </vars>
              </exports>
              <headers>
                  <header />
              </headers>
              <parts>
                  <part>
                      <label />
                      <filename />
                      <var />
                  </part>
              </parts>
              <response>
                  <expected>
                      <dom />
                      <code />
                  </expected>
                  <validator/>  
                  <parts>
                      <part>
                          <label />
                          <filename />
                          <var />
                      </part>
                  </parts>
              </response>
          </test>
      </testGroup>
  </restReplay>

2.c.4 Cleanup

After the testGroup has run, RestReplay will perform cleanup. You may control cleanup via the "autoDeletePOSTS" attribute of "testGroup". If true, then any POSTs that returned a "Location: " header will result in RestReplay sending a DELETE on that Location: URL. If false, RestReplay will perform no automated cleanup for that testGroup. If you called RestReplay programmatically, then you may initiate cleanup manually by calling on these methods of org.dynamide.restreplay.RestReplay

or

3. RestReplay Examples

3.a.1 Using DELETE for lists of resources.

Say we had a service listening on /api/orders that would return a list of orders we had created. It might return JSON like this:

Let's say previous tests have populated some Orders, and now we want to clean them all up. We could use autoDeletePOST or set up Delete URLs, but here is how to set up the REST workflow manually. We could set up two tests in one testGroup in RestReplay: one to call the service to get this list, and a second to delete all the resources found on the list.

        
            GET
            /api/orders
            
                orders/res/getOrdersAfterCreate.validator.js
            
        


          
              DELETE
              /api/orders/${getOrdersAfterCreate.ORDER_IDS[this.LoopIndex]}
          
        

The first test calls the file orders/res/getOrdersAfterCreate.validator.js Here is what is in that file:

Now let's walk through what we have done.

In this example, we first run a test called getOrdersAfterCreate, which gets the list of orders, after some other tests have created Order resources on the server.

After the response comes back, RestReplay runs any validator found, in this case orders/res/getOrdersAfterCreate.validator.js which is shown below. This validator looks into the JSON that came back, and digs out the count and the orders order_id's. If the count were not sent by your server, you can use Javascript to find the length of the r.orders array. This validator builds up a Java Array of String, then passes back to the test as an export.

Note that to create Java arrays of String, or String[], you must call either the long version:

var ordersArray = java.lang.reflect.Array.newInstance(java.lang.String, r.count);

var ordersArray = kit.newStringArray(theCount);

Then we run the delete test, which looks at the array of order IDs in the export getOrdersAfterCreate.ORDER_IDS. This works because getOrdersAfterCreate is the name of the test, and each test stores its exported vars for use by subsequent tests.

Note that size() is a function provided by Jexl.  It looks at the length of arrays, and the size of collections.  Here we use it to tell RestReplay how many times to loop, so that we perform one DELETE request for each ID in the list.

Also, this.LoopIndex is a loop counter provided by RestReplay when looping.

Specifically, if getOrdersAfterCreate.ORDER_IDS is an array of string like ["abc123","abc456"],
then in memory it looks like this:

0	abc123
1	abc456

Then size(getOrdersAfterCreate.ORDER_IDS) is 2, and loop="${size(getOrdersAfterCreate.ORDER_IDS)}" turns into loop="2", so RestReplay will run deleteOrders 2 times so that the following 2 URI's get hit:

DELETE /api/orders/abc123
DELETE /api/orders/abc456

/api/orders/${getOrdersAfterCreate.ORDER_IDS[this.LoopIndex]}

/api/orders/${getOrdersAfterCreate.ORDER_IDS[0]}

/api/orders/abc123

/api/orders/${getOrdersAfterCreate.ORDER_IDS[this.LoopIndex]}

/api/orders/${getOrdersAfterCreate.ORDER_IDS[1]}

/api/orders/abc456

3.a.2 Using XPath to dig elements out of XML or JSON.

The serviceResult.got() method is used to get data nodes from tree-structured data received from the server. the key passed to got() is an XPath that will work on any XML request. JSON requests are mapped to XML for using XPath, and this works well. You can also use a validator, which will run Javascript and give you JSON dotted syntax.

In this case, the XPath is //data which means "find the value of the node called data, anywhere in the tree".

Note: you can use either XPath or JsonPath.

First, let's say we have a token service, that when called, returns some JSON like so, and all we need to grab from the token is the value of the data element from that JSON:

Now we call this service like so:

Subsequent tests can now make the token available to their own templates like so:

or can use the token in the URI like so:

in which case, the URI would expand to: /tagonomy?mock=true&token=id=ffffffff540e662de4b01ef1c4c50faf;token-expires=112567

3.a.3 Using XPath part 2

Next we'll show another way to export that same value, and some cleaner ways to use it. These are all equivalent to the code above in 3.a.2, Using XPath

Note: you can use either XPath or JsonPath.

First, the selftestToken could be modified to export a var

After which you can use the token in the URI like so:

or you can use the token in headers like so:

3.a.4 Jexl Script

Expressions in Jexl can span multiple lines, and have return statements, so they can be used as scripts. In this example, a complicated expression is made manageable by breaking it into lines and steps. But it is still one "expression".

3.a.x More Examples

The best source for examples are the ones that run every time we build or install RestReplay: our _self-test. This ships with every RestReplay.jar, and can be unpacked from there, or can be seen on our _self-test GitHub page.

You can see the reports produced by our _self-test here: Sample Reports.

Especially, you can see all our tests here:
self-test.xml
master-self-test.xml
You can run these tests with a command line like this which will dump reports into the current directory in a directory called ./reports Use the latest version. For this example we use version 1.0.4 .

You can unpack the examples with this command:

Once unpacked, you'll see our _self-test in ./restreplay/_self_test/, and you notice that ./restreplay/ is our effective -testdir.