declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/practices/tests-any/best-practice/package.json.shell-flags.declapract.integration.test.ts

@@ -0,0 +1,129 @@
+import { execSync } from 'child_process';
+
+/**
+ * Tests the shell flag expressions used in package.json test commands.
+ *
+ * These tests verify that env vars like RESNAP and THOROUGH produce
+ * the correct flags when passed to jest via the package.json commands.
+ *
+ * We use a stand-in jest function that echoes the arguments it receives,
+ * so we can verify what flags would actually be passed.
+ *
+ * .why integration = this drives a real `bash -c` via execSync — a child-process
+ *   boundary. per rule.forbid.unit.remote-boundaries a `.test.ts` (unit) may not
+ *   cross a process boundary, so the shell-flag behavior is proven at the
+ *   integration grain, where a real shell is the point of the test.
+ */
+describe('package.json shell flag expressions', () => {
+  /**
+   * Evaluates a shell command with given env vars and returns the arguments
+   * that would be passed to jest (everything after the config flag).
+   */
+  const getJestFlags = (
+    command: string,
+    env: Record<string, string | undefined>,
+  ): string[] => {
+    // .note = deliberate mutation — cleanEnv is built up across two scoped local loops (base env
+    //         minus the flag vars, then the test overlay); a single-threaded local zone
+    //         (rule.require.immutable-vars sanctions in-place mutation with this note).
+    const cleanEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (!['CI', 'THOROUGH', 'RESNAP'].includes(key) && value !== undefined) {
+        cleanEnv[key] = value;
+      }
+    }
+    // Overlay the test env vars (undefined means unset)
+    for (const [key, value] of Object.entries(env)) {
+      if (value !== undefined) {
+        cleanEnv[key] = value;
+      }
+    }
+
+    // Run the command with jest replaced by echo to capture args
+    const result = execSync(
+      `bash -c 'jest() { echo "JEST_ARGS: $*"; }; ${command}'`,
+      {
+        env: cleanEnv,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // bound the call so a stuck shell fails fast rather than hangs the suite;
+        // the command is a trivial echo, so 5s is generous
+        timeout: 5000,
+      },
+    );
+
+    // Extract the jest args from output
+    const match = result.match(/JEST_ARGS: (.*)/);
+    if (!match) return [];
+    return match[1].split(/\s+/).filter(Boolean);
+  };
+
+  // The test:unit command from package.json best-practice
+  const testUnitCommand = `set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n "\${CI:-}" ] && echo '--ci') $([ "\${THOROUGH:-}" != "true" ] && echo '--changedSince=main') $([ "\${RESNAP:-}" = "true" ] && echo '--updateSnapshot')`;
+
+  describe('RESNAP flag', () => {
+    it('should pass --updateSnapshot when RESNAP=true', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: 'true' });
+      expect(flags).toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP is unset', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP=false', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: 'false' });
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP is empty string', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: '' });
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+
+    it('should not pass --updateSnapshot when RESNAP=0', () => {
+      const flags = getJestFlags(testUnitCommand, { RESNAP: '0' });
+      expect(flags).not.toContain('--updateSnapshot');
+    });
+  });
+
+  describe('THOROUGH flag', () => {
+    it('should pass --changedSince=main when THOROUGH is unset (run only changed)', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).toContain('--changedSince=main');
+    });
+
+    it('should pass --changedSince=main when THOROUGH=false', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: 'false' });
+      expect(flags).toContain('--changedSince=main');
+    });
+
+    it('should pass --changedSince=main when THOROUGH is empty string', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: '' });
+      expect(flags).toContain('--changedSince=main');
+    });
+
+    it('should not pass --changedSince=main when THOROUGH=true (run all tests)', () => {
+      const flags = getJestFlags(testUnitCommand, { THOROUGH: 'true' });
+      expect(flags).not.toContain('--changedSince=main');
+    });
+  });
+
+  describe('CI flag', () => {
+    it('should pass --ci when CI=true', () => {
+      const flags = getJestFlags(testUnitCommand, { CI: 'true' });
+      expect(flags).toContain('--ci');
+    });
+
+    it('should pass --ci when CI=1', () => {
+      const flags = getJestFlags(testUnitCommand, { CI: '1' });
+      expect(flags).toContain('--ci');
+    });
+
+    it('should not pass --ci when CI is unset', () => {
+      const flags = getJestFlags(testUnitCommand, {});
+      expect(flags).not.toContain('--ci');
+    });
+  });
+});

package/dist/practices/tests-any/best-practice/src/<star><star>/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/practices/tests-any/best-practice/src/<star><star>/<star>.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/practices/tests-expo/.declapract.integration.test.ts

@@ -0,0 +1,134 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full usecase evaluation)
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the expo test-toolchain triad (typescript-expo + tests-expo,
+ *         paired with typescript-any + tests-any).
+ * .why  = the shared cicd-common `.test.yml` runs `npm run build`, `test:types`,
+ *         `test:unit`, `test:integration`, `test:acceptance` unconditionally. before the
+ *         triad, the expo usecase carried none of those commands/configs, so a fresh expo
+ *         consumer's CI aborted at `npm run build`. this proves `declapract fix` on the
+ *         expo usecase EMITS the whole stack — the expo build (`expo export`), the
+ *         typecheck, and the jest-expo unit/integration/acceptance configs — so CI runs.
+ */
+describe('expo test-toolchain triad — pipeline', () => {
+  given('[case1] a fresh expo repo on the app-react-native-expo usecase', () => {
+    const tempDir = genTempDir({
+      slug: 'expo-toolchain',
+      clone: './src/practices/tests-expo/.test/assets/repo-expo-greenfield',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo-toolchain/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) =>
+      fs.readFile(path.join(tempDir, rel), 'utf-8').catch(() => null);
+
+    // useBeforeAll RETURNS the captured state (no in-place mutation of a shared const)
+    const state = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+
+      // apply the whole expo usecase (all four triad practices), thrice.
+      // .why = declapract adds a new minVersion dep to an already-present package.json as
+      //        its raw `@declapract{check.minVersion(..)}` expression on the first pass,
+      //        then resolves it to the concrete version on the next pass (a net-new file
+      //        is resolved immediately). so package.json settles at apply-2, and apply-3
+      //        is the true fixed point. a net-new file (tsconfig, jest configs) is a fixed
+      //        point from apply-1.
+      await executeApply({ config });
+      const tsconfigAfter1 = await read('tsconfig.json');
+      const jestUnitAfter1 = await read('jest.unit.config.ts');
+      const jestIntegrationAfter1 = await read('jest.integration.config.ts');
+      const jestAcceptanceAfter1 = await read('jest.acceptance.config.ts');
+
+      await executeApply({ config });
+      const pkgSettled = await read('package.json'); // resolved versions
+      const tsconfigAfter2 = await read('tsconfig.json');
+      const jestUnitAfter2 = await read('jest.unit.config.ts');
+
+      await executeApply({ config });
+      const pkgAfter3 = await read('package.json'); // must equal pkgSettled
+
+      return {
+        pkgSettled,
+        pkgAfter3,
+        tsconfigAfter1,
+        jestUnitAfter1,
+        jestIntegrationAfter1,
+        jestAcceptanceAfter1,
+        tsconfigAfter2,
+        jestUnitAfter2,
+      };
+    }, 170_000);
+
+    when('[t0] declapract fix emits the toolchain', () => {
+      then('package.json carries every command cicd-common runs', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        // the exact commands cicd-common/.test.yml invokes
+        expect(pkg.scripts.build).toBeDefined();
+        expect(pkg.scripts['test:types']).toEqual('tsc -p ./tsconfig.json --noEmit');
+        expect(pkg.scripts['test:unit']).toContain('jest -c ./jest.unit.config.ts');
+        expect(pkg.scripts['test:integration']).toContain(
+          'jest -c ./jest.integration.config.ts',
+        );
+        expect(pkg.scripts['test:acceptance']).toContain(
+          'jest -c ./jest.acceptance.config.ts',
+        );
+      });
+
+      then('the build command is the expo web export, not tsc', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        // `typescript-expo` is the SOLE declarer of `build:web` — `cicd-app-react-native-expo`
+        // no longer re-declares it, so there is no second CONTAINS declarer to oscillate
+        // with (the single-source shape this repo's convergence/oscillation lesson prefers).
+        expect(pkg.scripts['build:web']).toEqual('npx expo export --platform web');
+        expect(pkg.scripts.build).toEqual('npm run build:web');
+      });
+
+      then('package.json carries the typescript + jest-expo deps at concrete versions', () => {
+        const pkg = JSON.parse(state.pkgSettled!);
+        expect(pkg.devDependencies.typescript).toEqual('5.4.5');
+        expect(pkg.devDependencies['jest-expo']).toEqual('54.0.0');
+        expect(pkg.devDependencies['react-test-renderer']).toEqual('19.0.0');
+      });
+
+      then('tsconfig.json extends the expo base, not the node base', () => {
+        const tsconfig = JSON.parse(state.tsconfigAfter1!);
+        expect(tsconfig.extends).toEqual('expo/tsconfig.base');
+      });
+
+      then('the jest configs use the jest-expo preset', () => {
+        expect(state.jestUnitAfter1).toContain("preset: 'jest-expo'");
+        expect(state.jestIntegrationAfter1).toContain("preset: 'jest-expo/web'");
+        expect(state.jestAcceptanceAfter1).toContain("preset: 'jest-expo/web'");
+      });
+
+      then('the emitted package.json + tsconfig + jest.unit match snapshot', () => {
+        expect(state.pkgSettled).toMatchSnapshot('package.json — after fix');
+        expect(state.tsconfigAfter1).toMatchSnapshot('tsconfig.json — after fix');
+        expect(state.jestUnitAfter1).toMatchSnapshot('jest.unit.config.ts — after fix');
+      });
+    });
+
+    when('[t1] declapract fix is re-applied', () => {
+      then('package.json is a fixed point once settled', () => {
+        expect(state.pkgAfter3).toEqual(state.pkgSettled);
+      });
+
+      then('tsconfig.json is a fixed point', () => {
+        expect(state.tsconfigAfter2).toEqual(state.tsconfigAfter1);
+      });
+
+      then('jest.unit.config.ts is a fixed point', () => {
+        expect(state.jestUnitAfter2).toEqual(state.jestUnitAfter1);
+      });
+    });
+  });
+});

package/dist/practices/tests-expo/.test/assets/repo-expo-greenfield/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test to test/assets/expo-toolchain/declarations
+# .why  = a fresh expo repo, used to prove the typescript + tests triads emit the expo
+#         build/typecheck/jest stack that cicd-common's .test.yml runs.
+# .note = no variables — the four triad practices reference only @declapract{check.minVersion}.
+declarations: 'declarations/declapract.declare.yml'
+useCase: app-react-native-expo

package/dist/practices/tests-expo/.test/assets/repo-expo-greenfield/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-expo-app",
+  "version": "1.0.0"
+}

package/dist/practices/tests-expo/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,112 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: jest.unit.config.ts — after fix 1`] = `
+"/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo wires up babel-preset-expo (metro's transform) + react-native module
+  // resolution (platform suffixes, haste). this is what lets tests that reach the
+  // expo/react-native boundary load, where a plain node preset cannot.
+  preset: 'jest-expo',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/unit.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // the jest-expo preset's transformIgnorePatterns assume a hoisted (flat) node_modules.
+  // pnpm's \`.pnpm/\`-nested store ships react-native/expo as untranspiled ESM one layer
+  // deeper, so add a \`.pnpm/\` branch that still transforms those families. a repo that
+  // pulls other untranspiled-ESM packages (e.g. a native storage lib) appends its own
+  // package names to BOTH branches.
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: [
+    // note: order matters
+    '**/*.test.{ts,tsx}',
+    '!**/*.acceptance.test.{ts,tsx}',
+    '!**/*.integration.test.{ts,tsx}',
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  setupFilesAfterEnv: ['./jest.unit.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;
+"
+`;
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: package.json — after fix 1`] = `
+"{
+  "name": "test-expo-app",
+  "version": "1.0.0",
+  "devDependencies": {
+    "@jest/globals": "30.2.0",
+    "@types/jest": "30.0.0",
+    "jest": "30.2.0",
+    "esbuild-register": "3.6.0",
+    "test-fns": "1.15.8",
+    "tsx": "4.20.6",
+    "jest-expo": "54.0.0",
+    "@babel/core": "7.24.0",
+    "babel-preset-expo": "12.0.0",
+    "react-test-renderer": "19.0.0",
+    "isomorphic-fetch": "3.0.0",
+    "typescript": "5.4.5"
+  },
+  "scripts": {
+    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \\"\${CI:-}\\" ] && echo '--ci') $([ \\"\${THOROUGH:-}\\" != \\"true\\" ] && echo '--changedSince=main') $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \\"\${CI:-}\\" ] && echo '--ci') $([ \\"\${THOROUGH:-}\\" != \\"true\\" ] && echo '--changedSince=main') $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test": "set -eu && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \\"\${CI:-}\\" ] && echo '--ci') $([ \\"\${RESNAP:-}\\" = \\"true\\" ] && echo '--updateSnapshot')",
+    "test:types": "tsc -p ./tsconfig.json --noEmit",
+    "build": "npm run build:web",
+    "build:web": "npx expo export --platform web"
+  }
+}
+"
+`;
+
+exports[`expo test-toolchain triad — pipeline given: [case1] a fresh expo repo on the app-react-native-expo usecase when: [t0] declapract fix emits the toolchain then: the emitted package.json + tsconfig + jest.unit match snapshot: tsconfig.json — after fix 1`] = `
+"{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": [
+        "src/*"
+      ],
+      "@assets/*": [
+        "assets/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}
+"
+`;

package/dist/practices/tests-expo/bad-practices/inline-jest-config/.declapract.readme.md

@@ -0,0 +1,22 @@
+# bad-practice: inline-jest-config
+
+## .what
+
+a top-level `jest` key in a consumer's `package.json`.
+
+## .why it is bad
+
+an expo app that migrated to jest-expo by hand often carries the jest-expo preset INLINE in
+`package.json` AND a `jest.*.config.ts` file at the same time — a dual source of truth. `tests-expo`
+declares the jest config as its own `jest.*.config.ts` files (the go-forward home), so an inline
+block is redundant and the two configs can fight over the same run.
+
+## .the fix
+
+drop the inline `jest` key. the `jest.*.config.ts` files that `tests-expo` drops are the one home,
+so no jest settings are lost — they move to (or already live in) the config files.
+
+## .see also
+
+- `src/practices/tests-expo/best-practice/jest.*.config.ts` — the go-forward jest config home
+- `rule.require.idempotent-fixes` — the twice-applied clamp this fix owes

package/dist/practices/tests-expo/bad-practices/inline-jest-config/package.json.declapract.ts

@@ -0,0 +1,36 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = removes a top-level `jest` key from a consumer's package.json.
+ * .why  = an expo app that migrated by hand often carries a jest-expo preset INLINE in
+ *         package.json AND a jest.*.config.ts file at the same time — a dual source of
+ *         truth. tests-expo declares the jest config as its own jest.*.config.ts files
+ *         (the go-forward home), so the inline block is redundant and must be dropped, or
+ *         two configs fight over the same run. this is a bad-practice: `check` DETECTS the
+ *         inline key (returns) and `fix` drops it, so the jest.*.config.ts files stay the
+ *         one home.
+ */
+export const check: FileCheckFunction = (contents) => {
+  // no package.json → no key to detect, skip
+  if (!contents) throw new Error('does not match bad practice');
+
+  // an inline `jest` key is the dual-source hazard → detected
+  const packageJSON = JSON.parse(contents);
+  if (packageJSON.jest !== undefined) return;
+
+  // no inline `jest` key → not the bad practice, skip
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  // drop the inline `jest` key; the jest.*.config.ts files are the one home.
+  // destructure to EXCLUDE the key rather than delete-in-place (rule.require.immutable-vars)
+  const packageJSON = JSON.parse(contents);
+  const { jest: _jest, ...updatedPackageJSON } = packageJSON;
+
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/practices/tests-expo/best-practice/jest.acceptance.config.ts

@@ -0,0 +1,43 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo/web = jsdom + react-native-web, so acceptance tests exercise the web build
+  // surface. (a repo that prefers a device/simulator acceptance harness, e.g. playwright
+  // against the exported web app, swaps this out — the cicd-common shard runner reads the
+  // jest config named here.)
+  preset: 'jest-expo/web',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/acceptance.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // pnpm-nested react-native/expo ESM must still transform (see jest.unit.config.ts).
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: ['**/*.acceptance.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/practices/tests-expo/best-practice/jest.acceptance.env.ts

@@ -0,0 +1,15 @@
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+jest.setTimeout(90000); // since the web build surface is exercised end-to-end
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;

package/dist/practices/tests-expo/best-practice/jest.config.ts

@@ -0,0 +1,7 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import config from './jest.unit.config';
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/practices/tests-expo/best-practice/jest.integration.config.ts

@@ -0,0 +1,42 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo/web = a single jsdom project with react-native-web + expo module
+  // resolution, so integration tests that reach the expo/react-native boundary load
+  // under jsdom.
+  preset: 'jest-expo/web',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/integration.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // pnpm-nested react-native/expo ESM must still transform (see jest.unit.config.ts).
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: ['**/*.integration.test.{ts,tsx}', '!**/.agent/.cache/**', '!**/.yalc/**'],
+  setupFilesAfterEnv: ['./jest.integration.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/practices/tests-expo/best-practice/jest.integration.env.ts

@@ -0,0 +1,22 @@
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+
+// provide fetch for the test env, like the browser/native runtime does
+import 'isomorphic-fetch';
+
+jest.setTimeout(90000); // since downstream apis are reached
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+// react-test-renderer 19 requires this flag to run act() cleanly
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+/**
+ * sanity check that integration tests only run in the 'test' environment
+ * .why = prevent prod state pollution + financial mutations from test data
+ */
+if (process.env.NODE_ENV !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new Error(`integration-test does not target stage 'test'`);

package/dist/practices/tests-expo/best-practice/jest.unit.config.ts

@@ -0,0 +1,53 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import type { Config } from 'jest';
+
+// ensure tests run in utc, like they will on cicd and on server; https://stackoverflow.com/a/56277249/15593329
+process.env.TZ = 'UTC';
+
+// ensure tests run like on local machines, so snapshots are equal on local && cicd
+process.env.FORCE_COLOR = 'true';
+
+// https://jestjs.io/docs/configuration
+const config: Config = {
+  // jest-expo wires up babel-preset-expo (metro's transform) + react-native module
+  // resolution (platform suffixes, haste). this is what lets tests that reach the
+  // expo/react-native boundary load, where a plain node preset cannot.
+  preset: 'jest-expo',
+
+  verbose: true,
+  reporters: [
+    ['default', { summaryThreshold: 0 }], // ensure we always get a failure summary at the bottom, to avoid the hunt
+    ['test-fns/slowtest.reporter.jest', { slow: '10s', output: '.log/slowtest/unit.report.json' }],
+  ],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@src/(.*)$': '<rootDir>/src/$1',
+    '^@assets/(.*)$': '<rootDir>/assets/$1',
+  },
+  // the jest-expo preset's transformIgnorePatterns assume a hoisted (flat) node_modules.
+  // pnpm's `.pnpm/`-nested store ships react-native/expo as untranspiled ESM one layer
+  // deeper, so add a `.pnpm/` branch that still transforms those families. a repo that
+  // pulls other untranspiled-ESM packages (e.g. a native storage lib) appends its own
+  // package names to BOTH branches.
+  transformIgnorePatterns: [
+    'node_modules/.pnpm/(?!.*(react-native|@react-native|expo|@expo|@unimodules|unimodules|@react-navigation|react-navigation|sentry-expo|native-base|@sentry))',
+    'node_modules/(?!.pnpm)(?!(jest-)?react-native|@react-native(-community)?|expo(nent)?|@expo(nent)?|react-navigation|@react-navigation|@unimodules|unimodules|sentry-expo|native-base|@sentry)',
+  ],
+  testMatch: [
+    // note: order matters
+    '**/*.test.{ts,tsx}',
+    '!**/*.acceptance.test.{ts,tsx}',
+    '!**/*.integration.test.{ts,tsx}',
+    '!**/.agent/.cache/**',
+    '!**/.yalc/**',
+  ],
+  setupFilesAfterEnv: ['./jest.unit.env.ts'],
+
+  // use 50% of threads to leave headroom for other processes
+  maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
+};
+
+// eslint-disable-next-line import/no-default-export
+export default config;