name	nango-dry-run
description	Use when testing Nango syncs locally - runs dry-run command with proper parameters for integration testing without affecting production data

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

nango-integrations agent: Expert guidance on Nango sync patterns
Nango docs: https://docs.nango.dev/integrate/guides/dry-run

nango-dry-run

Install Skill

SKILL.md