@starci/jest-preset 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2.2.0 - 2026-10-01
+
+- Fixed: in one `npm run test:e2e` every e2e file after the first failed to boot with "Cannot determine a GraphQL output type":
+  `@nestjs/graphql` keeps its type registry on the process global, the test world's globalSetup loads application code in jest's
+  main process, and jest-environment-node exposes the host process's globals to every file it runs there (or in a reused worker).
+  The integration, e2e and contract projects now run on the preset's world runner (`runner: WORLD_RUNNER`, `world-runner.cjs`):
+  every spec file in a fresh worker process, never in band (not even with `--runInBand` or one
+  test), so each file boots clean whatever framework keeps state on a global. The runner drives the stock jest-runner of the jest
+  that loads it (jest -> @jest/core -> jest-runner), one single-worker farm per file.
+- Changed: the world runner runs the files of the integration, e2e and contract projects ONE AT A TIME, enforced by the runner
+  (`--maxWorkers` is not honoured there): every file shares the run's data and the test world resets it when a file boots, so
+  two files at once would wipe each other's state. The project-level `maxWorkers: 1` is removed: it is a global jest option a
+  project config never applied (so e2e files used to run cores-1 at a time).
+- Known limitation (lifted in alpha.5): world files cannot run in parallel until each worker has its own data namespace (a
+  database schema, a Keycloak realm prefix, a Redis key prefix and its own fakes per worker).
+- Added: `WORLD_RUNNER` (the runner's resolved path) on the package root.
+
+## 2.1.1 - 2026-10-01
+
+- Fixed: a repository without its test world (`src/tests/world/global-setup.ts`) could not run its unit specs with the managed `jest.config.js`: jest validates every project's `globalSetup`, even under `--selectProjects unit`. The integration, e2e and contract projects are now declared only when the world exists.
+
 ## 2.1.0 - 2026-09-30
 
 - Added: the claim side of `recordingOutbox()`, so a claim-side consumer is specced with the kit double the `OUTBOX` token requires (`spec-infra-double-from-kit`) instead of `mock<Outbox>()`. `queueRecords(...records)` fills a backlog that `claimDue(params)` hands out in order (only the asked queues, at most `limit`, removed once claimed; an empty backlog is an empty claim, a record queued twice is a duplicate delivery), `failNext(operation, error)` makes the next `enqueue`, `claimDue`, `complete`, `retry` or `bury` reject once, and `claims`, `completed`, `retried`, `buried` and `backlog` expose what happened. `RecordingOutbox<M, R>` takes the claimed record type as a second parameter; `ClaimedRecord`, `ClaimParams`, `RetryParams`, `BuryParams` and `OutboxOperation` are exported from `./outbox`. `clear()` resets the claim side too. No breaking change.

package/README.md

@@ -14,8 +14,11 @@ module.exports = require("@starci/jest-preset").starciJestConfig()
 - **Four projects, one per test kind**: `unit` (`**/*.spec.ts`, which by the unit standard means one `<name>.service.spec.ts` beside each `*.service.ts`; `clearMocks`; the Outcome matchers are installed through `setupFilesAfterEnv`; ignores
   `src/tests/{world,integration,e2e,contract}/`), `integration` (`src/tests/integration/**/*.integration-spec.ts`), `e2e`
   (`src/tests/e2e/**/*.e2e-spec.ts`) and `contract` (`src/tests/contract/**/*.contract-spec.ts`). The last three compile against
-  `src/tests/tsconfig.json`, run one worker, and start the one test world through `globalSetup`/`globalTeardown`
-  (`src/tests/world/global-setup.ts`, `global-teardown.ts`); only the unit project has a `setupFilesAfterEnv`. The managed scripts select one
+  `src/tests/tsconfig.json`, start the one test world through `globalSetup`/`globalTeardown`
+  (`src/tests/world/global-setup.ts`, `global-teardown.ts`) and run on the world runner (`world-runner.cjs`, `WORLD_RUNNER`): every
+  spec file in a worker process of its own and never in band, so nothing the globalSetup or another file left on a process global
+  (a framework registry such as `@nestjs/graphql`'s type metadata) reaches the file; and ONE FILE AT A TIME whatever
+  `--maxWorkers` says, because every file shares the run's data (the test world resets it when a file boots). Only the unit project has a `setupFilesAfterEnv`. The managed scripts select one
   project each: `test`, `test:integration`, `test:e2e`, `test:contract`; a contract spec skips itself without sandbox config.
 - **The three path aliases** `@features/*`, `@modules/*`, `@tests/*` (`MODULE_NAME_MAPPER`), the same ones the managed `tsconfig.json` declares.
 - **ts-jest with `diagnostics: false`** in every project. `isolatedModules: true` comes from `@starci/tsconfig` (ts-jest 29.4 reads it

package/index.cjs

@@ -84,11 +84,20 @@ const underTests = (folder) => String.raw`[\\/]src[\\/]tests[\\/]` + folder + St
  * contract project is never part of `test` or `test:e2e`, and a contract spec skips itself without sandbox config. The
  * test tree compiles against `src/tests/tsconfig.json`, the nearest config of every file under `src/tests/`. The
  * integration, e2e and contract projects share the world's `global-setup.ts`/`global-teardown.ts` (`src/tests/world/`) and
- * run one worker; the unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
+ * run their spec files one at a time, each in a worker process of its own (`world-runner.cjs`; every file shares the
+ * run's data, so the runner never runs two at once); the unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
  * Coverage is collected from every `*.service.ts` only, with a per-file threshold of 100 on lines, branches, functions and
  * statements: the `test` script runs the unit project with `--coverage` and fails below it. It uses v8: istanbul instruments the helpers TypeScript emits (`__decorate`, `__param`, `__awaiter`, interop wrappers)
  * as thousands of branches no spec can cover, while v8 measures the real source.
  */
+/** The runner of the integration, e2e and contract projects: one fresh worker process per spec file. */
+const WORLD_RUNNER = require.resolve("./world-runner.cjs")
+
+/** True when the repository at `root` has the test world's global setup (`src/tests/world/global-setup.ts`). */
+function hasTestWorld(root) {
+  return require("node:fs").existsSync(require("node:path").join(root, "src", "tests", "world", "global-setup.ts"))
+}
+
 function starciJestConfig() {
   const shared = {
     preset: "ts-jest",
@@ -101,7 +110,9 @@ function starciJestConfig() {
     ...shared,
     transform: transform("src/tests/tsconfig.json"),
     displayName,
-    maxWorkers: 1,
+    // Every spec file in a process of its own (never in band): nothing one file or the globalSetup put on a process global
+    // (a framework registry such as @nestjs/graphql's type metadata) reaches another file. See world-runner.cjs.
+    runner: WORLD_RUNNER,
     testMatch: [`<rootDir>/src/tests/${displayName}/**/*.${suffix}.ts`],
     // The one test world: started once per run of a project that has a test to run, torn down after it.
     globalSetup: "<rootDir>/src/tests/world/global-setup.ts",
@@ -126,9 +137,10 @@ function starciJestConfig() {
         testMatch: ["**/*.spec.ts"],
         testPathIgnorePatterns: ["/node_modules/", ...TEST_KIND_FOLDERS.map(underTests)],
       },
-      suite("integration", "integration-spec"),
-      suite("e2e", "e2e-spec"),
-      suite("contract", "contract-spec"),
+      // The integration, e2e and contract projects exist only where the repository has its test world: jest validates
+      // every project's globalSetup even under --selectProjects unit, so a repository whose world is not written yet
+      // would otherwise fail to run its unit specs with the managed config.
+      ...(hasTestWorld(process.cwd()) ? [suite("integration", "integration-spec"), suite("e2e", "e2e-spec"), suite("contract", "contract-spec")] : []),
     ],
   }
 }
@@ -154,4 +166,5 @@ module.exports = {
   COVERAGE_EXCLUDES,
   COVERAGE_THRESHOLD,
   UNIT_COMPILER_OPTIONS,
+  WORLD_RUNNER,
 }

package/index.d.ts

@@ -19,4 +19,6 @@ export declare const COVERAGE_SOURCES: string[]
 export declare const COVERAGE_EXCLUDES: string[]
 /** The compiler options the unit project overlays on the repository tsconfig so per-file 100 coverage of a decorated service is reachable. */
 export declare const UNIT_COMPILER_OPTIONS: Readonly<{ isolatedModules: false; importHelpers: true }>
+/** The runner of the integration, e2e and contract projects (`world-runner.cjs`): every spec file in a worker process of its own. */
+export declare const WORLD_RUNNER: string
 export declare const COVERAGE_THRESHOLD: Readonly<{ lines: 100; branches: 100; functions: 100; statements: 100 }>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The StarCi jest config for Nest repositories (unit, integration, e2e and contract projects, ts-jest with diagnostics off, per-file 100 coverage of *.service.ts only) and the one shared unit-test double kit: typed mock<T>(), mockEntityManager(), fakeTransaction(), fakeCache(), fakeLock(), recordingOutbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "UNLICENSED",
   "private": false,

package/world-runner.cjs

@@ -0,0 +1,69 @@
+"use strict"
+
+/**
+ * The runner of the integration, e2e and contract projects: every spec file runs in a process of its own.
+ *
+ * Why: jest runs a file in a fresh vm context, but a context still reaches the globals of the process that hosts it, and
+ * jest-environment-node exposes every global the host process had when the environment loaded. The test world's globalSetup
+ * runs in jest's main process and loads application code there (the migrate step and its modules), so a framework that keeps
+ * its registry on a process global (`@nestjs/graphql` keeps `GqlTypeMetadataStorage` on `global`) leaks it into every file
+ * jest runs in that process; and a worker that runs several files carries whatever the first one left on its own global. In
+ * one `npm run test:e2e` the second file then fails to boot with "Cannot determine a GraphQL output type". Resetting the
+ * framework's storage would chase one framework at a time; a process per file isolates every one of them.
+ *
+ * How: the stock jest-runner, driven one file at a time with a single-worker farm (`maxWorkers: 1` per file), which forks a
+ * fresh child, runs the file there and ends the child. Never in band, even when jest would choose it (one worker, one test,
+ * `--runInBand`): the main process holds the globalSetup's state.
+ *
+ * ONE FILE AT A TIME, whatever `--maxWorkers` says: every file of a run shares the run's data (the test world resets the run's
+ * databases, realm users, Redis DB and fakes when a file boots), so a second file running beside the first would wipe what the
+ * first is using. The runner enforces it, so no flag or script can turn it off. Per-worker data namespaces are the known
+ * limitation that lifts it (see CHANGELOG 2.2.0).
+ */
+
+const { createRequire } = require("node:module")
+const path = require("node:path")
+
+/**
+ * The stock jest-runner of the jest that loads this preset: resolved through jest's own dependency chain
+ * (jest -> @jest/core -> jest-runner) from the repository root, so the runner always matches the running jest.
+ */
+function stockRunner(root = process.cwd()) {
+  const fromRoot = createRequire(path.join(root, "package.json"))
+  const fromJest = createRequire(fromRoot.resolve("jest/package.json"))
+  const fromCore = createRequire(fromJest.resolve("@jest/core"))
+  const loaded = fromCore("jest-runner")
+  return loaded.default ?? loaded
+}
+
+const StockRunner = stockRunner()
+
+class WorldRunner extends StockRunner {
+  #listeners = []
+
+  /** Jest subscribes before the run; the subscriptions are handed to the per-file runner of each file. */
+  on(eventName, listener) {
+    const entry = { eventName, listener }
+    this.#listeners.push(entry)
+    return () => {
+      this.#listeners = this.#listeners.filter((candidate) => candidate !== entry)
+    }
+  }
+
+  /** Runs the files one after another, each in a fresh worker process; `--maxWorkers` and `serial` (in band) are never honoured. */
+  async runTests(tests, watcher) {
+    const perFile = { ...this._globalConfig, maxWorkers: 1 }
+    for (const test of tests) {
+      if (watcher.isInterrupted()) return
+      const runner = new StockRunner(perFile, this._context)
+      const unsubscribe = this.#listeners.map(({ eventName, listener }) => runner.on(eventName, listener))
+      try {
+        await runner.runTests([test], watcher, { serial: false })
+      } finally {
+        for (const stop of unsubscribe) stop()
+      }
+    }
+  }
+}
+
+module.exports = WorldRunner