Custom Assertion Functions

ReAPI enables you to extend the no-code editor by registering Custom Assertion Functions, which appear as options in the assertion builder. These functions empower QA teams to perform advanced validations effortlessly without writing code.

Why Custom Assertions Matter

Custom assertions provide a structured approach to handling complex validation scenarios beyond standard checks. They allow QA teams to implement domain-specific logic effortlessly and ensure consistency across tests.

Comparison: Without vs. With Custom Assertions

Challenges Without Custom Assertions

Without custom assertions, test cases may fail to ensure data integrity and quality. Built-in assertions like isString or isNumber provide basic checks but do not capture domain-specific requirements, potentially leading to undetected issues.

Example:

Consider an API that returns geolocation data:

{
  "location": { "lat": "40.7128", "lng": "-74.0060" }
}

Using only built-in assertions:

assert.isNumber(response.location.lat);
assert.isNumber(response.location.lng);

This approach does not check if latitude and longitude values fall within valid ranges (-90 to 90 for latitude, -180 to 180 for longitude). Without a custom assertion, invalid data might pass unnoticed.

By implementing a custom assertion like isGeoLocation, you can ensure:

• The correct data structure (object or array).
• Values within the proper geographic bounds.
• Improved test accuracy and confidence.

Rules for Custom Assertion Functions

1. Single Function Requirement: Each custom assertion must be a standalone function created within the ReAPI web editor. This ensures maintainability and clear function boundaries.
2. Parameter Limitations: Functions can accept 1-2 parameters:
   • Single parameter for simple validations, such as isGeoLocation(value).
   • Two parameters for comparisons, like isEqual(actual, expected).

⚠️ Coming Soon: A third parameter for additional options will be supported in future updates.

3. Asynchronous Support: Async functions are supported. Always use await with async calls to prevent unexpected behavior and ensure smooth execution.
4. Critical Requirement: The assertion result must be added using the $addAssertionResult callback. This function integrates your validation results into the ReAPI platform, ensuring they appear in test reports and workflows.

Example:

$addAssertionResult({ passed: true, leftValue: value });

Example: Validating GeoLocation Format

This example demonstrates how to create and register a geolocation validation logic using a custom assertion function.

Creating a Custom Assertion Function

Define the assertion function named isGeoLocation in the UI and implement logic to validate geolocation data.

• Name: isGeoLocation
• Description: “Validates if a value is a valid geolocation.”

/**
 * Validates if the provided value is a valid geolocation.
 * Accepts both object format { lat, lng } and array format [lat, lng].
 *
 * @param {Object|Array} value - The geolocation data to validate.
 * @returns {void} - The result is added to ReAPI using $addAssertionResult.
 */
async function isGeoLocation(value) {
  const isValid = (v) => typeof v === 'number' && v >= -180 && v <= 180;
  let lat, lng;
  if (Array.isArray(value) && value.length === 2) {
    [lat, lng] = value;
  } else if (value && typeof value === 'object' && 'lat' in value && 'lng' in value) {
    ({ lat, lng } = value);
  }
  if (isValid(lat) && isValid(lng)) {
    $addAssertionResult({ passed: true, leftValue: value });
  } else {
    $addAssertionResult({
      passed: false,
      leftValue: value,
      message: `${JSON.stringify(value)} is not a valid geolocation`,
    });
  }
}

Testing the Custom Assertion Function

Always test the custom assertion function using the test code editor on the web UI.

// Success cases
isGeoLocation({ lat: 40.7128, lng: -74.0060 });
isGeoLocation([40.7128, -74.0060]);
 
// Failure cases
isGeoLocation({ lat: 200, lng: -74.0060 });
isGeoLocation("not a location");

The test code above will add assertion results to the test result.

Using in the No-Code Editor

Once the function passes testing, enable it in the no-code editor. The isGeoLocation operator will then appear in the Assertion Operators list alongside built-in operators. QA teams can select it to validate geolocation fields without writing additional code.

Script Development Options

You can write custom assertion functions directly within the ReAPI web editor for quick access and ease of use. However, if you prefer using your own development environment, you can create assertion functions in an external library and register them with ReAPI.

• Web Editor: Ideal for quick, straightforward assertions without dependencies.
• External Library: Provides full flexibility to use your preferred IDE, version control, AI assistance, and local testing tools.

For more details, refer to the External Library Guide.

Next Steps

By following these best practices and leveraging async support, your validation logic becomes modular, flexible, and scalable. Start building reusable, efficient logic for your API tests today!