majiayu000 Nango Dry Run Testing
Overview
Test Nango sync jobs locally using the nango dryrun command to verify sync logic, data mapping, and API integration without persisting data to the database.
When to Use
- Testing sync changes before deployment
- Debugging data mapping issues
- Verifying API integration works correctly
- Checking manager resolution or relationship logic
- Validating incremental sync behavior
Quick Reference
| Task | Command |
|---|---|
| Run sync locally | npx nango dryrun <sync-name> <connection-id> --integration-id <provider> -e <env> |
| Test employees sync | npx nango dryrun employees <connection-id> --integration-id <provider> -e prod |
| Short-circuit for faster testing | Add if (page > 2) break; in sync loop |
Command Structure
cd nango-integrations
npx nango dryrun <sync-name> <connection-id> --integration-id <provider> -e <environment>
Parameters:
<sync-name>: Name of sync endpoint (e.g.,employees,locations,departments)<connection-id>: UUID of the Nango connection to test with--integration-id: Provider identifier (e.g.,workday,adp,gusto)-e <environment>: Environment (e.g.,prod,dev,staging)
Example:
npx nango dryrun employees <connection-id> \
--integration-id workday -e prod
Faster Testing with Short-Circuit
For large datasets, add temporary short-circuit to test faster:
// ✅ GOOD - In sync loop before processing
do {
await nango.log(`Fetching page ${page}`);
// SHORT-CIRCUIT FOR TESTING - Remove before committing
if (page > 2) {
await nango.log(`Short-circuit: stopping after page ${page}`);
break;
}
// ... rest of sync logic
hasMoreData = res.Response_Results.Page < res.Response_Results.Total_Pages;
page++;
} while (hasMoreData);
Remember: Remove short-circuit before committing!
Common Patterns
Testing Manager Resolution
// Add detailed logging to verify manager data
await nango.log(`Manager resolution: ${managersResolved} resolved, ${managersNotFound} not found`);
// Log sample manager data
if (allMappedEmployees.length > 0) {
const empWithManager = allMappedEmployees.find(e => e.manager);
if (empWithManager) {
await nango.log(`Sample manager: ${JSON.stringify(empWithManager.manager)}`);
}
}
Testing Data Mapping
// Log first mapped employee to verify structure
if (mappedEmployees.length > 0) {
await nango.log(`Sample employee: ${JSON.stringify(mappedEmployees[0], null, 2)}`);
}
Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
| "Connection not found" | Invalid connection ID | Verify connection exists in environment |
| "Sync not found" | Wrong sync name | Check sync export name in sync file |
| Timeout | Large dataset | Add short-circuit to limit pages |
| Missing data | Wrong Response_Group | Check API request includes needed data groups |
| Authentication error | Invalid credentials | Verify connection credentials in Nango dashboard |
Workflow
- Make changes to sync or mapper files
- Add short-circuit if testing large dataset
- Run dry run command
- Check logs for errors or missing data
- Verify mapped data structure is correct
- Remove short-circuit before committing
- Run full dry run to verify complete sync
Best Practices
- Always test in the target environment (prod credentials may differ from dev)
- Use short-circuit for initial testing, then test full sync
- Add comprehensive logging for debugging
- Verify manager/relationship data populates correctly
- Check edge cases (missing fields, null values, empty arrays)
- Remove all debugging code before committing
Example Output
Fetching page 1
Fetched batch of 100 workers. Total fetched: 100
Processed page 1 of 10 (1000 total)
Fetching page 2
Short-circuit: stopping after page 2
Resolving manager relationships for 200 employees...
Manager resolution complete: 180 resolved, 20 not found in employee list
Sample manager: {"id":"12345","firstName":"John","lastName":"Doe","email":"john.doe@company.com"}
Saved 200 employees with manager details
Related
- nango-integrations agent: Expert guidance on Nango sync patterns
- Nango docs: https://docs.nango.dev/integrate/guides/dry-run