Testing

This document covers how to test zkIdentity verification flows, from local development through sandbox provider testing to pre-production validation.

Testing Environments

zkIdentity supports three testing environments, each offering a different level of fidelity:

Environment	TEE Mode	KYC Provider	Blockchain	Use Case
Local	Simulation	Mock provider	Local Cartesi node	Development and unit testing
Sandbox	Simulation	Provider sandbox APIs	Testnet (Arbitrum Sepolia)	Integration testing
Staging	Production	Provider sandbox APIs	Testnet (Arbitrum Sepolia)	Pre-production validation

Local Testing with Mock Providers

For local development, the attestor can be configured to use mock KYC providers that simulate both Smile ID and Plaid APIs. This allows development without requiring real provider accounts.

Configuring for Local Testing

The key local testing configuration settings are:

• Set the environment to development.
• Set TEE mode to simulation.
• Point provider base URLs to the local mock provider.
• Use any values for provider credentials (mock provider accepts any credentials).
• Point blockchain URLs to local endpoints.

Simulating Verification Outcomes

The mock provider should support different test scenarios to exercise various code paths:

• Successful verification: Provider returns verified status. All 14 ZK proofs generated.
• Failed verification: Provider returns rejected status.
• Timeout: Provider does not respond. Tests session expiry handling.
• Partial data: Provider returns incomplete data. Tests error handling.

Running Tests

Consult the project's README or contributing guide for the specific commands to run unit tests, integration tests, and the test suite.

Sandbox Provider Testing

Sandbox testing uses real provider APIs in their sandbox/test mode. This validates the actual API integration without processing real identity documents.

Smile ID Sandbox

1. Configure the attestor with sandbox credentials from Smile ID.
2. Start the attestor.
3. Initiate a verification via the frontend or API. In sandbox mode, use the test document numbers specified in the Smile ID sandbox documentation.
4. The attestor will generate real ZK proofs over the sandbox response.

Plaid Sandbox

1. Configure the attestor with sandbox credentials from Plaid.
2. Start the attestor and initiate a verification.
3. When the Plaid Link widget appears, use the sandbox test credentials provided in the Plaid documentation.
4. The verification completes with simulated identity data.

Validating Sandbox Results

After a sandbox verification completes, validate that:

• The attestation was submitted to the rollup.
• All 14 ZK proofs were generated and are valid.
• The encrypted document reference was uploaded to IPFS.
• The non-PII metadata stored on-chain matches expectations.

End-to-End Testing

End-to-end tests should simulate the complete user journey including frontend interaction. The test suite should cover:

• Wallet connection via Privy
• Provider selection based on country
• Full verification flow with each provider (sandbox)
• Status polling and result display
• On-chain proof verification after completion
• Session expiry behavior
• Error handling and display

Pre-Production Validation

Before deploying to production, validate:

1. TEE Attestation

Verify the attestor is running in a real TEE (not simulation mode). The TEE attestation report should be valid and the code measurement should match the published hash.

2. Provider Connectivity

Confirm the attestor can reach all configured KYC providers, the IPFS pinning service, and the Cartesi rollup endpoint.

3. Full Flow Validation

Execute a complete verification using sandbox providers on the staging environment with both Smile ID and Plaid.

4. Wallet Balance

Confirm the attestor wallet on Arbitrum has sufficient ETH for rollup submissions.

Common Testing Issues

Issue	Likely Cause	Resolution
Sandbox webhook not received	Webhook URL not reachable from provider	Use a tunneling tool for local testing; verify URL in provider dashboard
Proof generation timeout	Insufficient resources	Increase timeout settings; ensure adequate CPU/RAM
Rollup submission fails	Local Cartesi node not running	Start the local rollup node
IPFS upload fails	Pinata credentials invalid or rate limited	Verify credentials; check Pinata dashboard

Related Documentation

• Configuration -- Environment variables for each testing mode.
• Provider Setup -- Provider sandbox credentials and test data.
• Troubleshooting -- Resolving common issues.