User Acceptance Testing Guide

Before your employment verification integration goes live, validate the full candidate experience and API integration. This guide walks through testing using your sandbox environment and provides a checklist to confirm everything works.

About Test Mode

During onboarding, your organization operates in Test Mode. You'll see a "Test Mode" badge on your portal dashboard. In this mode:

  • Your test key (sk_test_) returns sandbox fixture responses — no real candidate data is involved
  • Your live key (sk_live_) exists but is not yet enabled for production
  • The sandbox intercepts API calls made with test keys and returns pre-built JSON responses

Using the Test Harness

Your portal includes a Test Harness that lets you test the API interactively without writing code.

  1. Navigate to your portal (e.g., https://trua.cloud/sites/GC)
  2. Click Test Harness in the navigation
  3. Enter a candidate ID and click Try It
  4. The sandbox returns a fixture response displayed on the page

Sandbox Fixture Responses

Candidate ID Response
Any valid ID (e.g., INV-12345) Success — complete lifecycle data with sample steps and transitions
404 Not found — simulates a missing or unauthorized candidate
500 Server error — for testing your error handling

Testing with curl

Test directly from the command line using the test key from your API Keys page:

bash 
# Success response
curl -X GET https://trua.cloud/api/v1/candidates/INV-12345/lifecycle \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx"

# Not-found response
curl -X GET https://trua.cloud/api/v1/candidates/404/lifecycle \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx"

# Error response
curl -X GET https://trua.cloud/api/v1/candidates/500/lifecycle \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx"

Testing the Candidate Wizard

Test the full candidate experience end-to-end by creating a real invitation to your own email.

Step 1: Create a Test Invitation

From the Trua Cloud admin panel (or via API), create an invitation using a test email you control (e.g., uat-tester@yourcompany.com).

Step 2: Walk Through the Wizard

Click the link in the invitation email. The access code is validated automatically — you'll land directly on the first step. Complete each step:

  1. Personal Info — Enter test candidate name and email
  2. Biometric Enrollment — Complete the facial capture (use your device's front camera)
  3. Employment History — Add at least two employers to test the timeline:
    • Add an employer with start/end dates
    • Add a second employer, leaving a gap between them to test gap detection
    • Try marking one as "current employer"
    • Test the "I don't have a contact" option on one entry
    • Verify the timeline requirement indicator updates as you add entries
  4. Review — Verify all entered data appears correctly; try clicking "Edit" to go back
  5. Signature — Draw a signature and submit

Step 3: Test Session Resumption

During the wizard walkthrough:

  1. Complete one or two steps
  2. Close the browser entirely
  3. Re-open the invitation link
  4. Confirm the wizard resumes at the step where you left off with all data intact

Step 4: Test Invalid Code

Navigate to https://trua.cloud/start?code=0000 — confirm it shows the start page with an error message and the code field pre-filled, rather than proceeding.

Step 5: Monitor via Admin Panel

After submitting the test wizard:

  1. Log in to the admin panel
  2. Find your test invitation — confirm status is Submitted
  3. View the submission data — confirm all entered employment history, personal info, and signature are present
  4. Download the PDF — confirm it contains all submitted data

Verifying Error Handling

Confirm your integration handles error responses:

bash 
# Invalid API key → 401 Unauthorized
curl -X GET https://trua.cloud/api/v1/candidates/INV-12345/lifecycle \
  -H "Authorization: Bearer invalid_key_here"

# Nonexistent candidate → 404 Not Found
curl -X GET https://trua.cloud/api/v1/candidates/404/lifecycle \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx"

Your integration should handle 401, 404, and 429 responses gracefully.

Reporting Issues

If you encounter unexpected behavior during UAT, contact Trua Cloud support with:

  • Candidate ID (the INV-XXXXX identifier)
  • Step where the issue occurred
  • Expected vs. actual behavior
  • Browser and device (for wizard UI issues)
  • Request and response details (for API issues)

Email support@trua.com or contact your account representative.

UAT Checklist

Portal Access

  • [ ] Can log in to the portal with provided credentials
  • [ ] Dashboard shows organization name and integration status
  • [ ] API Keys page displays test and live key prefixes
  • [ ] Documentation page lists assigned guides
  • [ ] Test Harness returns fixture response for a sample candidate ID

Candidate Wizard — Employment Verification

  • [ ] Invitation email arrives with embedded link
  • [ ] Clicking the link auto-validates and enters the wizard (no manual code entry)
  • [ ] Personal Info step accepts name and email
  • [ ] Biometric Enrollment completes facial capture
  • [ ] Employment History accepts multiple employer entries
  • [ ] Gap detection highlights timeline gaps between employers
  • [ ] Timeline requirement indicator shows progress toward lookback period
  • [ ] Requirements warning appears when timeline is incomplete — candidate can still proceed
  • [ ] Review step displays all entered data accurately
  • [ ] "Edit" links on Review step navigate back to the correct step
  • [ ] Signature step captures electronic signature
  • [ ] Submission confirmation is displayed after signing
  • [ ] Confirmation email arrives at the candidate's address
  • [ ] Closing browser and reopening the link resumes at the correct step
  • [ ] Previously entered data is preserved after session resumption

API Integration

  • [ ] Test key returns sandbox fixture for valid candidate ID
  • [ ] Test key returns not-found fixture for candidate ID 404
  • [ ] Test key returns error fixture for candidate ID 500
  • [ ] Invalid API key returns 401 Unauthorized
  • [ ] Your integration parses the response correctly
  • [ ] Your integration handles 401, 404, and 429 errors gracefully

Production Readiness

  • [ ] Live API key is stored securely in your production environment
  • [ ] Production base URL (https://trua.cloud) is configured
  • [ ] Webhook endpoint is receiving events (if using webhooks)
  • [ ] Error handling for all error responses is implemented and tested
  • [ ] Your Trua Cloud admin has confirmed all readiness checks pass