SPDCI Compliance Test Suite

Unified compliance testing framework for SPDCI (Social Protection Digital Convergence Initiative) API standards.

Supported Registries

Domain	Spec	Status
Social Registry (SR)	`social_api_v1.0.0.yaml`	Registry Profile
Civil Registration (CRVS)	`crvs_api_v1.0.0.yaml`	Registry Profile
Disability Registry (DR)	`dr_api_v1.0.0.yaml`	Core Happy Path
Farmer Registry (FR)	`fr_api_v1.0.0.yaml`	Registry Profile
ID & Beneficiary Registry (IBR)	`ibr_api_v1.0.0.yaml`	Not Implemented

SR, CRVS, and FR registry profiles cover the registry server endpoints and async callback workflows. Subscriber/client profiles are separate and are not included in npm run test:<domain>. DR coverage includes core happy-path registry workflows and DR-specific sync endpoints. Negative, security, and client-trigger parity with SR, CRVS, and FR is not yet implemented.

Project Structure

spdci-compliance/
├── common/                     # Shared infrastructure
│   ├── helpers/               # Request builders, validators, utilities
│   │   ├── index.js           # Re-exports all helpers
│   │   ├── envelope.js        # Message envelope (header, signature, message)
│   │   ├── headers.js         # Header builders and validators
│   │   ├── openapi-validator.js
│   │   └── callback-server.js # Callback server for async testing
│   ├── features/              # Shared test scenarios reusable across domains
│   │   ├── validation_format.feature   # Timestamp, locale format tests
│   │   ├── validation_boundary.feature # String length boundary tests
│   │   ├── pagination.feature          # Pagination parameter tests
│   │   ├── client_compliance.feature   # SPMIS client tests
│   │   ├── security_headers.feature    # Security header tests
│   │   └── support/           # Shared step definitions
│   ├── requirements.json      # Common compliance requirements (DCI-*)
│   └── mock-server/           # Mock registry for client testing
│       └── server.mjs
├── domains/                    # Domain-specific tests
│   ├── social/                # Social Registry (implemented)
│   │   ├── features/          # SR-specific scenarios
│   │   ├── payloads/          # SR-specific data generators
│   │   ├── requirements.json  # SR-specific requirements (SR-*)
│   │   └── config.js          # SR endpoints, record types
│   ├── crvs/                  # Civil Registration (implemented)
│   │   ├── features/          # CRVS-specific scenarios
│   │   └── requirements.json  # CRVS-specific requirements
│   ├── dr/                    # Disability Registry
│   ├── fr/                    # Farmer Registry (implemented)
│   │   ├── features/          # FR-specific scenarios
│   │   └── requirements.json  # FR-specific requirements
│   └── ibr/                   # ID & Beneficiary Registry (not implemented)
├── spec/                       # OpenAPI specifications
└── cucumber.cjs                # Cucumber configuration

Shared vs Domain-Specific

Shared (common/)

All SPDCI specs share:

Message envelope: signature, header, message structure
Header format: version, message_id, sender_id, receiver_id, action, etc.
Async pattern: Request → ACK → Callback (on-*)
Error responses: ACK/ERR with error codes
Security: Authorization header handling, invalid signature rejection
Endpoints pattern: /registry/search, /registry/subscribe, /registry/txn/status

Domain-Specific (domains/)

Each registry has:

Record types: Person, Group, BirthCertificate, DisabledPerson, etc.
Query attributes: Domain-specific searchable fields
Event types: Domain-specific subscription events
Validation rules: Domain-specific business logic

Usage

Run all tests

npm test

Run tests for a specific domain

npm run test:social
npm run test:crvs
npm run test:dr
npm run test:fr

Run tests against the mock server

These scripts automatically start the mock server, run the tests, and shut down the server:

npm run test:mock:social   # Social registry tests against mock
npm run test:mock:crvs     # CRVS tests against mock
npm run test:mock:fr       # FR tests against mock
npm run test:mock:dr       # Disability Registry tests against mock

The mock server runs on http://127.0.0.1:3335/ and the correct DOMAIN env var is set automatically.

Run by tier

npm run test:core    # Core compliance requirements
npm run test:smoke   # Quick smoke tests

Run with specific tags

npx cucumber-js --tags '@profile=sr-registry and @tier=core'
npx cucumber-js --tags '@endpoint=registry/search'
npx cucumber-js --tags '@smoke'

Environment Variables

Connection

Variable	Default	Description
`API_BASE_URL`	`http://127.0.0.1:3333/`	Target API base URL
`DOMAIN`	`social`	Active domain (social, crvs, dr, fr, ibr)
`OPENAPI_SPEC_PATH`	Auto-detected	Path to OpenAPI spec
`CALLBACK_SERVER_PORT`	`3336`	Callback receiver port

Authentication

The test suite does not assume any authentication mechanism by default. Configure auth using:

Variable	Description
`DCI_AUTH_TOKEN`	Bearer token (auto-prefixed with "Bearer " if needed)
`AUTH_TOKEN`	Alternative to DCI_AUTH_TOKEN
`EXTRA_HEADERS_JSON`	Additional headers as JSON: `{"Authorization":"Bearer xxx","X-Tenant":"abc"}`
`EXTRA_HEADERS`	Additional headers as string: `Authorization:Bearer xxx;X-Tenant:abc`

Example:

# Using bearer token
DCI_AUTH_TOKEN=your-token-here npm run test:social

# Using custom headers for gateway/tenancy
EXTRA_HEADERS_JSON='{"Authorization":"Bearer xxx","X-Tenant-ID":"tenant1"}' npm run test:social

Adding a New Domain

Create domain folder: domains/<domain>/
Add domain config: domains/<domain>/config.js
Add payloads: domains/<domain>/payloads/
Add domain-specific features: domains/<domain>/features/
Copy/symlink spec to spec/

Test Profiles

Registry Server Testing (`<domain>-registry`)

Test that a registry server correctly implements the SPDCI spec:

# Test a Social Registry server
API_BASE_URL=http://sr-server:8080 DOMAIN=social npm run test:social

Client Testing (`spmis-client`)

Test that an SPMIS client correctly sends requests to registries:

# Option 1: Verify registry profiles against the mock server
npm run test:mock:social
npm run test:mock:crvs
npm run test:mock:fr

# Option 2: Manual setup
# 1. Start the mock registry server for a specific domain
npm run mock-server:social   # or mock-server:crvs, mock-server:fr

# 2. Configure your client to use http://localhost:3335

# 3. Run client compliance tests (requires client trigger API and client-profile steps)
PROFILE=spmis-client CLIENT_TRIGGER_URL=http://your-client:8080/test/trigger npm test

The mock server:

Enforces OpenAPI request validation by default
Requires syntactically valid Bearer Authorization headers for secured OpenAPI operations by default
Rejects known invalid test signature values by default
Records all requests for assertion
Sends async callbacks to client's sender_uri
Provides admin API for test control

See common/mock-server/README.md for details.

Spec Issues and Local Fixes

During test development, we found inconsistencies in the SPDCI OpenAPI specifications. These have been fixed locally in the spec/ directory and reported upstream.

See SPEC_ISSUES_REPORT.md for details on:

Typo: sunscription_codes → subscription_codes (CRVS, FR)
Schema: oneOf → anyOf for attribute_value (CRVS, FR)
Type: reg_records object → array (FR)

Acknowledgments

This project builds upon the work of the Social Protection Digital Convergence Initiative (SPDCI):

SR Mockup Compliance: spdci/SR-Mockup-Compliance - The original Social Registry compliance test suite by @aishamerhebi that served as the starting point for this project
API Standards: spdci/api-standards - The OpenAPI specifications this test suite validates against
Schemas: spdci/schemas - JSON schemas for SPDCI data models

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 - See LICENSE for details.

Navigation Menu

Uh oh!

Repository files navigation

SPDCI Compliance Test Suite

Supported Registries

Project Structure

Shared vs Domain-Specific

Shared (common/)

Domain-Specific (domains/)

Usage

Run all tests

Run tests for a specific domain

Run tests against the mock server

Run by tier

Run with specific tags

Environment Variables

Connection

Authentication

Adding a New Domain

Test Profiles

Registry Server Testing (`<domain>-registry`)

Client Testing (`spmis-client`)

Spec Issues and Local Fixes

Acknowledgments

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
common		common
domains		domains
spec		spec
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SPEC_ISSUES_REPORT.md		SPEC_ISSUES_REPORT.md
cucumber.cjs		cucumber.cjs
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

SPDCI Compliance Test Suite

Supported Registries

Project Structure

Shared vs Domain-Specific

Shared (common/)

Domain-Specific (domains/)

Usage

Run all tests

Run tests for a specific domain

Run tests against the mock server

Run by tier

Run with specific tags

Environment Variables

Connection

Authentication

Adding a New Domain

Test Profiles

Registry Server Testing (<domain>-registry)

Client Testing (spmis-client)

Spec Issues and Local Fixes

Acknowledgments

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Registry Server Testing (`<domain>-registry`)

Client Testing (`spmis-client`)