Testing a Location Integration

An integration has several moving parts: your server, the UPCS API, the browser script and your database. A balanced test plan covers each without spending your request allowance or depending on the network.

Unit tests with mocked responses

Isolate your own logic by replacing the HTTP call. Write fixtures that mirror the documented shapes:

// Example with a hand-rolled fake
const okLookup = {
  upcs_code: 'PK-1A2B-3C4D',
  location: { latitude: 31.5204, longitude: 74.3587, country_code: 'PK' },
  share_url: 'https://example.invalid/share'
};

test('stores verified code', async () => {
  const fakeFetch = async () => ({ ok: true, status: 200, json: async () => okLookup });
  const result = await verifyAndStore('pk-1a2b-3c4d', { fetch: fakeFetch });
  expect(result.upcs_code).toBe('PK-1A2B-3C4D');
});

Test the error paths

Failures are where integrations break. Cover at least:

• 404 on lookup (and 400 for a malformed code): "unknown code" message shown.
• 401 session_expired and key_inactive (the latter appears only on a running embedded map): see handling onError and session_expired.
• 403 origin_not_allowed.
• 422 unsupported_location: handling it.
• 429 rate_limited: your backoff behaves, see rate limits and backoff.
• Timeouts and malformed JSON.

The error codes reference lists them all.

Database tests

Assert that submitting the same order location twice leaves one row, and that null codes are accepted. See idempotency for location API calls.

A small live smoke test

Run one lookup and one session creation against the real API from a scheduled job or before deployment, using a separate key. It confirms the key, origin and network path, not your business logic.

Manual browser checks

Automated tests rarely cover the embed. Before release, check on desktop and phone:

1. The map loads and a selection fills the form.
2. The page still works when the session endpoint fails.
3. Keyboard users can reach and leave the map.
4. Destroying and remounting the map does not leave duplicates; see embed lifecycle.

Use a development key and http://localhost origin as described in local development with localhost.