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`	Complete
Civil Registration (CRVS)	`crvs_api_v1.0.0.yaml`	Complete
Disbursement Registry (DR)	`dr_api_v1.0.0.yaml`	Not Implemented
Functional Registry (FR)	`fr_api_v1.0.0.yaml`	Complete
ID & Beneficiary Registry (IBR)	`ibr_api_v1.0.0.yaml`	Not 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 (apply to ALL 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/                    # Disbursement Registry (not implemented)
│   ├── fr/                    # Functional 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 headers, signature validation
Endpoints pattern: /registry/search, /registry/subscribe, /registry/txn/status

Domain-Specific (domains/)

Each registry has:

Record types: Person, Group, BirthCertificate, Disbursement, 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: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

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: Use the combined test scripts (recommended)
npm run test:mock:social   # Starts mock server + runs tests
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)
PROFILE=spmis-client CLIENT_TRIGGER_URL=http://your-client:8080/test/trigger npm test

The mock server:

Validates incoming requests against the OpenAPI spec
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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Uh oh!

Releases

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
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

License

OpenSPP/spdci-compliance

Folders and files

Latest commit

History

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

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

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

Client Testing (`spmis-client`)

Packages