Read as Markdown · Use with an AI agent
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, plus your application’s required-field checks. Make the network layer injectable so tests cannot accidentally call production.
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 '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.
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/balanceto check authentication and current balance at zero credit cost. Read the public catalogue 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 to test linked calls and the production guide to turn a successful smoke test into an operational integration.