@proconnect-gouv/proconnect.testing

Mock server and CLI tools for testing ProConnect integrations with external APIs.

What

This package provides:

• Mock API Server: HTTP server that mimics external service responses
• CLI Tools: Commands for fetching and managing test data from real APIs
• Test Data: Pre-populated JSON responses for common scenarios
• Integration Tests: Test suite ensuring mock endpoints work correctly

Why

• Testing without external dependencies: Test ProConnect integrations without hitting real APIs during development and CI
• Deterministic test data: Consistent mock responses for reliable and reproducible tests
• Development environment: Local development without needing API tokens, rate limits, or network connectivity
• Data privacy: Anonymized test data for non-public enterprise information
• Performance: Fast local responses vs. external API calls

How

Mock Server Usage

Create a testing handler and mount it in your application:

import { createTestingHandler } from "@proconnect-gouv/proconnect.testing/api";
import { createServer } from "http";

const handler = createTestingHandler("/testing", {
  ISSUER: "oidc.franceconnect.localhost",
  log: console.log,
});

const server = createServer(handler);
server.listen(3000);
// Server running at http://localhost:3000/testing

The handler uses Hono framework and provides:

• Structured logging with 🎭 prefix
• Error handling and 404 responses
• Health check endpoint at /healthz

CLI Tools

Adding Enterprise Test Data

Fetch real establishment data and save it as anonymized test data:

Specific .env

For regular use, do not follow the next exports instructions. Create a .env.development.local file with:

ENTREPRISE_API_TOKEN="your api key"
ENTREPRISE_API_URL="https://entreprise.api.gouv.fr

Comment it out by default and uncomment it when you want to extract data.

# Set up environment variables
export ENTREPRISE_API_TOKEN="your-api-token"
export ENTREPRISE_API_URL="https://entreprise.api.gouv.fr"
export ENTREPRISE_API_TRACKING_CONTEXT="testing"
export ENTREPRISE_API_TRACKING_RECIPIENT="your-siret"

# Add establishment data
npx tsx scripts/testing.ts entreprise add 49430870300052

This command:

1. Fetches real data from the Entreprise API
2. Anonymizes private/non-diffusible information using predefined personas
3. Saves the result as a JSON file in src/api/routes/entreprise.api.gouv.fr/etablissements/
4. Formats the JSON with Prettier

Available Mock Endpoints

Entreprise API (/entreprise.api.gouv.fr)

• GET /v3/insee/sirene/etablissements/{siret} - Establishment details
• GET /v3/infogreffe/rcs/unites_legales/{siren}/mandataires_sociaux - Company officers
• GET /etablissements/discover - Browse all available establishments (HTML interface)
• GET /mandataires_sociaux/discover - Browse all available company officers (HTML interface)
• Includes 80+ pre-populated establishments and company data
• Handles both public and anonymized private data

INSEE API (/api.insee.fr)

• GET /entreprises/sirene/V3/etablissements/{siret} - INSEE establishment data
• Compatible with INSEE Sirene API format

FranceConnect OIDC (/oidc.franceconnect.gouv.fr)

• GET /.well-known/openid-configuration - OIDC discovery endpoint
• GET /api/v2/logout - Logout page mock
• GET /api/v2/select - Identity provider selection mock
• Configurable issuer for testing different environments

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run dev:test

# Build the package
npm run build

Test Data Structure

Mock data is organized as:

src/api/routes/
├── entreprise.api.gouv.fr/
│   ├── etablissements/          # Establishment JSON files by SIRET
│   │   └── discover.page.tsx    # HTML browser for establishments
│   └── mandataires_sociaux/     # Company officers by SIREN
│       └── discover.page.tsx    # HTML browser for company officers
├── api.insee.fr/
│   └── etablissements/          # INSEE format establishment data
└── oidc.franceconnect.gouv.fr/  # OIDC mock responses

Each JSON file contains real API response structure with anonymized sensitive data when needed.

Discovery Interface

The testing server provides HTML interfaces to browse available test data:

• Establishments: Visit /entreprise.api.gouv.fr/etablissements/discover to see all available establishments with formatted company names and expandable JSON data https://identite-showcase.proconnect.gouv.fr/testing/entreprise.api.gouv.fr/etablissements/discover
• Company Officers: Visit /entreprise.api.gouv.fr/mandataires_sociaux/discover to browse all available company officers data https://identite-showcase.proconnect.gouv.fr/testing/entreprise.api.gouv.fr/mandataires_sociaux/discover