tests-untp

A comprehensive suite of tools for implementing and demonstrating the UN Transparency Protocol (UNTP) specification. The repository includes:

1. Reference Implementation: A multi-tenant application for issuing, storing, and verifying UNTP-compliant verifiable credentials such as Digital Product Passports (DPPs), Digital Conformity Credentials (DCCs), and more.
2. Test Suites: Technical interoperability, semantic interoperability, and graph validation testing.
3. Playground: A web application for validating UNTP credentials against the specification.
4. Documentation Site: Comprehensive resources covering setup, configuration, and usage.

Quick Start

Prerequisites

• Docker with Compose (latest version recommended)
• Node.js >= 22.22.2; pnpm 9.15.4 (managed via Corepack)

We recommend using Node Version Manager (NVM) to manage Node.js versions:

nvm install 22.22.2
nvm use 22.22.2
corepack enable
pnpm install

Start with Docker Compose

The fastest way to get everything running:

git clone https://github.com/uncefact/tests-untp.git
cd tests-untp
cp .env.example .env
docker compose up -d --build

This starts the Reference Implementation and all dependent services. See the Quick Start guide for full details.

Resetting Services

To tear down all containers and remove all data volumes (databases, Keycloak realm data, etc.):

docker compose down -v

Warning: The -v flag removes all named volumes. This deletes all database data and forces Keycloak to re-import its realm configuration on the next start. Only use this when you need a clean slate.

To reset a specific service's data without affecting others, remove its volume individually. For example, to reset Keycloak so it re-imports the latest realm configuration:

docker compose down
docker volume rm tests-untp_keycloak-data
docker compose up -d --build

Local Development

For development with hot reloading, stop the Reference Implementation container and run it locally instead.

Warning: Running the Reference Implementation on the host needs a one-line Keycloak change first. The Compose config sets KC_HOSTNAME to http://keycloak:8080 for the containerised RI, but the host process cannot resolve keycloak:8080 and the issuer in Keycloak's tokens would not match, so API authentication fails. Before the steps below, change KC_HOSTNAME to http://localhost:8080 in docker-compose.yml and recreate Keycloak with docker compose up -d keycloak. Revert it to http://keycloak:8080 before running the Reference Implementation in Docker again.

docker compose stop ri
pnpm build
pnpm start

Note: Ensure you have completed the Prerequisites before running locally.

The dependent services continue running in Docker while the Reference Implementation runs locally at http://localhost:3003. See Authentication for how to obtain an API token.

Architecture

The Reference Implementation is an orchestration layer that delegates to several dependent services:

Service	Purpose
Verifiable Credential Service	DID management, credential signing and verification
Storage Service	Credential and template storage
Identity Resolver Service	Links identifiers to associated credentials
Identity Provider (Keycloak)	Authentication and tenant resolution
PostgreSQL	Database for the Reference Implementation and VC service

For a detailed overview of how these components connect, see System Architecture and Service Architecture.

Documentation

The documentation site is included in the Docker Compose stack at http://localhost:3002, or view the deployed version at https://uncefact.github.io/tests-untp/.

Key pages:

• Overview — what the Reference Implementation does and why
• Quick Start — getting started with Docker Compose
• System Architecture — how the components connect
• Authentication — browser sessions and service accounts
• API Documentation — interactive Swagger UI (requires running instance)

To run the documentation site outside Docker:

cd documentation
pnpm install
pnpm start

Development

pnpm build                    # Full build (services + components + test-suite)
pnpm start                    # Start Reference Implementation dev server
pnpm test                     # Run all tests
pnpm lint:check               # ESLint across packages

Observability

The reference implementation is instrumented with OpenTelemetry. To run the local trace stack (Tempo + OTel agent + Grafana) alongside the app, use docker compose --profile local-observability up -d --build. See docs/observability.md for the full guide.

End-to-End Testing

E2E tests use Cypress and support both local Docker Compose and deployed instances. Each app owns its own E2E suite:

• packages/reference-implementation/e2e/ for the reference implementation.
• packages/untp-playground/e2e/ for the playground.

See each suite's README for setup, local testing, deployed instance prerequisites, and tenant mode configuration.

Release Management

See the release management guide and release guide.

Contributions

See CONTRIBUTING.md.