read-file (on-premises only)

In an on-premises deployment, the read-file command allows you to read a text file from the server local storage, in the /data directory.

Parameters:

Name Type/Value Required
path String Yes
var String Yes
mode “json”,”xml2″,”text”,”csv” Yes

path: the path of the file, relative to the /data/ directory

var: the name of the variable that will carry the read values

mode: how the file has to be parsed

If the file is successfully read, the variable declared in the “var” attribute will contain the structured (in case of json, xml2, csv) or unstructured (in case of text) information you can use as any other piece of data.

Composer Snippets

A snippet is a fragment of test, stored in the Vault, that can be reused in multiple tests.

To create a snippet, click on the first component you want to include in the fragment. Then, hold down the [SHIFT] key and click on the last component you want to include. The selection will be highlighted.

Click the + button in the snippets section of the Vault panel, and fill the Name and Description fields. That is it! The fragment of the code is created and ready to be use in every test of the project.

For each snippet, two actions are available:
1) Paste Snippet: Allows you to paste the entire component inside the test, allowing you to edit as needed. The pasted components will lose any reference to the original snippet.
2) Invoke Snippet: This creates a Call component that will invoke the snippet. If the snippet changes, all the tests containing the Call component to that snippet will inherit the changes.

Tag

This component is used to dynamically tag the resulting document of a test execution. You can easily find a document by searching for the specific tag, in the same way you can find a test by searching for the tag you assigned to it.

In the composer you will have the ‘tag’ component as option to be added. In this way, you can add different tags based on dynamic events happening during the test execution, such as a certain value retrieved in the payload. You can assign multiple tags to each test by adding more ‘tag’ components to it.

Parameters:

Name

Type/Value

Required

Value String

Yes

Another way to add a tag to your test is in the test details screen during test definition or edit.

Static tags will be displayed in the tests list.

All tags, dynamic and static will mark the test execution documents. In the project dashboard, you have the ability to filter events by tags.

There is also a dedicated API that does the same. For more info please see the documentation here

Company settings

The Company settings page allows the manager(s) of a company to alter global settings such as  the users that can access the company, who will receive the notifications etc.

The page can be reached by clicking on the top right icon (gear).

The page is composed by different sections: Company, Account, Plans and Payment, Users, Notifications, Alerts Group, API Keys, API Hooks. In the Company page, you can set the Company Name, the Description and the Time Zone.

The Time Zone is important because it will be used when you schedule a test: if you schedule a test at 9am and Time Zone is ‘America/New York’, test will run at 9am New York time, that is different from 9am ‘Europe/London’.

At the top of the page, the ‘Save changes‘ button will make your changes effective.

In the Account page, you can see information about the company:

Contract: the contract type of your account.
Monthly Hits: the number of executions so far for the current month.
Monthly origin downloads: how many times tests downloaded a web service
Overall documents: the number of documents generated and still available for consultation
Monthly SMSs sent: the number of SMSes sent as failure alert

Plans and Payment page allows you to upgrade your account.

The Users page allows you to add and remove users to the company account.

By clicking ‘+ User‘ you will be presented a popup:

e-mail: the email address of the user you want to add.
Full Name: the name of the user
Time Zone: the Time Zone of the user
Level: the permission level of the user: as ‘Manager’ the user will have access to company settings, tests and analytics. As ‘Developer’ the user will have access to tests and analytics. As ‘analyst’ only analytics will be made available.

In the Notification page, you can add and administer who receives alerts and reports. You can add either an user that has access to the company or an user that does not have access to the company.

The Alerts Groups section is the higher granularity notification system that includes integration with other software and platforms

The API Keys page is useful if you want to use the API. You just need to click the + API Key button to generate a key/secret pair.

At the bottom of the page, the API Hooks section.
In this section you can create the project hook for the v3 API. To get started, you will first need to create a hook for the project you want to interact with by clicking + API Hook button, choose the project the hook will refer to, choose a privileged user for this hook and copy the hook in your clipboard. The generated URL will give you the ability to query some resources of the connected project without needing any further authentication, so mind who you will share it with. If you feel the url has been improperly shared, you can revoke it from the page you used to create it.

For all the update endpoints, a JWT token is required as part of the authorization process and the authenticating user has to match the user selected while creating the hook.

For details about all the endpoints, please see the documentation here:

http://docs.apifortressv3.apiary.io/

 

 

Main dashboard

The main dashboard presents the list of your projects and an overview of their statuses.

At the top of the page there is a chart showing the whole company status, it sums up the failures and successes of all the projects in your company for the last 24h. (More details about the failures and successes are available in the project dashboard).

For every project you can see the number of tests, the number of the events happened in the last 2 days and the total failures (in the last 2 days). You can reach the dashboard, the tests list and the incident page with the dedicated buttons.

On the right side of the screen, you can find the platform logs: choose to see only the relevant events (default) or all the events. Test failures and administrative operations are reported here.

Project dashboard

The Project Dashboard is the section of API Fortress where the project status and history are displayed.

There are three main sections: Logs, Metrics and Availability. The data is collected from the scheduled runs and from the manual execution of a test outside the composer.
The three sections have the same structure but with different content. Every section has a graph to show you the trend of the project of the last two days but you can see any day by selecting the specific date using the calendar feature. If you need to zoom into a particular time frame you can do it by selecting an area directly on the graph. You can filter results also by test name, by failures and by location.  On the top left part of the screen you can see some details about the tests: how many events have been created,  how many failures and successes, how many scheduled runs have been configured.

The Logs section shows, as default view, the events in the last two days.
Every event is listed in a table with test name, the date and time of the event, the location where the event happened, the status. You can limit the number of events displayed in the table by filtering the results by test name, by failures or by location. For every event, you can see the related report by double clicking on a row or download it as a PDF. The reports are visible only to the registered users but you can generate a publicly sharable URL.

The Metrics section shows you the performance of your endpoints. The default view displays the last two days. As in the Logs section, every event is listed in a table with a footprint, date and time when it happened, the latency and fetch, the location and status. The results can be filtered by footprint, location and failures. By clicking on any row you can see the details of the event or create an alert related to it. An alert allows you to be notified when fetch or latency of a specific footprint is greater than a value you set up.  Once set up, you can find it by clicking Monitors in the left panel; at any time you can edit or delete it.

Lastly, the Availability section shows you the availability of your endpoints. The default view shows the last two days. The data is listed in a table that shows the endpoint, the date and time, the location and the status of any result. The results can be filtered by footprint, location and failures.

If you need to view a specific log, metric or availability in a specific time range you can create your own query using the drop downs at the top of the page. The query allows you to filter by logs, by metrics or by availability by selecting the specific test name or the endpoint; choose a start and end  date for extending the time range (max 10 days allowed) and view only the failures. Every query performed is listed on the bottom of the left panel so you can easily retrieve it. If you want to keep it for later uses, you can save it by clicking on the heart icon. If the query makes sense also for other projects, it will be preserved and listed when you switch from one dashboard to another via the dedicated drop-down menu at the top of the left panel.

 

 

 

Assert Compares

Allows you to compare two payloads in terms of text, structure or values.

Parameters:

Name Type/Value Required
Expression 1 Expression Yes
Expression 2 Expression Yes
Mode Text, values, structure Yes
Level error, warning No
Stop test if fails True, false No

Expression 1: the first payload you want to compare.
Expression 2: the second payload you want to compare.
Mode: the comparator you wish to use. Text compares the text of the two payloads as plain text, values compares the two payloads regardless the text layout, structure compares only the structure of the two payloads.
Level: Specifies, when the assertion fails, whether it should be considered an ‘error’ or just a ‘warning.’ A warning will not trigger alerts (such as email or text messages).
Stop test if fails: The test will be immediately stopped if the assertion fails.

 

While

Allows you to run a block of assertions as long as a condition is valid.

Parameters:

Name Type/Value Required
Expression Expression Yes

Expression: The condition that has to be met for the assertions block to be executed

 

Composer

The composer is the cornerstone of API Fortress.

With the composer you can make calls and add assertions for testing your APIs.

There are two versions of the composer: the visual composer and the code view. Visual composer does not need any code knowledge and provides real time suggestions to help you while writing the test. The code view is intended (only for paid accounts) for those that are comfortable with coding and want to add scripting functionalities to their tests.

 

All the available components can be seen by clicking on Add component.

The panel shows you all the available components grouped by category.

If a component is not valid for the operation you are doing, it is disabled (i.e. if you didn’t add a POST first, you cannot add a POST Body or POST Param), so some mistakes can be avoided. Please consider Free accounts do not provide all the available components.

See the other pages in the Reference for the explanation about each component.

In the header:

Console opens up our console to allow you to make calls and see the responses.

Gadgets allows you to generate signatures, base-64 encode/decode features, or use crypto features.

In the top left of the page, there are tools for helping you to create the test:

 

From left to right:

+:  has the same functionality of the Add component in the composer.
pencil: edit the selected component.
arrows: transforms a component into another.
check: checks whether an assertion is valid against the payload downloaded making a call using the console.
save: saves the current working copy. Saving the test won’t affect the scheduled version (if any); any change you made will be in your working copy. You will need to publish the working copy to make it effective.
trash: deletes a component.
exit: exits the composer with or without saving the changes you made.
play: runs the test, in order to check if all works fine. You can choose the data center you want to run it on. Running a test inside the composer won’t create logs and reports as well as won’t affect the version that is already scheduled.
help: the help tool allows you to see the reference related to the specific component directly inside the composer, without needing to keep the reference opened in a different tab.

Every component can be dragged and dropped to easily rearrange your test.

At the left of the screen there are two buttons:

the first one (top) opens the Global variables / input sets panel, the second one (bottom) opens the Console.

Global variables / input set panel:

  • the Global variables don’t change during the test execution like domain, path, api key.
  • Input sets: are groups of variables to run the test against such as IDs, search terms…

Console: our console allows you to make calls and see the responses.

On the top left of the console there are the buttons to perform the following actions:

folder: open/close the request panel (the one where you can see the saved requests/payloads).
save: save the request you made in the console in order to retrieve it in the future. Once saved, the request and payload will be available to you anytime, just click on the name and it will appear in the console. In this way, you can see it later if you didn’t complete the test or you can compare the current response with the old one in order to check any change made in between.
arrows: expand/reduce the console in the window.

At the center right of the screen there is the Request/Response link, where you can see the request and response of the call that you have made.

At the top right of the screen there are the following buttons:
import: import a call made on console into the composer, so you don’t have to write it again into your test.
export: export the selected call in the composer into the console, so it will be easy to see the response without needing to write it
magic: this button allows you to create a test using the ‘magic tool’ without needing to write anything. In order to use it, first you have to write a call in the console and send it, once the response showed up, you can tap on the magic icon that will auto-magically create the test. If you want to have a better idea on how it works, please check out the tour that is available tapping on ? icon in the header of the composer.
send: send the request written in the console and allows you to see the response.

At the bottom there is the console where you can make the call. Once you made a call in the console, you can see the response but the most important thing is that in this way, you will get real time assistance while writing your test: this means that every field in the response will present a suggestion on the data structure.

 

Configs

The ‘configs’ section is used to configure the internal behavior of the testing engine. Currently, there is nothing adjustable to the end user. you can ignore this for now.