RestFixture (RestFixture 4.4 API)

java.lang.Object
- smartrics.rest.fitnesse.fixture.RestFixture

All Implemented Interfaces:: fitnesse.slim.StatementExecutorConsumer, RunnerVariablesProvider

public class RestFixture
extends Object
implements fitnesse.slim.StatementExecutorConsumer, RunnerVariablesProvider

A fixture that allows to simply test REST APIs with minimal efforts. The core principles underpinning this fixture are:

allowing documentation of a REST API by showing how the API looks like. For REST this means
- show what the resource URI looks like. For example /resource-a/123/resource-b/234
- show what HTTP operation is being executed on that resource. Specifically which one fo the main HTTP verbs where under test (GET, POST, PUT, DELETE, HEAD, OPTIONS).
- have the ability to set headers and body in the request
- check expectations on the return code of the call in order to document the behaviour of the API
- check expectation on the HTTP headers and body in the response. Again, to document the behaviour
should work without the need to write/maintain java code: tests are written in wiki syntax.
tests should be easy to write and above all read.

Configuring RestFixture
RestFixture can be configured by using the RestFixtureConfig. A RestFixtureConfig can define named maps with configuration key/value pairs. The name of the map is passed as second parameter to the RestFixture. Using a named configuration is optional: if no name is passed, the default configuration map is used. See RestFixtureConfig for more details.

The following list of configuration parameters can are supported.

supported configuration parameters
smartrics.rest.fitnesse.fixture.RestFixtureConfig	optional named config
http.proxy.host	http proxy host name (RestClient proxy configuration)
http.proxy.port	http proxy host port (RestClient proxy configuration)
http.basicauth.username	username for basic authentication (RestClient proxy configuration)
http.basicauth.password	password for basic authentication (RestClient proxy configuration)
http.client.connection.timeout	client timeout for http connection (default 3s). (RestClient proxy configuration)
http.client.use.new.http.uri.factory	If set to true uses a more relaxed validation rule to validate URIs. It, for example, allows array parameters in the query string. Defaults to false.
restfixture.requests.follow.redirects	If set to true the underlying client is instructed to follow redirects for the requests in the current fixture. This setting is not applied to POST and PUT (for which redirection is set to false) Defaults to true.
restfixture.resource.uris.are.escaped	boolean value. if true, RestFixture will assume that the resource uris are already escaped. If false, resource uri will be escaped. Defaults to false.
restfixture.display.actual.on.right	boolean value (default=true). if true, the actual value of the header or body in an expectation cell is displayed even when the expectation is met.
restfixture.display.absolute.url.in.full	boolean value (default=true). if true, absolute URLs in the fixture second column are rendered in their absolute format rather than relative.
restfixture.default.headers	comma separated list of key value pairs representing the default list of headers to be passed for each request. key and values are separated by a colon. Entries are sepatated by \n. `setHeader()` will override this value.
restfixture.xml.namespaces.context	comma separated list of key value pairs representing namespace declarations. The key is the namespace alias, the value is the namespace URI. alias and URI are separated by a = sign. Entries are sepatated by `System.getProperty("line.separator")`. These entries will be used to define the namespace context to be used in xpaths that are evaluated in the results.
restfixture.content.default.charset	The default charset name (e.g. UTF-8) to use when parsing the response body, when a response doesn't contain a valid value in the Content-Type header. If a default is not specified with this property, the fixture will use the default system charset, available via `Charset.defaultCharset().name()`
restfixture.content.handlers.map	a map of content type to type adapters, entries separated by \n, and kye-value separated by '='. Available type adapters are JS, TEXT, JSON, XML (see `BodyTypeAdapterFactory` ).
restfixture.null.value.representation	This string is used in replacement of the default string substituted when a null value is set for a symbol. Because now the RestFixture labels support is implemented on top of the Fitnesse symbols, such default value is defined in Fitnesse, and that is the string 'null'. Hence, every substitution that would result in rendering the string 'null' is replaced with the value set for this config key. This value can also be the empty string to replace null with empty.
restfixture.response.optimisation.threshold	a numeric value fixing a threshold for the response length to disable optimisation of javascript body. Default value is 65535. See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino/Optimization for details. If a JSON response or a JavaScript expression is larger than this threshold, then the optimisation level is set to -1. Otherwise set to 0 by default.
restfixture.javascript.imports.map	a map of name to Url/File path. Each entry refers to a url/path to a javascript file that is imported in the JS context and available for evaluation. Files are checked for existence and access. If not available/not accessible, an exception is thrown. Urls are tried to be downloaded. A failure in accessing the content causes an error/exception. The map key is the name of the library - it can be a freeform string that appears in logs for debugging purposes.

Author:: smartrics

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class RestFixture.Runner
What runner this table is running on.

Nested Classes
Modifier and Type	Class and Description
`static class`	`RestFixture.Runner` What runner this table is running on.

Field Summary

Fields
Modifier and Type	Field and Description
`protected String`	`fileName`
`protected Variables`	`GLOBALS`
`protected Map<String,smartrics.rest.client.RestMultipart>`	`multiFileNameByParamName`
`protected String`	`multipartFileName`
`protected String`	`multipartFileParameterName`
`protected String`	`requestBody`
`protected Map<String,String>`	`requestHeaders`
`protected boolean`	`resourceUrisAreEscaped`
`protected RowWrapper`	`row`

Constructor Summary

Constructors
Constructor and Description
`RestFixture()` Constructor for Fit runner.
`RestFixture(String hostName)` Constructor for Slim runner.
`RestFixture(String hostName, String configName)` Constructor for Slim runner.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addHeader()`
`Map<String,String>`	`addHeader(String headers)` \@sglebs - fixes #161.
`void`	`addHeaders()`
`void`	`addMultipartFile()` Allows setting of the the multi-part file to upload.
`void`	`addMultipartString()` Allows setting of the multi-part String.
`void`	`baseUrl(String url)`
`void`	`comment()` allows to add comments to a rest fixture - basically does nothing except ignoring the text.
`protected void`	`completeHttpMethodExecution()`
`protected BodyTypeAdapter`	`createBodyTypeAdapter()`
`protected BodyTypeAdapter`	`createBodyTypeAdapter(ContentType ct)`
`Variables`	`createRunnerVariables()` Get a variable store linked to the current runner environment.
`void`	`DELETE()` `\| DELETE \| uri \| ?ret \| ?headers \| ?body \|`
`protected void`	`doMethod(String body, String method)`
`protected void`	`doMethod(String method, String resUrl, Map<String,String> headers, String rBody)`
`protected void`	`doMethod(String method, String resUrl, String rBody)`
`List<List<String>>`	`doTable(List<List<String>> rows)` Slim Table table hook.
`protected String`	`emptifyBody(String b)`
`void`	`evalJs()` Evaluates a string using the internal JavaScript engine.
`void`	`GET()` `\| GET \| uri \| ?ret \| ?headers \| ?body \|`
`String`	`getBaseUrl()` The base URL as defined by the rest fixture ctor or input args.
`Config`	`getConfig()`
`Map<String,String>`	`getDefaultHeaders()` The default headers as defined in the config used to initialise this fixture.
`String`	`getFileName()`
`CellFormatter<?>`	`getFormatter()` The formatter for this instance of the RestFixture.
`Map<String,String>`	`getHeaders()`
`String`	`getLastEvaluation()`
`protected smartrics.rest.client.RestRequest`	`getLastRequest()`
`protected smartrics.rest.client.RestResponse`	`getLastResponse()`
`String`	`getMultipartFileName()`
`String`	`getMultipartFileParameterName()`
`protected Map<String,String>`	`getNamespaceContext()`
`protected String`	`getRequestBody()`
`void`	`HEAD()` `\| HEAD \| uri \| ?ret \| ?headers \| \|`
`protected void`	`initialize(RestFixture.Runner runner)`
`void`	`let()` `\| let \| label \| type \| loc \| expr \|`
`protected void`	`notifyInvalidState(boolean state)` Method invoked to notify that the state of the RestFixture is invalid.
`void`	`OPTIONS()` `\| OPTIONS \| uri \| ?ret \| ?headers \| ?body \|`
`protected Map<String,String>`	`parseHeaders(String str)`
`void`	`POST()` `\| POST \| uri \| ?ret \| ?headers \| ?body \|`
`void`	`processRow(RowWrapper<?> currentRow)` Process the row in input.
`void`	`PUT()` `\| PUT \| URL \| ?ret \| ?headers \| ?body \|`
`void`	`setBaseUrl(Url url)` sets the base url.
`void`	`setBody()` `\| setBody \| body text goes here \|`
`String`	`setBody(String body)` \@sglebs - fixes #162.
`protected void`	`setConfig(Config c)`
`void`	`setFileName()` Allows setting of the name of the file to upload.
`void`	`setHeader()` `\| setHeader \| http headers go here as nvp \|`
`Map<String,String>`	`setHeader(String headers)` \@sglebs - fixes #161.
`void`	`setHeaders()` Equivalent to setHeader - syntactic sugar to indicate that you can now.
`Map<String,String>`	`setHeaders(String headers)` \@sglebs - fixes #161.
`void`	`setMultipartFileName()` Allows setting of the name of the multi-part file to upload.
`void`	`setMultipartFileParameterName()` Sets the parameter to send in the request storing the multi-part file to upload.
`protected void`	`setRequestBody(String text)`
`void`	`setStatementExecutor(fitnesse.slim.StatementExecutorInterface arg0)`
`void`	`TRACE()` `\| TRACE \| uri \| ?ret \| ?headers \| ?body \|`
`protected boolean`	`validateState()` Overrideable method to validate the state of the instance in execution.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - GLOBALS
```
protected Variables GLOBALS
```
  - fileName
```
protected String fileName
```
  - multipartFileName
```
protected String multipartFileName
```
  - multipartFileParameterName
```
protected String multipartFileParameterName
```
  - multiFileNameByParamName
```
protected Map<String,smartrics.rest.client.RestMultipart> multiFileNameByParamName
```
  - requestBody
```
protected String requestBody
```
  - resourceUrisAreEscaped
```
protected boolean resourceUrisAreEscaped
```
  - requestHeaders
```
protected Map<String,String> requestHeaders
```
  - row
```
protected RowWrapper row
```
- Constructor Detail
  - RestFixture
```
public RestFixture()
```
    Constructor for Fit runner.
  - RestFixture
```
public RestFixture(String hostName)
```
    Constructor for Slim runner.
    
    Parameters:
    
    hostName - the cells following up the first cell in the first row.
  - RestFixture
```
public RestFixture(String hostName,
                   String configName)
```
    Constructor for Slim runner.
    
    Parameters:
    
    hostName - the cells following up the first cell in the first row.
    
    configName - the value of cell number 3 in first row of the fixture table.
- Method Detail
  - createRunnerVariables
```
public Variables createRunnerVariables()
```
    Description copied from interface: RunnerVariablesProvider
    
    Get a variable store linked to the current runner environment.
    
    Specified by:
    
    createRunnerVariables in interface RunnerVariablesProvider
    
    Returns:
    
    the variables
  - getConfig
```
public Config getConfig()
```
    Returns:
    
    the config used for this fixture instance
  - getLastEvaluation
```
public String getLastEvaluation()
```
    Returns:
    
    the result of the last evaluation performed via evalJs.
  - getBaseUrl
```
public String getBaseUrl()
```
    The base URL as defined by the rest fixture ctor or input args.
    
    Returns:
    
    the base URL as string
  - setBaseUrl
```
public void setBaseUrl(Url url)
```
    sets the base url.
    
    Parameters:
    
    url - the url
  - baseUrl
```
public void baseUrl(String url)
```
  - getDefaultHeaders
```
public Map<String,String> getDefaultHeaders()
```
    The default headers as defined in the config used to initialise this fixture.
    
    Returns:
    
    the map of default headers.
  - getFormatter
```
public CellFormatter<?> getFormatter()
```
    The formatter for this instance of the RestFixture.
    
    Returns:
    
    the formatter for the cells
  - doTable
```
public List<List<String>> doTable(List<List<String>> rows)
```
    Slim Table table hook.
    
    Parameters:
    
    rows - the rows to process
    
    Returns:
    
    the rendered content.
  - validateState
```
protected boolean validateState()
```
    Overrideable method to validate the state of the instance in execution. A RestFixture is valid if the baseUrl is not null.
    
    Returns:
    
    true if the state is valid, false otherwise
  - setConfig
```
protected void setConfig(Config c)
```
  - notifyInvalidState
```
protected void notifyInvalidState(boolean state)
```
    Method invoked to notify that the state of the RestFixture is invalid. It throws a RuntimeException with a message displayed in the FitNesse page.
    
    Parameters:
    
    state - as returned by validateState()
  - setMultipartFileName
```
public void setMultipartFileName()
```
    Allows setting of the name of the multi-part file to upload.
    | setMultipartFileName | Name of file |
    body text should be location of file which needs to be sent
  - addMultipartFile
```
public void addMultipartFile()
```
    Allows setting of the the multi-part file to upload.
    | addMultipartFile | Name of file | Name of form parameter for the uploaded file | ContentType of file | CharSet of file |
    body text should be location of file which needs to be sent
  - addMultipartString
```
public void addMultipartString()
```
    Allows setting of the multi-part String.
    | addMultipartString | String content | Name of form parameter | ContentType of String | CharSet of String |
    body text should be location of file which needs to be sent
  - getMultipartFileName
```
public String getMultipartFileName()
```
    Returns:
    
    the multipart filename
  - setFileName
```
public void setFileName()
```
    Allows setting of the name of the file to upload.
    | setFileName | Name of file |
    body text should be location of file which needs to be sent
  - getFileName
```
public String getFileName()
```
    Returns:
    
    the filename
  - setMultipartFileParameterName
```
public void setMultipartFileParameterName()
```
    Sets the parameter to send in the request storing the multi-part file to upload. If not specified the default is file
    | setMultipartFileParameterName | Name of form parameter for the uploaded file |
    body text should be the name of the form parameter, defaults to 'file'
  - getMultipartFileParameterName
```
public String getMultipartFileParameterName()
```
    Returns:
    
    the multipart file parameter name.
  - setBody
```
public void setBody()
```
    | setBody | body text goes here |
    body text can either be a kvp or a xml. The ClientHelper will figure it out
  - setBody
```
public String setBody(String body)
```
    \@sglebs - fixes #162. necessary to work with a scenario
    
    Parameters:
    
    body - the body to set
    
    Returns:
    
    the body after substitution
  - setHeader
```
public void setHeader()
```
    | setHeader | http headers go here as nvp |
    header text must be nvp. name and value must be separated by ':' and each header is in its own line
  - addHeader
```
public void addHeader()
```
  - addHeader
```
public Map<String,String> addHeader(String headers)
```
    \@sglebs - fixes #161. necessary to work with a scenario
    
    Parameters:
    
    headers - the headers string to set
    
    Returns:
    
    the headers map
  - setHeader
```
public Map<String,String> setHeader(String headers)
```
    \@sglebs - fixes #161. necessary to work with a scenario
    
    Parameters:
    
    headers - the headers string to set
    
    Returns:
    
    the headers map
  - setHeaders
```
public Map<String,String> setHeaders(String headers)
```
    \@sglebs - fixes #161. necessary to work with a scenario
    
    Parameters:
    
    headers - the headers string to set
    
    Returns:
    
    the headers map
  - setHeaders
```
public void setHeaders()
```
    Equivalent to setHeader - syntactic sugar to indicate that you can now.
    set multiple headers in a single call
  - addHeaders
```
public void addHeaders()
```
  - PUT
```
public void PUT()
```
    | PUT | URL | ?ret | ?headers | ?body |
    executes a PUT on the URL and checks the return (a string representation the operation return code), the HTTP response headers and the HTTP response body
    URL is resolved by replacing global variables previously defined with let()
    the HTTP request headers can be set via setHeaders(). If not set, the list of default headers will be set. See DEF_REQUEST_HEADERS
  - GET
```
public void GET()
```
    | GET | uri | ?ret | ?headers | ?body |
    executes a GET on the uri and checks the return (a string repr the operation return code), the http response headers and the http response body uri is resolved by replacing vars previously defined with let() the http request headers can be set via setHeaders(). If not set, the list of default headers will be set. See DEF_REQUEST_HEADERS
  - HEAD
```
public void HEAD()
```
    | HEAD | uri | ?ret | ?headers | |
    executes a HEAD on the uri and checks the return (a string repr the operation return code) and the http response headers. Head is meant to return no-body. uri is resolved by replacing vars previously defined with let() the http request headers can be set via setHeaders(). If not set, the list of default headers will be set. See DEF_REQUEST_HEADERS
  - OPTIONS
```
public void OPTIONS()
```
    | OPTIONS | uri | ?ret | ?headers | ?body |
    executes a OPTIONS on the uri and checks the return (a string repr the operation return code), the http response headers, the http response body uri is resolved by replacing vars previously defined with let() the http request headers can be set via setHeaders(). If not set, the list of default headers will be set. See DEF_REQUEST_HEADERS
  - DELETE
```
public void DELETE()
```
    | DELETE | uri | ?ret | ?headers | ?body |
    executes a DELETE on the uri and checks the return (a string repr the operation return code), the http response headers and the http response body uri is resolved by replacing vars previously defined with let() the http request headers can be set via setHeaders(). If not set, the list of default headers will be set. See DEF_REQUEST_HEADERS
  - TRACE
```
public void TRACE()
```
    | TRACE | uri | ?ret | ?headers | ?body |
  - POST
```
public void POST()
```
    | POST | uri | ?ret | ?headers | ?body |
    executes a POST on the uri and checks the return (a string repr the operation return code), the http response headers and the http response body uri is resolved by replacing vars previously defined with let() post requires a body that can be set via setBody(). the http request headers can be set via setHeaders(). If not set, the list of default headers will be set. See DEF_REQUEST_HEADERS
  - let
```
public void let()
```
    | let | label | type | loc | expr |
    allows to associate a value to a label. values are extracted from the body of the last successful http response.
    - label is the label identifier
    - type is the type of operation to perform on the last http response. At the moment only XPaths and Regexes are supported. In case of regular expressions, the expression must contain only one group match, if multiple groups are matched the label will be assigned to the first found type only allowed values are xpath and regex
    - loc where to apply the expr of the given type. Currently only header and body are supported. If type is xpath by default the expression is matched against the body and the value in loc is ignored.
    - expr is the expression of type type to be executed on the last http response to extract the content to be associated to the label.
    labels can be retrieved after they have been defined and their scope is the fixture instance under execution. They are stored in a map so multiple calls to let() with the same label will override the current value of that label.
    Labels are resolved in uris, headers and bodyes.
    In order to be resolved a label must be between %, e.g. %id%.
    The test row must have an empy cell at the end that will display the value extracted and assigned to the label.
    Example:
    | GET | /services | 200 | | |
    | let | id | body | /services/id[0]/text() | |
    | GET | /services/%id% | 200 | | |
    or
    | POST | /services | 201 | | |
    | let | id | header | /services/([.]+) | |
    | GET | /services/%id% | 200 | | |
  - comment
```
public void comment()
```
    allows to add comments to a rest fixture - basically does nothing except ignoring the text. the text is substituted if variables are found.
  - evalJs
```
public void evalJs()
```
    Evaluates a string using the internal JavaScript engine. Result of the last evaluation is set in the attribute lastEvaluation.
  - processRow
```
public void processRow(RowWrapper<?> currentRow)
```
    Process the row in input. Abstracts the test runner via the wrapper interfaces.
    
    Parameters:
    
    currentRow - the current row
  - initialize
```
protected void initialize(RestFixture.Runner runner)
```
  - emptifyBody
```
protected String emptifyBody(String b)
```
  - getHeaders
```
public Map<String,String> getHeaders()
```
    Returns:
    
    the request headers
  - getRequestBody
```
protected String getRequestBody()
```
  - setRequestBody
```
protected void setRequestBody(String text)
```
  - getNamespaceContext
```
protected Map<String,String> getNamespaceContext()
```
  - doMethod
```
protected void doMethod(String body,
                        String method)
```
  - doMethod
```
protected void doMethod(String method,
                        String resUrl,
                        String rBody)
```
  - doMethod
```
protected void doMethod(String method,
                        String resUrl,
                        Map<String,String> headers,
                        String rBody)
```
  - completeHttpMethodExecution
```
protected void completeHttpMethodExecution()
```
  - createBodyTypeAdapter
```
protected BodyTypeAdapter createBodyTypeAdapter()
```
  - createBodyTypeAdapter
```
protected BodyTypeAdapter createBodyTypeAdapter(ContentType ct)
```
  - getLastResponse
```
protected smartrics.rest.client.RestResponse getLastResponse()
```
  - getLastRequest
```
protected smartrics.rest.client.RestRequest getLastRequest()
```
  - parseHeaders
```
protected Map<String,String> parseHeaders(String str)
```
  - setStatementExecutor
```
public void setStatementExecutor(fitnesse.slim.StatementExecutorInterface arg0)
```
    Specified by:
    
    setStatementExecutor in interface fitnesse.slim.StatementExecutorConsumer

Class RestFixture

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GLOBALS

fileName

multipartFileName

multipartFileParameterName

multiFileNameByParamName

requestBody

resourceUrisAreEscaped

requestHeaders

row

Constructor Detail

RestFixture

RestFixture

RestFixture

Method Detail

createRunnerVariables

getConfig

getLastEvaluation

getBaseUrl

setBaseUrl

baseUrl

getDefaultHeaders

getFormatter

doTable

validateState

setConfig

notifyInvalidState

setMultipartFileName

addMultipartFile

addMultipartString

getMultipartFileName

setFileName

getFileName

setMultipartFileParameterName

getMultipartFileParameterName

setBody

setBody

setHeader

addHeader

addHeader

setHeader

setHeaders

setHeaders

addHeaders

PUT

GET

HEAD

OPTIONS

DELETE

TRACE

POST

let

comment

evalJs

processRow

initialize

emptifyBody

getHeaders

getRequestBody

setRequestBody

getNamespaceContext

doMethod

doMethod

doMethod

completeHttpMethodExecution

createBodyTypeAdapter

createBodyTypeAdapter

getLastResponse

getLastRequest

parseHeaders

setStatementExecutor