# Test your integration

Test parsing and failure handling without spending credits, then verify the exact production operation with a small, explicitly budgeted live request.

## 1. Start with offline fixtures

Keep representative success, partial and error envelopes in your own test suite. Use fictional records or redact captured content. Validate the documented fields using [endpoint schemas](https://www.monocrawl.com/docs/schemas), plus your application’s required-field checks. Make the network layer injectable so tests cannot accidentally call production.

**Node.js · offline test of the downloaded client**

```
import assert from 'node:assert/strict';
import { createClient } from './monocrawl-client.mjs';
const client = createClient({
  apiKey: 'offline-only', budget: 1,
  fetchImpl: async () => new Response(JSON.stringify({
    success: true, request_id: 'req_fixture', credits_used: 1,
    data: { id: '7350000000000000001', followers: null },
  }), { status: 200 }),
});
const result = await client.get('tiktok/profile', { handle: 'example' }, { quote: 1 });
assert.equal(result.data.followers, null);
assert.equal(client.spent, 1);
```

| Fixture | What to assert |
| --- | --- |
| Null, absent, zero and large string IDs | Unknown remains unknown; zero remains valid; identifiers keep every digit. |
| Empty page, repeated cursor and duplicate ID | No infinite loop; bounded calls; no silent loss of unidentified records. |
| Partial bundle or truncated comment tree | Retain usable rows and expose component warnings and missing coverage. |
| 429 with Retry-After | Honor the delay, retain the same key and stop when the attempt or wait budget is reached. |
| Timeout before headers or during body read | Reuse the original key and parameters; do not create a second logical request. |
| Idempotent replay | Use the saved outcome once; its original credits_used is not a new debit. |
| Pending reconciliation or in-progress conflict | Keep the original request unresolved; do not treat it as a confirmed zero charge. |
| 401 / 402 / 422 | Stop rather than repeatedly retrying a request that needs intervention. |
| Budget reached or actual price above estimate | Stop further calls and retain earlier results. A key cap supplies the hard ceiling. |

## 2. Use the explicit sandbox surface

Send the same authentication header to `/sandbox/PLATFORM/ENDPOINT`. The sandbox produces representative synthetic data, uses the sample engine even for production-supported endpoints, and costs zero credits. It still authenticates and applies API limits. Use a real API key in the header, never in the query string.

**curl · synthetic profile sample**

```
curl 'https://www.monocrawl.com/sandbox/tiktok/profile?handle=nasa' \
  -H 'x-api-key: YOUR_API_KEY'
```

Assert `synthetic:true` and `credits_used:0`, and keep the sandbox path with saved samples. Sandbox payloads are demonstrations; they do not prove current upstream availability, exact optional fields, pagination depth, live prices or real source coverage. Use your fixtures to test endpoint-specific edge cases.

Production `/v1` does not substitute synthetic samples after a source failure. Keep sandbox records out of production datasets. See [sandbox response details](https://www.monocrawl.com/docs/errors#degraded-responses).

## 3. Run a small live smoke test

- Create a dedicated capped key. Set its cumulative limit to your approved test allowance and disable unrelated jobs using it.

- Read `GET /v1/credits/balance` to check authentication and current balance at zero credit cost. Read the public [catalogue](https://www.monocrawl.com/openapi.json) for the intended route’s current price and availability.

- Make one direct production request with a saved idempotency key. Use a known public record on the platform and inspect the full envelope, not only HTTP status.

- Check types, nulls, warnings, source identifiers, marketplace, continuation and confirmed credit usage. If needed, make one continuation request within the remaining allowance.

- Keep a redacted fixture from the result and verify the job can restart without repeating completed work. If the outcome is unresolved, reconcile it before another live run.

A live smoke test can spend credits and tests only the selected path and input at that time. Avoid making paid source calls part of ordinary CI. Keep offline tests deterministic; run separately budgeted smoke tests when validating a release or investigating a source change.

Use the [bounded workflows](https://www.monocrawl.com/docs/workflows) to test linked calls and the [production guide](https://www.monocrawl.com/docs/production-checklist) to turn a successful smoke test into an operational integration.