Skip to main content

Test Modes

Traces provides three testing modes for endpoints, each suited to different scenarios. Full Collection and Iterate modes use SSE streaming with real-time progress updates.

Overview​

ModeIconPurposeWhen to Use
Single TestPlayQuick single requestBasic testing, debugging
Full CollectionDatabaseCollect all pagesComplete data capture
Iterate TestRefreshRun for each source valueDependent endpoints

Single Test​

What It Does​

Runs the endpoint once with configured parameters:

  • Makes one HTTP request (or up to 3 pages if paginated)
  • Returns response for inspection
  • Saves sample to history

When to Use​

  • Initial endpoint testing
  • Verifying authentication works
  • Checking response structure
  • Quick debugging

How to Run​

  1. Select endpoint in tree
  2. Click Test button (play icon)
  3. View response in JSON viewer

Pagination Behavior​

For paginated endpoints:

  • Collects up to 3 pages
  • Stops early if pagination ends
  • Good for testing pagination config works

Full Collection​

What It Does​

Collects ALL available data by following pagination to completion:

  • Follows pagination until stop condition
  • Aggregates all pages into single response
  • No configured page limit (safety caps of 100 pages and 10,000 items per endpoint)
  • Uses SSE streaming for real-time progress

When to Use​

  • Capturing complete dataset
  • Testing stop conditions work correctly
  • Creating comprehensive sample for mapping
  • Validating pagination configuration

How to Run​

  1. Ensure pagination is configured
  2. Click Full Collection button (database icon)
  3. Progress modal shows real-time streaming updates
  4. View combined results when complete

Streaming Progress​

The progress modal shows real-time counters via SSE:

  • Pages collected: Current page number
  • Items collected: Running total of items
  • Elapsed time: Duration so far
  • Stop condition status: Which condition will terminate collection
  • Rate limit wait bar: Persistent bar showing delay between requests (when configured)

Stop Conditions​

Collection stops when:

  • Stop condition triggers (cursor empty, boolean flag, comparison)
  • A safety cap is reached (100 pages or 10,000 items)
  • Error occurs
  • You click Stop

Iterate Test​

What It Does​

Runs the endpoint multiple times, once for each value from a source variable or mapping:

  • Extracts values from dependency mapping or reusable variable
  • Substitutes each value into parameters
  • Collects all responses into array
  • Uses SSE streaming for real-time progress

When to Use​

  • Testing dependent endpoints
  • Processing each item from a parent list
  • Collecting detail records for each ID

How to Run​

  1. Configure a mapping with Iterate mode (or use a variable with iterate mode)
  2. Test the source endpoint first (need data to iterate)
  3. Click Iterate Test button (refresh icon)
  4. Progress modal shows streaming iteration progress

Example Flow​

Source: GET /channels returns [{ id: "C1" }, { id: "C2" }, { id: "C3" }]
Mapping: channels[*].id -> channelId (iterate mode)
Target: GET /channels/{channelId}/messages

Iterate Test runs:
  1. GET /channels/C1/messages
  2. GET /channels/C2/messages
  3. GET /channels/C3/messages

Result: Array of 3 message lists

Streaming Progress​

Shows during iteration:

  • Current iteration: e.g., "3 of 15"
  • Success/fail/skip counts: Color-coded counters
  • Rate limit wait bar: Shows delay between requests when rate limiting is configured
  • Current parameter value: The value being used for this iteration

Result Structure​

Iterate test returns an array of responses:

[
  { "messages": [...] },  // From C1
  { "messages": [...] },  // From C2
  { "messages": [...] }   // From C3
]

This combined array is saved as the test result, useful for:

  • Mapping to further downstream endpoints
  • Verifying data collection across all items

Stop and Preserve​

When you click Stop during a Full Collection or Iterate test:

  • The test stops after the current request completes
  • Already-received responses are preserved as a partial result
  • The result is viewable in the response panel
  • The sample is saved to history with success: false
  • Useful for inspecting partial data without waiting for the full run

Pause and Resume​

Streaming tests (Full Collection and Iterate) support pause/resume:

  • Click Pause to pause the live progress view
  • Incoming progress events are buffered client-side while paused
  • Click Resume to flush the buffered events and continue following the stream
  • Progress counters are preserved across pause/resume

Rate Limiting During Tests​

Configure per-test rate limiting to avoid hitting API rate limits:

  • Delay between requests (delayMs): Milliseconds to wait between each request
  • Respect Retry-After (respectRetryAfter): Automatically wait when receiving 429 responses

When rate limiting is active, a persistent rate limit wait bar appears in the progress modal showing the countdown between requests.

See Rate Limiting for configuration details.

Button Visibility​

Test Button (Play)​

Always visible when credentials are configured.

Full Collection Button (Database)​

Visible when:

  • Pagination is configured
  • Pagination is enabled

Iterate Button (Refresh)​

Visible when:

  • At least one mapping has "iterate" mode
  • Source endpoint has test data

Choosing the Right Mode​

Use Single Test When​

  • First testing an endpoint
  • Response structure is unknown
  • Debugging authentication issues
  • Quick verification needed
  • Endpoint has no pagination

Use Full Collection When​

  • Need complete dataset
  • Testing pagination thoroughly
  • Creating sample for complex mappings
  • Endpoint returns paginated lists

Use Iterate Test When​

  • Endpoint depends on array from another endpoint
  • Need to test N:1 relationships
  • Collecting details for each parent item
  • Iterate mode mapping is configured

Result Handling​

Sample History​

All test modes save to sample history:

  • Single: Saved as "Single" type
  • Full Collection: Saved as "Full" type
  • Iterate: Saved as "Full" type (array of responses)
  • Stopped tests: Saved with partial results (success: false)

Dependency Mapping​

Test results from any mode can be used for mapping:

  • Single: First-level extraction
  • Full: Aggregated array extraction
  • Iterate: Nested array of results

Error Handling​

If a test fails:

  • Error message displayed
  • Previous sample data preserved
  • Can retry or use cached data

Performance Considerations​

Single Test​

  • Fastest mode
  • Minimal API calls
  • Low rate limit impact

Full Collection​

  • Can be slow for large datasets
  • Many API calls
  • Configure rate limiting to avoid 429 errors

Iterate Test​

  • N API calls (one per value)
  • Can be very slow for large arrays
  • Use rate limiting and consider filtering source array

Best Practices​

Test Incrementally​

  1. Start with Single Test to verify basics
  2. Run Full Collection to test pagination
  3. Use Iterate Test for dependent endpoints

Configure Rate Limits​

Full Collection and Iterate modes make many requests:

  • Set appropriate delay between requests
  • Enable "Respect Retry-After" for 429 handling
  • See Rate Limiting for details

Review Results​

After any test:

  • Verify response structure
  • Check pagination stopped correctly
  • Confirm expected data present

Troubleshooting​

"Iterate button not visible"​

  1. Check mapping has "iterate" mode set
  2. Verify source endpoint has test data
  3. Confirm mapping is configured correctly

"Full collection never stops"​

  1. Review stop condition configuration
  2. Check hasMore/cursor paths are correct
  3. Verify API returns proper pagination signals

"Iterate test has many failures"​

  1. Some IDs may be invalid/deleted
  2. Rate limiting may cause timeouts — configure delay between requests
  3. Permissions may vary per item