An API App is an App of type API: a REST, GraphQL or other HTTP service that your Test Cases call with API Call steps. You give each Environment the Base URL of the API and its authentication, and you can add an OpenAPI or Swagger spec. With the spec, Thunders AI writes API tests from a short description, and it can call your API once to check the real values.
This article covers what is specific to an API App. For what an App is and how Apps share a Test Project, see Apps: Test Multiple Applications in One Test Project. For the fields of an API Call step, see How to add an API Call step?
Before you start
You need the Admin role to add or edit an App.
Have the Base URL of the API for each Environment.
If the API needs authentication, have the username and password (Basic Auth) or the token (Bearer Token) for each Environment.
Where you set up an API App
When you create a Test Project. In the Configure your first app step of the onboarding wizard, select API. The Set up environment step then asks for the API setup, and Review and Create sums it up.
When you add an App. Open Configure > Apps, select the New app card, and select API in App settings. Fill in the Environments step, then select Create App.
When you edit an App. Open Configure > Apps and select the card of the API App. Change the fields, then select Save changes.
An API App shows each Environment in its own card. The API spec (optional) field sits above the cards, because one spec serves every Environment of the App.
Enter the Base URL of each Environment
In each Environment card, enter the Base URL of the API, for example https://api.example.com. Enter the root address of the API, not the address of a web page or of a spec file. In the onboarding wizard, the Base URL is required.
Read the Base URL check
Under each Base URL, Thunders sends one request to the address with the authentication of that Environment, and shows the result:
Result | What it means |
Reachable | The API answered. |
Authentication required | The API asks for credentials. Choose its authentication below the Base URL. |
Credentials refused | The API refused the username and password, or the token, that you entered. |
Looks like a website | The address returns a web page. Enter the Base URL of the API instead. |
Looks like a spec file | The address returns an API spec. Enter the Base URL of the API, and add the spec in the API spec (optional) field. |
Server error | The API answered with a server error. Check that it is up. |
Not reachable | Thunders could not connect, for example because the hostname does not resolve or the API does not answer within 5 seconds. |
Not checked | Thunders checks https URLs only. |
When you choose Basic Auth or Bearer Token, the check waits for the credentials and shows "Fill in the authentication to check this URL." The check is information only. It never blocks Continue, Create App or Save changes.
Choose the authentication of each Environment
Each Environment has its own Authentication select, under its Base URL. The API Call step editor offers the same three types:
No Auth: Thunders sends no credentials.
Basic Auth: enter a Username and a Password.
Bearer Token: enter a Token.
Thunders saves the values as variables of that Environment, named from the App name. For an App named Billing API, the token goes into the secret variable BILLING_API_TOKEN, the password into the secret variable BILLING_API_PASSWORD, and the username into the variable BILLING_API_USERNAME.
When you edit an API App later, the password and the token show as dots, and the field names the variable that holds the value, for example "Stored in [BILLING_API_TOKEN]. Leave empty to keep the current value."
For how to manage these values after the setup, see Add / Edit / Delete / Use Secrets and Variables.
Add an API spec (optional)
Add a spec so that Thunders AI knows the endpoints of your API (see the next section). The API spec (optional) field takes an OpenAPI or Swagger spec. Thunders supports Swagger 2.0 and OpenAPI 3.
Upload: drop your spec files, or select the area to browse. You can add 5 files at most, 10 MB each, in
.json,.yamlor.yml.From URL: enter the Spec URL, then select Parse spec. The link must be a public https link to the spec file itself, not to a documentation page.
A status line sums up the result, for example "Parsed · 19 endpoints detected." A file that Thunders cannot read shows the reason, and Thunders does not save it. When the first Environment has no Base URL yet, Thunders fills it with the first server of the spec.
When a spec references a file that you did not upload, a Missing file line names it. A spec that you add From URL is read as one document, so upload a spec that is split across several files.
Generate API tests with Thunders AI
Open Thunders AI, select the API App in the Apps list and an Environment in the Environment list, then describe the test in your own words. For example: "Create a test that places a new order in the store. Call the API once to see the real response, then check the exact status code and fields that it returns."
Thunders AI reads the spec. A card titled API spec lists what it read, for example Read the API spec with the number of matching operations.
When the spec does not give a value, Thunders AI calls your API once to see the real response. A call that only reads data, such as a GET, runs at once. A call that changes data (POST, PUT, PATCH or DELETE) waits for your answer: Thunders AI shows the method, the path, the body, the App and the Environment, and states "This request changes data." Select Run probe once to send the call one time, or Use spec default to keep the values of the spec.
The card, now titled API spec and live calls, then shows the Live call with its status code and the fields of the response. When the call fails or you choose the spec, the line reads Unverified, and the test uses the value of the spec.
Thunders AI creates a Draft Test Case with the API Call steps and the checks on their response, and opens it. It then asks "Execute the test now?".
You can also ask Thunders AI to change the Test Case that is open, for example: "Set the assertions to the exact values that the API returns." Thunders AI saves the result as a new version of the Test Case.
A few more points apply to Thunders AI with an API App:
For an API App, Thunders AI works only with the API. It writes API steps and does not open a browser.
When your request contains a password or a token in clear, Thunders AI removes it from the steps and asks you to store it as a secret variable.
When a similar Test Case already exists, Thunders AI may ask whether to create a separate Test Case or to change a copy of the existing one.
Thunders AI does not write GraphQL tests yet.
Use your API App in a Test Case
New API Call steps start from the App. A new API Call step starts with the URL variable of the App, for example
[APP_BILLING_API_URL], and with the authentication of the selected Environment.Steps hold variables, not secrets. For an API App, the password or the token of an API Call step must be a variable. When you type a raw value, the step editor refuses it: "Use a variable, for example [ORDERS_TOKEN]. Secrets are never stored in a step."
Frequently asked questions
How do I use a different token for each Environment?
Set the authentication in the card of each Environment. Each Environment keeps its own authentication type and its own variables. At run time, the step uses the values of the Environment that the run targets.
How do I replace or remove the API spec?
Open Configure > Apps and select the card of the API App. To replace the spec, add the new files or the new link. To remove a spec that you uploaded, select Clear all. To remove a spec that you added From URL, empty the Spec URL field. Then select Save changes. When you change an API App to a Web App, Thunders also removes its spec.