Testing

This guide covers testing strategies and tools for integrating with the Flash Americas API, including sandbox environments, test data, and validation techniques.

Sandbox Environment

Use the sandbox environment for development and testing:

  • Base URL: https://ship.flashamericas.com/api/v1 (same as production)
  • Test Data: Simulated carriers and responses
  • Rate Limits: 100 requests per minute
  • API Keys: Contact support for sandbox credentials

Test Data

Sample Addresses

Test addressesjavascript
const testAddresses = {
validUS: {
  address1: "123 Main Street",
  city: "Dallas", 
  state: "TX",
  postalCode: "75201",
  country: "US"
},
validMX: {
  address1: "Av. Principal 456",
  city: "Mexico City",
  state: "CDMX", 
  postalCode: "09300",
  country: "MX"
},
invalid: {
  address1: "Invalid Address",
  city: "Nowhere",
  state: "XX",
  postalCode: "00000", 
  country: "US"
}
};

Test Scenarios

Comprehensive test suitejavascript
describe('Flash Americas API', () => {
test('should get quotes for valid domestic shipment', async () => {
  const response = await api.getQuote({
    originAddress: testAddresses.validUS,
    destinationAddress: {
      ...testAddresses.validUS,
      city: "Houston",
      postalCode: "77001"
    },
    cargo: [{
      weight: 25,
      length: 18, 
      width: 12,
      height: 10,
      quantity: 1,
      description: "Test package"
    }],
    shipDate: "2025-03-01"
  });
  
  expect(response.success).toBe(true);
  expect(response.data.quotes).toBeDefined();
  expect(response.data.quotes.length).toBeGreaterThan(0);
});

test('should handle invalid address gracefully', async () => {
  try {
    await api.getQuote({
      originAddress: testAddresses.validUS,
      destinationAddress: testAddresses.invalid,
      cargo: [{ /* ... */ }]
    });
  } catch (error) {
    expect(error.code).toBe('INVALID_ADDRESS');
  }
});

test('should respect rate limits', async () => {
  const requests = Array(110).fill().map(() => 
    api.getQuote(validQuoteRequest)
  );
  
  const results = await Promise.allSettled(requests);
  const rateLimited = results.filter(r => 
    r.status === 'rejected' && 
    r.reason.code === 'RATE_LIMIT_ERROR'
  );
  
  expect(rateLimited.length).toBeGreaterThan(0);
});
});

Integration Testing

Mock API Responses

API mocking for testsjavascript
// Mock successful quote response
const mockQuoteResponse = {
success: true,
data: {
  quotes: [{
    id: 'test-quote-1',
    provider: 'TEST_CARRIER',
    service: 'GROUND',
    cost: 12.45,
    transitDays: 2,
    deliveryDate: '2025-03-03'
  }]
}
};

// Mock API client for testing
class MockFlashAmericasClient {
async getQuote(request) {
  // Validate request structure
  if (!request.originAddress || !request.destinationAddress) {
    throw new Error('INVALID_REQUEST');
  }
  
  // Simulate rate limiting
  if (this.requestCount > 100) {
    throw new Error('RATE_LIMIT_ERROR');
  }
  
  return mockQuoteResponse;
}
}

Load Testing

Test your integration under high load:

Load testing scriptjavascript
const loadTest = async () => {
const concurrentRequests = 50;
const totalRequests = 1000;
const batchSize = concurrentRequests;

const results = {
  successful: 0,
  failed: 0,
  rateLimited: 0,
  averageResponseTime: 0
};

for (let i = 0; i < totalRequests; i += batchSize) {
  const batch = Array(batchSize).fill().map(async () => {
    const startTime = Date.now();
    
    try {
      await api.getQuote(testQuoteRequest);
      results.successful++;
      return Date.now() - startTime;
    } catch (error) {
      if (error.code === 'RATE_LIMIT_ERROR') {
        results.rateLimited++;
      } else {
        results.failed++;
      }
      return null;
    }
  });
  
  const batchResults = await Promise.allSettled(batch);
  
  // Add delay between batches to respect rate limits
  await new Promise(resolve => setTimeout(resolve, 1000));
}

console.log('Load test results:', results);
};

Best Practices

  1. Use Test Data: Always use appropriate test addresses and cargo
  2. Mock External Calls: Mock API responses for unit tests
  3. Test Error Scenarios: Verify error handling works correctly
  4. Validate Responses: Check response structure and data types
  5. Load Testing: Test under realistic load conditions
  6. CI/CD Integration: Include API tests in your deployment pipeline

Next Steps