Jason/serenity framework refactor

[jasonmorais]

Summary by Sourcery

Refactor the verification and local dev infrastructure to use shared portless/worktree settings, deterministic per-worktree ports, and centralized Serenity task steps, while simplifying MongoDB seeding and adding Azurite to the test stack.

New Features:

• Introduce shared worktree-aware hostname and port utilities for portless development and testing, including per-worktree MongoDB and Azurite configuration.
• Add reusable Serenity TaskStep helper and shared header sign-in tasks/types for API, UI, and E2E tests.
• Add dedicated Azurite test server and API azurite startup script to support blob/queue/table storage in local and E2E environments.
• Add worktree-aware dev entrypoints for API, UI, docs, OAuth2 mock, and Mongo memory mock services, plus e2e-specific Vite/dev tooling and settings files.
• Add centralized MongoDB seed module that seeds deterministic end-user documents based on shared test actors.

Bug Fixes:

• Ensure OAuth2 mock portal discovery prefers process.env values so worktree overrides are honored and missing env vars are reported clearly.
• Fix MongoDB and Azurite port collisions between concurrent worktrees by deriving deterministic, non-overlapping port ranges from the worktree name.
• Improve robustness of portless and Azurite server startup/shutdown handling, including proper child exit forwarding and avoiding race conditions when processes exit before readiness.

Enhancements:

• Simplify MongoDBTestServer to always start its own in-memory replica set, accept richer config, and use the new shared seeding API with scenario reset support.
• Unify portless-based test servers (API, Vite, OAuth2) around shared app path, env, and dev-script utilities, and make E2E infrastructure start all required services (Mongo, Azurite, OAuth2, API, UIs) in coordinated phases.
• Refactor E2E and acceptance tasks from low-level Serenity interactions to higher-level Tasks using the shared TaskStep helper for community creation, OAuth2 login, and header sign-in flows.
• Centralize portless hostname and URL construction into shared settings modules for both runtime and test code, replacing scattered ad-hoc builders and local-settings dependencies.
• Modernize various build and tooling configurations, including switching archunit-tests to tsgo, updating dependency overrides, and tightening Sonar coverage exclusions for local-dev scripts.

Build:

• Update workspace and app package scripts to support worktree-specific dev and test flows, including dev:worktree and test:e2e:worktree commands and revised sync-local-settings behavior.
• Replace per-app dev-process-exit handlers with a shared local-dev utility and add shared Vite argument builder that drives e2e-aware dev modes.
• Add new E2E/local-dev configuration artifacts (.env.e2e, local-settings.e2e.json, turbo/pnpm/sonar adjustments) to align CI and local worktree test execution.

Documentation:

• Clarify the main README developer usage section and link wording for getting started with the project.

Tests:

• Adjust acceptance and E2E test infrastructure to use the new MongoDBTestServer API, shared seed data, portless settings, and consolidated header/OAuth2 login tasks, while disabling Cucumber parallelism to avoid proxy hostname contention.

[sourcery-ai]

Reviewer's Guide

Refactors verification test infrastructure to use a shared Mongo seeding pipeline and worktree‑aware portless/dev tooling, introduces Azurite as a managed test server, and standardises SerenityJS tasks and login flows across acceptance and E2E tests, along with supporting scripts and dependency overrides.

File-Level Changes

Change	Details	Files
Refactor MongoDB in-memory test server and seeding into reusable, context-based helpers.	MongoDBTestServer now always starts its own MongoMemoryReplicaSet using a MongoMemoryReplicaSetConfig and receives a connectionString from startMongoMemoryReplicaSet Database seeding moved to a shared seedDatabase(MongoDBSeedContext) function with typed EndUserSeedDocument seed data and stable END_USER_IDS MongoDBTestServer.start accepts options for dbName, port, replSetName, binaryVersion, attachMongoose, and seedData, and can attach Mongoose lazily via attachMongoose Added resetForScenario that clears all collections via clearDatabase and re-runs the configured seed function Removed external reachability/seeding helpers and apiSettings coupling from acceptance/e2e infrastructure; acceptance GraphQL tests now call start({ attachMongoose: true })	packages/ocom-verification/verification-shared/src/servers/test-mongodb-server.ts packages/cellix/server-mongodb-memory-mock-seedwork/src/index.ts packages/ocom-verification/acceptance-api/src/shared/support/shared-infrastructure.ts packages/ocom-verification/verification-shared/src/test-data/seed/* packages/ocom-verification/verification-shared/src/test-data/index.ts packages/ocom-verification/verification-shared/src/test-data/seed/end-users.ts
Introduce worktree-scoped local-dev infrastructure (portless hostnames, per-worktree ports, Azurite server) and wire it into dev scripts and E2E harness.	Added scripts to compute worktree-specific ports for Mongo and Azurite and to derive portless hostnames from .env files; these are used by api, UI apps, and tests Added TestAzuriteServer and worktree port helpers for E2E tests, and updated ensureE2EServers/stopAll to manage Azurite lifecycle API dev startup now injects worktree-specific OIDC, Mongo, and Azurite settings into func child processes when WORKTREE_NAME is set; Azurite is started via start-azurite.mjs UI dev for community, staff, docs, OAuth2 mock, and Mongo memory mock now goes through new start-dev/start-mongo entrypoints that apply worktree hostnames and Vite args when WORKTREE_NAME/E2E are set E2E test environment bootstraps the portless proxy, loads .env.e2e defaults for portals, exposes buildPortlessUrl/getHostnames, and narrows Mongo connection-string responsibilities to setMongoConnectionString/getMongoConnectionString	scripts/local-dev/worktree-ports.mjs scripts/local-dev/portless-hostnames.mjs scripts/local-dev/dev-process-exit.mjs scripts/local-dev/vite-dev-args.mjs apps/api/start-dev.mjs apps/api/start-azurite.mjs apps/api/scripts/sync-local-settings.mjs apps/api/local-settings.e2e.json apps/server-mongodb-memory-mock/start-mongo.mjs apps/ui-community/start-dev.mjs apps/ui-staff/start-dev.mjs apps/server-oauth2-mock/start-dev.mjs apps/docs/start-dev.mjs packages/ocom-verification/e2e-tests/src/shared/support/servers/test-azurite-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/worktree-ports.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-environment.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-api-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-community-vite-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-staff-vite-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/resolve-portless.ts packages/ocom-verification/e2e-tests/src/shared/support/shared-infrastructure.ts packages/ocom-verification/verification-shared/src/settings/portless-settings.ts packages/ocom-verification/verification-shared/src/settings/index.ts package.json apps/api/package.json apps/server-mongodb-memory-mock/package.json apps/ui-community/package.json apps/ui-staff/package.json apps/docs/package.json
Standardise SerenityJS abstractions by introducing TaskStep and migrating interactions/tasks to Task/TaskStep across acceptance and E2E flows.	Added a reusable TaskStep class in verification-shared/serenity and re-exported it for consumers Rewrote UI and E2E CreateCommunity flows, OAuth2Login, and header sign-in steps to use Task.where + TaskStep instead of Interaction.where Introduced shared header note types (HeaderE2ENotes/HeaderApiNotes) and encapsulated header sign-in logic for acceptance and E2E into ClickHeaderSignIn tasks Updated OAuth2 login helper to reflect the new mock-auth behavior (explicit login form using actors.CommunityOwner.email) and to rely on isPostAuthUrl for post-login URL checks	packages/ocom-verification/verification-shared/src/serenity/task-step.ts packages/ocom-verification/verification-shared/src/serenity/index.ts packages/ocom-verification/acceptance-ui/src/contexts/community/tasks/create-community.ts packages/ocom-verification/e2e-tests/src/contexts/community/tasks/create-community.ts packages/ocom-verification/e2e-tests/src/shared/support/oauth2-login.ts packages/ocom-verification/e2e-tests/src/contexts/authentication/tasks/click-header-sign-in.ts packages/ocom-verification/acceptance-ui/src/contexts/authentication/tasks/click-header-sign-in.ts packages/ocom-verification/acceptance-api/src/contexts/authentication/tasks/click-header-sign-in.ts packages/ocom-verification/e2e-tests/src/contexts/authentication/abilities/header-types.ts packages/ocom-verification/acceptance-api/src/contexts/authentication/abilities/header-types.ts packages/ocom-verification/e2e-tests/src/contexts/authentication/step-definitions/header-login.steps.ts packages/ocom-verification/acceptance-api/src/contexts/authentication/step-definitions/header-login.steps.ts
Tighten portless-based E2E server orchestration and environment handling.	PortlessServer now derives its executable via getPortlessPath, uses a shared spawnEnv helper that strips NODE_OPTIONS, exposes startupTimeoutMs from timeout settings, and ensures exit events don’t double-report if the ready marker fired TestApiServer, TestCommunityViteServer, TestStaffViteServer, and TestOAuth2Server now use appPaths for cwd, getPortlessDevScript to choose dev vs dev:worktree scripts, and e2eEnv for consistent E2E environment vars E2E cucumber configuration forces serial execution (parallel: 0) to avoid contention on shared portless proxy and worktree ports	packages/ocom-verification/e2e-tests/src/shared/support/servers/portless-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-api-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-community-vite-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-staff-vite-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/test-oauth2-server.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/app-paths.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/dev-script.ts packages/ocom-verification/e2e-tests/src/shared/support/servers/child-process-env.ts packages/ocom-verification/e2e-tests/cucumber.js
Adjust workspace tooling, dependencies, and coverage settings to support the new dev/test model.	Updated pnpm workspace overrides for axios, qs, brace-expansion, ws, uuid, and @opentelemetry/exporter-prometheus; removed root-level azurite dev dependency and added it to apps/api only Tweaked root scripts for dev, dev:worktree, proxy management, test:e2e:worktree, test:acceptance, and verify to align with worktree-aware dev and E2E workflows Switched cellix/archunit-tests build/watch scripts from tsc to tsgo and added Serenity core as a verification-shared dependency Expanded Sonar coverage exclusions to include scripts/local-dev and related infra; minor README wording cleanup	pnpm-workspace.yaml package.json packages/cellix/archunit-tests/package.json packages/ocom-verification/verification-shared/package.json sonar-project.properties readme.md apps/api/package.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @jasonmorais, your pull request is larger than the review limit of 150000 diff characters