Testing Connectors

Always test connectors before use in production collections.

Adding Test Credentials

Test credentials are managed as slots in the Test tab of the connector editor (or in Test & Configure for a draft). Each slot is one set of credentials; the active slot is the one used when you fire test requests.

1. Open the connector and go to the Test tab
2. Add a New credential slot
3. Fill in the form for your connector's auth type (see below)
4. Optionally mark the slot persistent to keep it beyond the default expiry
5. Save the slot, then make it the active slot

Credentials are encrypted and stored in Doppler. They are never exposed in the UI after saving.

warning

Non-persistent test credential slots expire (default ~24 hours). Persistent slots are kept until you delete them.

By Auth Type

Bearer / API Key / Basic Auth

Enter your token, API key, or username and password directly. The form matches the connector's configured auth type.

OAuth2

Enter the access token provided by the platform's OAuth flow.

Token Exchange

The token exchange form has two options:

Option 1 — Authorization Code Flow (shown when the connector has OAuth flow configured):

1. Click Authorize with [Platform] — a browser window opens to the platform's authorization URL
2. Log in and grant permissions
3. After redirect, an authorization code appears — paste it into the Authorization code field
4. Traces will exchange this code for an access token automatically when tests run

Option 2 — Direct token (shown as "I already have an access token"):

If you already have a valid access token (e.g. from a previous OAuth step or a long-lived token), paste it here. Traces will use it as-is, bypassing the token endpoint entirely. This is useful for initial testing before the full OAuth flow is configured.

When the connector has static body fields configured (e.g. client_id, client_secret), those are stored at the connector level and do not need to be entered per analyst.

Testing Individual Endpoints

Running a Test

1. Click Test on any endpoint
2. Review the request that will be sent:
   • URL with resolved parameters
   • Headers
   • Query parameters
3. Click Send Request
4. Examine the response:
   • Status code
   • Response headers
   • Response body (interactive JSON viewer)
   • Response time

Using the JSON Viewer

The interactive JSON viewer lets you:

• Expand/collapse nested objects
• Click paths to select for dependencies
• Copy values
• Search within response
• Save selections as variables directly from the viewer (click a value, then "Save as Variable")

Interpreting Results

Status	Meaning	Action
200	Success	Verify data is correct
401	Unauthorized	Check credentials
403	Forbidden	Check permissions/scopes
404	Not Found	Verify endpoint path
429	Rate Limited	Reduce request rate or configure rate limiting
500+	Server Error	Platform issue, retry later

Pasting Sample Responses

If you can't make live requests:

1. Click Paste Sample Response
2. Paste JSON from the API documentation
3. Use for:
   • Configuring pagination paths
   • Setting up dependencies
   • Verifying data extraction

note

Sample data helps configure but doesn't validate the connector works with real API.

Sample History

Test responses are automatically saved for later use:

• Auto-save: Successful (2xx) tests save automatically
• Limit: Up to 10 samples per endpoint
• Persistence: Samples survive browser refresh and sessions

Using Sample History

1. Click the History button (clock icon) in the response toolbar to open the history popout
2. See the list of saved samples with timestamps
3. Click any sample to view/activate it
4. Active sample data is used for dependency mapping

Sample history lets you:

• Work offline with cached responses
• Compare responses over time
• Restore good test data if new tests fail

See Sample History for the full guide.

Query Parameters

Add query parameters for testing in the parameters panel below the URL bar:

1. Expand the Query Parameters section under the URL bar
2. Click + to add a new parameter
3. Enter the parameter name and value

Parameter Sources

Query parameters can come from:

• Manual entry: Type values directly
• Dependency mappings: Link to other endpoint responses
• Variables: Apply saved variable extractions

See Query Parameters for details.

Test Modes

Testing is driven from the toolbar at the top of the endpoint editor:

Control	Appears	Purpose
Test button (Play icon)	Always	Runs the endpoint once
Full collection toggle	When pagination or recursion is enabled	When on, the Test button follows all pages/recursion; when off, it fetches a single page (max 3 pages)
Iterate button	When the endpoint has an iterate-mode dependency mapping	Runs the endpoint once per source value

Full-collection and Iterate runs use SSE streaming with real-time progress counters, pause/resume, and stop-and-preserve behavior.

When to Use Each

• Test (single): Initial testing, debugging, quick checks
• Test with Full collection on: Complete pagination test, comprehensive samples
• Iterate: Test dependent endpoints with multiple source values

See Test Modes for the full guide.

Testing Pagination

1. Configure pagination settings
2. Test the endpoint
3. Verify response includes:
   • Cursor/next token
   • Has_more flag (if applicable)
   • Data array at expected path
4. Check that second request would be made
5. Monitor for correct stop condition

Verifying Complete Pagination

For thorough testing:

1. Run multiple test requests
2. Follow cursor manually
3. Verify you can reach last page
4. Confirm stop condition triggers

Running Test Collections

For comprehensive testing after finalizing:

1. Finalize the connector
2. Create a test collection
3. Configure minimal scope:
   • Recent date range (last 7 days)
   • Limited filters if available
4. Run and monitor in real-time
5. Review collected files and logs
6. Check for:
   • Complete pagination
   • All dependencies resolved
   • No unexpected errors

Testing Checklist

Before publishing a connector:

• Authentication works correctly
• All enabled endpoints return data
• Pagination retrieves multiple pages
• Pagination stops correctly (not infinite)
• Dependencies resolve to correct values
• Rate limits are respected
• Error handling works as expected
• Data extraction paths are correct
• Conditional execution conditions evaluate correctly
• Response transformations produce expected output
• Recursive endpoints traverse to expected depth

Common Testing Issues

"Test succeeds but collection fails"

Causes:

• Different credential scopes in production
• Test used sample data not real API
• Rate limits hit during full collection

Solutions:

1. Use same credentials for test and collection
2. Always test with live API calls
3. Configure appropriate rate limits

"Pagination stops early"

Causes:

• Wrong cursor path
• Stop condition triggered incorrectly
• Cursor not updating

Solutions:

1. Verify cursor path matches response
2. Check stop condition logic
3. Test multiple pages manually

"Dependencies work in test, fail in collection"

Causes:

• Test used limited data
• Full collection has edge cases
• Order issues in parallel execution

Solutions:

1. Test with larger data sets
2. Handle empty results
3. Verify dependency order is correct

Best Practices

1. Always test with real credentials - Don't rely on sample data
2. Test edge cases - Empty results, single items, large volumes
3. Verify pagination completely - Don't just test first page
4. Document test results - Note any quirks discovered
5. Re-test after changes - Any config change needs re-testing

Next Steps

• Versioning
• Troubleshooting