Skip to content

docs(adr): ADR-064 test layers follow the hexagon, repository contract tests per port - #711

Open
seanspeaks wants to merge 1 commit into
nextfrom
docs/adr-repository-contract-tests
Open

seanspeaks wants to merge 1 commit into
nextfrom
docs/adr-repository-contract-tests

Conversation

@seanspeaks

@seanspeaks seanspeaks commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Proposes ADR-064: Frigg's tests follow the same layers as the hexagonal architecture.

  • Use cases are tested against in-memory fake repositories, with no database.
  • Handlers and routers are tested against mocked use cases.
  • Each repository port gets one shared contract suite. It runs against every adapter (MongoDB and PostgreSQL; DocumentDB is covered by MongoDB in CI, plus a documented manual run against real DocumentDB before releases) on real databases, in the separate test:db CI job, with the encryption extension exercised.
  • Unit test setup never starts a global database.

Why

Core's jest setup used to start an in-memory MongoDB for every run. Almost nothing used it, and when it failed on Ubuntu 24.04 (OpenSSL 1.1) the whole core suite stopped running. Today's adapter tests mock Prisma, so they can't catch behaviour that differs between databases. #710 removes the global database and adds the *.db.test.js / test:db path. This ADR sets the target the 14 repository ports migrate to.

Migration order

credential, integration, module (entities), user and token first, because encryption and tenancy live there. Then the remaining nine ports. A tracking issue follows.

Test plan

  • Docs only: ADR file, README index row and adrs.json entry.

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only ADR and index updates; no runtime or test code changes in this PR.

Overview
Adds ADR-064 (Proposed), which defines how Frigg core tests should align with hexagonal boundaries: use cases on in-memory fakes, handlers on mocked use cases, and one shared contract suite per repository port run against MongoDB/PostgreSQL (and DocumentDB via Mongo in CI) as *.db.test.js / npm run test:db, including encryption checks and no global DB in unit globalSetup. It documents motivation (CI outage from global MongoMemoryServer, Prisma mocks missing cross-DB bugs), generalizes existing parity/encryption suites, lists a 14-port migration order, and ties the target to #710.

The ADR register is updated in docs/architecture-decisions/README.md and website/roadmap/data/adrs.json (count 32, new entry for 064).

Reviewed by Cursor Bugbot for commit f8b6445. Bugbot is set up for automated code reviews on this repo. Configure here.

📦 Published PR as canary version: 2.0.0--canary.711.f8b6445.0

✨ Test out this PR locally via:

npm install @friggframework/admin-scripts@2.0.0--canary.711.f8b6445.0
npm install @friggframework/core@2.0.0--canary.711.f8b6445.0
npm install @friggframework/devtools@2.0.0--canary.711.f8b6445.0
npm install @friggframework/eslint-config@2.0.0--canary.711.f8b6445.0
npm install @friggframework/prettier-config@2.0.0--canary.711.f8b6445.0
npm install @friggframework/schemas@2.0.0--canary.711.f8b6445.0
npm install @friggframework/serverless-plugin@2.0.0--canary.711.f8b6445.0
npm install @friggframework/test@2.0.0--canary.711.f8b6445.0
npm install @friggframework/ui@2.0.0--canary.711.f8b6445.0
# or 
yarn add @friggframework/admin-scripts@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/core@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/devtools@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/eslint-config@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/prettier-config@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/schemas@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/serverless-plugin@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/test@2.0.0--canary.711.f8b6445.0
yarn add @friggframework/ui@2.0.0--canary.711.f8b6445.0

…t tests per port

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
@seanspeaks seanspeaks added release Create a release when this pr is merged prerelease This change is available in a prerelease. labels Oct 24, 2026

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

@netlify

netlify Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for friggframework-org ready!

Name Link
🔨 Latest commit f8b6445
🔍 Latest deploy log https://app.netlify.com/projects/friggframework-org/deploys/6adc2debdd0906e298e55f15
😎 Deploy Preview https://deploy-preview-711--friggframework-org.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

prerelease This change is available in a prerelease. release Create a release when this pr is merged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant