IntegrationTesting Guide

Testing Guide

Before moving to production, verify every item on the checklists below in the development / staging environment.

HMAC Signature Validation

  • Signature is generated with HMAC-SHA256 using the canonical string partnerId | user_id | email | name | company_id | candidate_ids_csv.
  • Signature output is lowercase hexadecimal.
  • Requests with an invalid signature return 401 Invalid Signature.
  • The secretKey is not stored in frontend, mobile, or public repos.
  • Signature generation runs only on the backend server.
  • Signature for Test Vector 1 matches the expected value.
  • Signature for Test Vector 2 matches the expected value.

Session Endpoint

  • Request body matches the schema (user, company, candidates, signature).
  • A successful response returns sessionToken, widgetUrl, partnerId, and expiresIn.
  • The returned widgetUrl opens correctly in a browser tab and inside an iframe.
  • The expiresIn value is respected by the backend refresh logic.
  • Requests with missing or malformed fields return 400 Bad Request or 422 Validation Failed with a clear error payload.
  • Requests with a wrong partnerId return 404 Partner not found or inactive.

Widget Integration & Candidate Flow

  • widgetUrl is embedded via <iframe> in the partner application.
  • The widget opens without an additional manual login.
  • User and candidate data shown in the widget match the data sent in Create Session.
  • HR/recruiters can access the dashboard and monitor candidates through the widget.
  • Candidates can run through the assessment without issues.
  • The widget is only accessible from whitelisted domains.
  • Session expiration is handled by re-creating the session and refreshing the iframe with the new widgetUrl.

Error Handling

  • 400 Bad Request is handled without crashing the app.
  • 401 Unauthorized is handled when the signature is invalid or session expired.
  • 403 Forbidden is handled when the partner domain is not whitelisted.
  • 404 Not Found is handled with a meaningful user-facing message.
  • 500 Internal Server Error is handled with a user-friendly fallback.
  • Timeout handling is implemented when the API does not respond in time.
  • A fallback UI is shown when the iframe widget fails to load.

Go-to-Production Checklist

Verify the items below the day before going live in production.

Secret Key Management

  • Production secretKey has been received from PsikologieHub.
  • secretKey is stored via environment variable or a secret manager.
  • secretKey is not in frontend, mobile app, or any public repository.
  • A secretKey rotation plan is in place.

Production Session Endpoint

  • The production endpoint is reachable from the partner backend.
  • Signature validation succeeds.
  • Successful response includes sessionToken, widgetUrl, and expiresIn.
  • Session expiration is correctly handled.
  • Backend logging is active for integration monitoring.

Widget iframe (Production)

  • iframe loads on the production environment without console errors.
  • The widget responsive on desktop and laptop resolutions.
  • Content Security Policy (CSP) does not block the iframe.

Security & Monitoring

  • All API communication uses HTTPS/TLS.
  • API requests are recorded in the backend log.
  • Session tokens are not stored in localStorage without additional encryption.
  • The secretKey is not exposed via browser devtools.
  • API error monitoring is active.
  • Timeout and retry mechanisms are applied on the backend.
  • HR/recruiter access control is enforced on the partner side.
Error Handling