Add API

Creating and Configuring API Test Steps in FinalRun

Think of a test that first gets a token or ID from an API, then uses that value in a mobile step—or a mobile step that grabs some data and sends it back to the server to check. FinalRun’s Add API step makes this easy: you call an endpoint, check the response, and save a value as a variable for your next mobile action. Or you can take data from your mobile test (like an order ID) and send it to an API to confirm it on the backend. This guide shows you exactly how to add and use the API step in FinalRun.

Overview and Prerequisites

Why Use API Steps?

  • Setup Test Data: Populate your application state before executing UI interactions.

  • Verify Backend Logic: Ensure endpoints return expected results before proceeding with front-end validation.

  • Fetch Dynamic Values: Extract tokens, IDs, or other data to drive subsequent test steps.

Prerequisites:

  1. FinalRun Account & Project: Ensure you have a project with at least one test case created.

  2. Endpoint Details: Know the API URL, supported HTTP methods, required headers, authentication scheme, and sample payloads.

  3. Network Access: Confirm that your machine can reach the target endpoint (e.g., no VPN or firewall blocking).

2. Adding an API Step

  1. Navigate to Test Steps:

    • Open your test case and scroll to the Test Steps section.

    • Click on the Select a step dropdown.

  2. Choose “Add API”:

    • From the list of available steps, select Add API.

    • The API request builder appears.

Tip: If you frequently add API steps, consider creating a reusable template with common headers (e.g., Authorization) in your settings.

3. Configuring Your API Request

3.1 Select HTTP Method

  • Available options: GET, POST, PUT, PATCH, DELETE.

  • Example: For a read-only fetch, choose GET.

3.2 Enter the Endpoint URL

  • In the URL field, paste or type the full endpoint (e.g., https://jsonplaceholder.typicode.com/todos/1).

3.3 Add Params, Headers, and Body (Optional)

  • Params Tab: Add query parameters as key–value pairs.

  • Authorization Tab: Select an auth type (e.g., Bearer Token, Basic Auth). Enter credentials or tokens.

  • Headers Tab: Define custom headers (e.g., Content-Type: application/json).

  • Body Tab (for POST/PUT/PATCH): Enter raw JSON, form-data, or other supported payload formats.

Example: To create a new TODO item:

{
  "userId": 1,
  "title": "Buy groceries",
  "completed": false
}

3.4 Sending the Request

  • Click the Send (or Hit API) button located at the bottom-right.

  • Wait for the response; the Response Data pane populates with status, headers, and body.

4. Validating the API Response (Assertions)

Use assertions to verify that the API behaves as expected.

4.1 Status Code Validation

  1. Switch to the Status Tab: Shows the HTTP status (e.g., 200 OK).

  2. Hover & Click “Validate”: A dialog opens pre-filled with the current status code.

  3. Adjust Comparison Logic (Optional): Change operators (e.g., ==, >=).

  4. Click Create: The assertion appears under the step summary (e.g., Status == 200).

Best Practice: Always assert that status codes are in the 2xx range for successful requests.

4.2 Header Validation

  1. Switch to the Headers Tab: Lists all response headers.

  2. Identify Target Header (e.g., x-ratelimit-limit):

  3. Hover & Click “Validate”: A dialog pre-fills the header and its value.

  4. Click Create: Assertion appears (e.g., x-ratelimit-limit >= 1000).

Note: Header names are case-insensitive. Use exact keys from the response.

4.3 Body Validation with AI JSONPath Helper

  1. Go to the Body Tab: Displays the raw JSON response.

  2. Click “Validate” Next to JSON View: Opens the validation dialog.

  3. Select “Use AI” Button: An input box appears.

  4. Type a Natural-Language Query (e.g., extract completed): AI generates a JSONPath expression (e.g., $.completed).

  5. Verify & Adjust “Expected Value” Field: AI populates this based on current response (e.g., false).

  6. Click Create: Assertion is saved under the step (e.g., $.completed == false).

Pro Tip: Use AI for complex nested fields (e.g., extract user’s company name) to avoid manual JSONPath errors.

5. Extracting Data into Variables

Saving parts of the response to variables makes your tests dynamic.

5.1 Extract Status Code

  1. Switch to the Status Tab:

  2. Hover & Click “Extract Value”: Opens extraction dialog.

  3. Name Your Variable (e.g., statusCode):

  4. Click Extract: The status code is stored in {{statusCode}} for later use.

Usage: In a subsequent HTTP request, you could reference {{statusCode}} to assert dependencies.

5.2 Extract from Body with AI

  1. Go to the Body Tab:

  2. Click “Extract Value” Next to JSON View: Opens extraction dialog.

  3. Click “Use AI”: Type a plain-English extraction request (e.g., extract title).

  4. AI Suggests JSONPath ($.title): Review and confirm the path.

  5. Enter Variable Name (e.g., todoTitle):

  6. Click Extract: Value from $.title is saved in {{todoTitle}}.

Example: If the response is:

{
  "userId": 1,
  "id": 1,
  "title": "Buy groceries",
  "completed": false
}

extracting title stores "Buy groceries" in {{todoTitle}}.

6. Example Walkthrough: Creating & Validating a TODO

  1. Add API Step → Select GET https://jsonplaceholder.typicode.com/todos/1.

  2. Send Request → Observe 200 OK, response body displays TODO fields.

  3. Validate Status → Assert Status == 200.

  4. Validate Body Field → Use AI helper: “extract completed” → Assert $.completed == false.

  5. Extract Values → Extract id into todoId, extract title into todoTitle.

  6. Save Step → Step summary shows two assertions (Status == 200, $.completed == false) and two extractions ({{todoId}}, {{todoTitle}}).

Screenshot Placeholder:

  1. API Request Builder showing URL, method.

  2. Response Pane with status, headers, body.

  3. Validations & Extractions UI highlighting AI JSONPath helper.

7. Best Practices & Troubleshooting

  • Consistent Variable Naming: Use descriptive, camelCase names (e.g., userId, authToken).

  • Chain API Steps Carefully: If one API depends on data from another, ensure extraction is done before referencing the variable.

  • Validate Critical Fields First: Always assert status code before deeper validations to catch errors early.

  • Use AI Helper Sparingly: For very simple fields, manual JSONPath ($.fieldName) may be faster.

  • Error Handling: If an API returns an unexpected schema, adjust your JSONPath or API configuration to match the actual response.

  • Timeouts & Retries: Configure request timeouts and retry logic in project settings if endpoints are unstable.

8. Finalizing and Saving Your Test Case

  1. Review All Assertions & Extractions: Scroll to the bottom of the API step builder; ensure every item is correct.

  2. Click Create: Adds the fully configured API step to your test case.

  3. Save Test Case: In the top-right, click Save Changes to persist your test.

  4. Run the Full Test Suite: Verify that API steps integrate seamlessly with UI steps.

9. Summary

This improved documentation offers a structured approach, practical tips, and clear examples for configuring API test steps in FinalRun. By following these guidelines, you can:

  • Rapidly add and configure API steps.

  • Assert response correctness with minimal effort.

  • Extract dynamic values for robust, data-driven testing.

Continue experimenting with different endpoints and complex scenarios to fully leverage FinalRun’s API testing capabilities.

For questions or feedback, reach out to the FinalRun support team or consult the official knowledge base.

PreviousAdd Variable AssertionNextAdvanced

Last updated