Testing

Test with real assessments

Create and publish assessments in your Edpire dashboard before testing your integration. Your API key gives access to the same assessments your learners will see — no separate test environment needed.

# .env.local
EDPIRE_API_KEY=edp_live_<your-api-key>

Keeping test data out of your real numbers

Edpire does not run a separate sandbox environment, and there is no edp_test_ key type. Test submissions are real submissions, so if you send them into your production organization they land in your analytics and your usage counters. Create a second organization for development. It is the recommended pattern and it costs nothing:

Sign up a second organization (for example “Acme — Sandbox”)
Create its own API key under Integrations
Register your localhost and staging domains under Integrations → Security
Copy or rebuild the handful of assessments you need to test against

Because quotas, analytics and active-learner counts are all scoped per organization, nothing your developers do can distort your real reporting or your bill. When you go live, swap the API key and the webhook URL. Nothing else changes.

Load testing and attack simulation are different and need our involvement. Do not run them against production. Request a pen test window as described in Security Posture, at least 5 business days ahead.

Test the complete flow end-to-end

Before going live, run through the full learner journey with your chosen integration pattern:

Hosted Redirect

Build the share URL with your assessment’s share code
Open it in a private browser window (to simulate a fresh learner session)
Complete the assessment
Verify the redirect lands on your return_url with submission_id, score, and max_score appended
Fetch the submission via GET /api/v1/submissions/{id} and confirm the response shape matches your data model

Embedded Player

Mint an embed token from your server via client.mintEmbedToken()
Call EdpireAssessment.mount({ token, container }) in the browser
Complete the assessment — verify the player mounts, renders questions, and accepts answers
Submit and confirm onComplete fires with the correct result shape
Verify per-question feedback is shown inline after submission

Custom Flow

Fetch an assessment through your backend proxy and flatten with flattenAssessment()
Render each step with your custom UI using EdpireQuestion or renderQuestion
After each answer, call your /check proxy — verify feedback shape matches the question type
Confirm correct: true feedback is returned for known-correct answers
After all questions, submit via client.submit() and verify the full submission record

Test webhooks locally

Your local server isn’t reachable from Edpire’s servers directly. Use ngrok or Cloudflare Tunnel to expose a local port:

ngrok http 3000
# Forwarding: https://abc123.ngrok.io -> http://localhost:3000

curl -X POST https://edpire.com/api/v1/webhooks \
  -H "Authorization: Bearer edp_live_<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/webhooks/edpire",
    "events": ["submission.graded"]
  }'

Store the secret from the response. Complete an assessment — the webhook fires to your local handler in real time.

Verify signature verification

Confirm your signature verification logic rejects tampered requests:

// Send a request with a wrong signature — your handler should return 401
const fakeSignature = "sha256=0000000000000000000000000000000000000000000000000000000000000000"
const res = await fetch("http://localhost:3000/webhooks/edpire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Edpire-Signature": fakeSignature,
  },
  body: JSON.stringify({ event: "submission.graded", submission_id: "test" }),
})
assert(res.status === 401)

Test idempotency

The same webhook event can be delivered more than once. Your handler must be safe to call twice with the same payload:

Complete an assessment — your handler processes the submission.graded event
Replay the exact same POST body to your webhook handler (copy from ngrok’s request log)
Verify your database has exactly one record, not two

// Good — idempotent check before write
if (await db.submissionExists(req.body.submission_id)) {
  return res.sendStatus(200) // already processed
}
await db.saveSubmission(...)

Test error paths

Don’t only test the happy path. Verify your integration handles:

Scenario	How to trigger
Invalid API key	Use a wrong or revoked key — expect `401`
Missing scope	Use a key without `read:results` on a submissions call — expect `403`
Assessment not found	Request a non-existent assessment ID — expect `404`
Max attempts exceeded	Submit the same assessment more than its allowed attempt count — expect `409`
Rate limit (general)	Send 301+ requests per minute on any endpoint — expect `429` with `Retry-After`
Rate limit (submit)	Send 101+ requests per minute to `/assessments/{id}/submit` — expect `429`
Check lockout	Call `/check` a 4th time for the same question and `session_id` within an hour — expect `429`

Pre-production checklist

There is no separate test key type: you develop and go live with the same edp_live_ key (see Keeping test data out of your real numbers below). This is the list to work through before you point real learners at the integration:

All API calls go through your server — no edp_live_ keys in the browser
return_url and back_url match Allowed API & Redirect Origins; embedding pages match Allowed Embed Origins
Webhook signature verification is enabled and tested
Idempotency check is in place for submission.graded
Error responses are handled (retry on 429/500, alert on persistent 5xx)
learner_ref is your stable internal user ID — not email, not username
EDPIRE_API_KEY is in environment variables, not committed to source control

See the full Security checklist before going live.

Getting Started

For Platforms & Developers

For Schools

Test with real assessments

Keeping test data out of your real numbers

Test the complete flow end-to-end

Test webhooks locally

Verify signature verification

Test idempotency

Test error paths

Pre-production checklist

​Test with real assessments

​Keeping test data out of your real numbers

​Test the complete flow end-to-end

​Test webhooks locally

​Verify signature verification

​Test idempotency

​Test error paths

​Pre-production checklist

Test with real assessments

Keeping test data out of your real numbers

Test the complete flow end-to-end

Test webhooks locally

Verify signature verification

Test idempotency

Test error paths

Pre-production checklist