Category: How To
General introduction guides to the platform.
Copy a Test
- Are you looking to do negative testing? You can likely do that in the same test using data sets and the IF component + status codes.
- Are you looking to run from different environments? No problem with Presets.
- Do you want to run most but not all of the tests in a specific project? Execute tests using tags. (example, using a unique webhook and the ‘live’ tag.)
Write Tests in Code
Code View
First, the whole test can be seen and edited “naked,” without our glamorous UI. Behind the curtains, the test is described using the XML markup language. To use it, you simply need to look at the top right of the composer. The default is VISUAL COMPOSER, but right next to it is CODE VIEW. Click that. Now you will see the markup language that is the basis of API Fortress.More experienced testers may find this to be the most efficient manner to use the platform. Tip: The best way to learn the markup? Build your tests using the visual composer/magic, then switch to code view and have a look!
A Groovier Approach
Whether you are using the code view, or the visual composer, one important aspect to note is that all “evaluated” fields are actually able to execute a subset of Groovy commands.For example, let’s take this assertion that verifies whether the “items” element is an array.
Or in code view:
<assert-is expression="payload.whatever.items" type="array"/>
Or in code view
<assert-greater expression="payload.whatever.items.size()" value="3" type="integer"/>
Even More Serious Grooviness
Moreover, Groovy can be put within SET components. The first scenario is when you want to set a variable that is not a String. The best way to do it is using the Variable Mode “Object.” The value, in this case, will be evaluated as Groovy code.
<set var="number" object="otherNumber+50"/>
<set var="myVar" lang="java">
<![CDATA[
def item = payload.whatever.items.find { it -> it.id==11 }
return item.amount
]]>
</set>
Templating
What about all the fields that are not explicitly evaluated? Like URL, value, or POST Body? Or the content of a comment? It is often extremely useful to evaluate content on those as well. This is possible using the template syntax.<assert-equals expression="payload.id" value="${req_id}"/>
This assertion, for example, is evaluating the req_id variable right within the value.
A Little Bit of Everything
Let’s join everything we’ve learned into one snippet:<set var="data" lang="java"> <![CDATA[ def items = payoad.whatever.items.find{ it-> it.id>100} return items.collect{ it -> it.providerId} ]]> </set> <each expression="data"> <post url="http://www.example.com/${counter+1}" params="[:]" var="payload2" mode="json"> <postBody contentType="application/json"> <![CDATA[{"providerId":${_1}}]]> </postBody> </post> <set var="counter" object="counter+1"/> </each>
Want to learn more about Groovy?
Follow this link to the official documentation: http://groovy-lang.org/documentation.html Important Note For security concerns, the cloud version of API Fortress is sandboxed. Meaning many programming language features are disabled. Self-hosted/on-premises eliminates that restraint. While on cloud, if you think a specific feature should be safe to be enabled but is disabled, please contact us and we’ll do our best to help you!Build an Integration Test (Multistep Test)
- Add a “for each” assertion and reference the “resultsPayload.products” object.
- Add a new “Set (variable)” assertion to set the “id” variable as every single “resultsPayload.product” that is returned. Notice we set the string to “${_1.id}” The system uses _1 automatically when recognizing a subroutine. Makes it easier when things get into many sub levels.
- Make a GET to the product details endpoint, using our new “id” variable as the id parameter. Again, you can still reference the original “${access_token}” to make this call. Variables last through the entire test unless overwritten.
Generate a Status Page
Dealing with Authentication (Simple, oAuth, etc)
Introduction
API Fortress can handle nearly any authorization scheme. Below, we provide some guides on simple ways to work with the most common authorization methods. If it requires usage of a long lasting token, see here for more information.
Simple Authorization
- Enter the visual composer
- Click Add Component
- Click POST (or whatever REST method the authentication server is expecting)
- Enter details and then click Add Authentication
- Choose Basic
- Enter the Username and Password
The header information is automatically encoded and entered for you!
Next, we parameterize the token that we receive in the response.
- First, select the Set (variable) component
- Next, enter the name that you would like to use for the variable as Var
- Enter the value of the token itself as Value
- Add a Comment component with the previously set variable as the Value to see the token logged!
From here, we can use the token in follow-on prompts by referencing its variable name.
Here’s the process in video form!
Simple Authorization from the HTTP Client
Using the HTTP composer requires encoding the Username and Password yourself.
- Click on Tools > HTTP Client
- Click on Tools > Gadgets
- Choose base64-encode
- Type in the username and password like this with the semicolon “username:password”
- Click encode
- Copy the generated code (our example is VXNlcm5hbWU6UGFzc3dvcmQ=)
- Now use that generated code in your call. Specifically as a Header, and use the word “Basic” under key, and the generated code (VXNlcm5hbWU6UGFzc3dvcmQ=) for value.
That’s it! The call should work now. If not feel free to send us a message at support@apifortress.com!
oAuth/Token Exchange
- Enter the visual composer
- Click Add Component
- Click POST (or whatever REST method the authentication server is expecting)
- Enter details and add parameters or POST body
- In our example its a POST body with username and password
Next, we parameterize the token that we receive in the response.
- First, select the Set (variable) component
- Next, enter the name that you would like to use for the variable as Var
- Enter the reference to the token from the previous payload as Value
- Add a Comment component with the previously set variable as the Value to see the token logged!
- From here, we can use the token in subsequent API calls by referencing its variable name.
Use Long Lasting Tokens
- Prepare the input set by adding the basePath, loginPath, and dataPath. Most importantly, add an empty variable for token and expires. These items will be updated by the test.
- Add an IF component with this logic:
!expires || D.nowMillis()>expires.toLong()
- Within the IF branch, make the login call. Shown here is a call to the login URL. We are storing the retrieved information in the variable named “loginPayload.”
- Within the IF branch, set the value to token and expires. Note that in the value we’re saying: take the current time and add one hour
D.plusHours( D.nowMillis(), 1 )
- Within the if branch, update the input set. This is a unique feature of API Fortress. By performing this operation, you’re having the test modify itself for the next use by updating the token and the expires variables. By doing so, the token will be available for all tests executions that will happen within an hour, and therefore no login calls will be made.
- After the IF branch, perform the main call. We can reference the previously updated token.
<if expression="!expires || D.nowMillis()>expires.toLong()">
<comment>
<![CDATA[Authentication has to be performed due to expired token]]>
</comment>
<post url="${basePath}${loginPath}" params="[:]" var="loginPayload" mode="json">
<postParam name="username" value="test"/>
<postParam name="password" value="test"/>
</post>
<set var="token" value="${loginPayload.token}" lang="java"/>
<set var="expires" value="${D.plusHours(D.nowMillis(),1)}"/>
<update-input var="token"/>
<update-input var="expires"/>
</if>
More Notes
Updating input variables won’t work when launching a test from within the composer, so the login call will run every time when developing a test. Run the test from outside the composer or schedule the test to see it in action.
Language Appendix
Negation: the exclamation mark (!) prior to an expression is used as a negation and it means: when it’s false, when it’s empty, when it does not exist.
In our example: !expires means when expires is empty.
Logic Or: the classic double pipe sign ( || ). Rarely used in API Fortress except in IF conditions.
toLong(): converts a string to a long number.
D.<action>() an API Fortress language extension that provides date and time manipulation functionalities. Please refer to https://apifortress.com/doc/expression-language-extensions/ for further details.