Flurry Documentation
Quick Navigation
Core Concepts
Introduction
Getting started with Flurry begins with creating or joining an organisation. Organisations are collaborative spaces where users can work together on projects. Admins can invite new members and manage roles. Within each organisation, projects are created to group related work. Each project can contain multiple collections, which serve as containers for your testing logic and scenarios.
Collections
Collections are at the core of Flurry. When using the CLI, you initiate a collection run. This collection contains your testing building blocks: tasks. Tasks are units of action, such as making an API call or listening for a callback. They come in two flavors: dispatchers, which handle outgoing actions like sending requests, and listeners, which handle incoming data such as webhooks or event stream messages.
Flows
Tasks are combined into flows. Flows represent different testing scenarios. Only flows that are toggled to be active are executed when you run a collection, which means you can work on a flow and only enable it when it is ready. Tasks can be run in groups or individually. Grouped tasks are executed in two concurrent phases. All dispatchers are executed first (in parallel), while listeners are executed after all dispatchers have completed (also in parallel).
Environments
Environments allow you to configure different testing contexts. Each environment contains variables that can be referenced in your tasks using the {{variableName}} syntax. This enables you to test the same collection against different API endpoints, authentication credentials, or configurations without duplicating your test logic. A Local environment is available in the UI, but is not available in the CLI. The values in the Local environment are only stored in the browser.
Assertions
Relevant task types can have assertions that validate the data it produces. Simple checks can be quickly configured in the UI. Define the path, assertion type, data type and expected value. You can create these simple comparisons or complex custom JavaScript validation scripts.
Task Types
Dispatchers
Dispatchers are tasks that initiate outgoing actions, such as making HTTP requests or publishing messages to queues.
HTTP Requests
Make API calls to your endpoints.
Configuration:
Set HTTP method, request URL, headers, body content, and query parameters. Define optional timeout and request delay.Polling:
Retry requests with configurable intervals and stop conditions.Assertions:
Validate response status, headers, and body content.Post-request utilities:
Extract values from the response to use in subsequent tasks.
Listeners
Listeners are tasks that handle async incoming data from external sources like webhooks and event streams.
Callbacks (Webhooks)
Listen for HTTP callbacks or webhooks sent from your application.
Matching Rules:
Define rules to match against incoming data. These are configured using the familiar structure of assertions.Assertions:
Validate payload structure and content.Timeouts:
Configure how long to wait for expected webhooks.Post-request utilities:
Extract values from the payload to use in subsequent tasks.
Kinesis Events
Connect to a Kinesis event stream.
Stream Configuration:
Define the stream name and region.Body Format & Encoding:
Configure the expected format and encoding for event data.Matching:
Set rules to match incoming event data. This uses the same structure as assertions.Assertions:
Validate the content of incoming events.Post-event Utilities:
Set payload values as variables that can be used in follow up tasks.
Assertions
Overview
Assertions are validation rules that test whether your API responses, webhook payloads, or event data meet your expectations. They allow you to verify data values, check response structure, validate business logic, and ensure your integrations work correctly. Tasks can have multiple assertions to validate different aspects of the received data.
Data Sources
Body
The response body or payload data. Most commonly used for validating API response content. Default source for events from event streams.
{"userId": 123, "name": "John", "orders": [...]}Headers
HTTP headers or event metadata. Useful for validating content types, authentication headers, or custom metadata.
content-type: application/json x-api-version: v2
Response
HTTP response metadata like status codes. Only available for HTTP request tasks.
status: 200 ok: true statusText: "OK"
Path Navigation
Dot notation
Navigate nested objects using dot notation:
user.profile.emailAccesses: {"user": {"profile": {"email": "..."}}}}
Array access
Access array elements with bracket notation:
users[0].name orders[1].total
Gets the first user's name or second order's total
Root-level arrays
For responses that are arrays at the root:
[0].userId [2].status
Access items directly from root array: [{"userId": 1}, ...]
Empty path
Leave path empty to work with the entire response:
Path: (empty) Type: length
Validates the length of the entire response array
Assertion Types
Comparison Operators
Special Types
Custom Script Assertions
Script assertions allow you to write custom JavaScript logic for complex validation scenarios. They provide access to the extracted data and variables.
Function Structure
function(context) {
const data = context.data; // Extracted value
const variables = context.variables; // Environment vars
// Your validation logic here
// Return boolean for simple pass/fail
return true; // or false
// Or return object for advanced control
return {
passed: true,
errorMessage: "Optional custom error message",
setVariables: { "key": "value" }
};
}Accessing Variables
Variables are available as a plain JavaScript object:
// Access with bracket notation const apiKey = variables["API_KEY"]; const userId = variables["currentUserId"]; // Access with dot notation const apiKey = variables.API_KEY; const userId = variables.currentUserId;
Setting Variables
Scripts can return a boolean or an object with additional options:
// Simple boolean return
return data.userId === 1;
// Object return with advanced features
return {
passed: data.userId === 1,
setVariables: {
"currentUserId": data.userId,
"timestamp": Date.now(),
"isValidUser": data.status === "active"
},
errorMessage: "Custom error message when failed"
};passed: boolean - Whether the assertion should pass
setVariables: object - Variables to set for use in later tasks and assertions.
errorMessage: string - Custom error message shown when assertion fails
Flows
Flow Orchestration
Flows organize your tasks into coherent testing scenarios.
Execution Modes
Sequential Mode
Tasks run one after another in order. Each task waits for the previous one to complete before starting.
Grouped Mode
Tasks are executed in two phases: all dispatchers run in parallel first, then all listeners run in parallel.
Flow Controls
- Active/Inactive: Toggle flows on or off to control which scenarios are executed during a collection run.
Running a Collection
CLI Usage
Basic Command
npx flurry-test --collection-id=YOUR_COLLECTION_ID --api-key=YOUR_API_KEY --environment=production
Command Line Options
--collection-id- The collection ID to run (required). Find this in your collection's settings.--api-key- Your API key for authentication (required). You can generate a new key in the API keys section of the collections page.--environment- The environment to use (required)--run-flow-id- Run a single flow by ID (optional)--verbose- Set totruefor detailed output (optional)--fail-fast- Set totrueto exit the test run as soon as an assertion fails (optional)