Add react boundary tests

Author: tanem

.github/copilot-instructions.md

@@ -60,6 +60,32 @@ Managed by Renovate (`config:js-lib` preset):
 - **100% code coverage** required across all build formats
 - Always run `npm test` after changes; use `npm run test:src` for quick
   source-only feedback during development
+- Use `npm run test:react` for the full React version matrix independently.
+  It also runs as part of `npm test` (via the `test:*` glob).
+
+### React version matrix
+
+We test boundary versions only: first and last minor of each supported
+major. See `test/react/` for current versions.
+
+Current boundaries: 16.14, 17.0, 18.0, 18.3, 19.0.
+
+React 16.14 is the practical lower bound. Hooks require 16.8 and
+`@testing-library/react-hooks` requires 16.9.
+
+When adding a new boundary:
+
+1. Add `test/react/<version>/package.json` with correct `react`,
+   `react-dom`, and `@testing-library/react` (12.x for React 16–17,
+   16.x for React 18+). React 16–17 also need
+   `@testing-library/react-hooks` (8.x) and `react-test-renderer`.
+2. Replace the previous "latest minor" for that major.
+3. Verify with a single-version run before the full matrix:
+   ```bash
+   cd test/react/<version> && npm i --no-package-lock --quiet --no-progress
+   REACT_VERSION=<version> npx jest --config ./scripts/jest/config.src.js --coverage false
+   ```
+4. Update the boundary list above.
 
 ## Examples
 

package.json

@@ -20,6 +20,7 @@
     "clean:compiled": "shx rm -rf compiled",
     "clean:coverage": "shx rm -rf coverage",
     "clean:dist": "shx rm -rf dist",
+    "clean:react": "node ./scripts/clean-react.js",
     "compile": "tsc -p tsconfig.base.json",
     "format": "npm run lint -- --fix && prettier --write \"**/*.{js,ts,tsx}\"",
     "lint": "eslint .",
@@ -30,6 +31,7 @@
     "test:cjs": "jest --config ./scripts/jest/config.cjs.js",
     "test:cjsprod": "jest --config ./scripts/jest/config.cjsprod.js",
     "test:es": "jest --config ./scripts/jest/config.es.js",
+    "test:react": "node ./scripts/test-react.js",
     "test:src": "jest --config ./scripts/jest/config.src.js",
     "test:umd": "jest --config ./scripts/jest/config.umd.js",
     "test:umdprod": "jest --config ./scripts/jest/config.umdprod.js",

scripts/clean-react.js

@@ -0,0 +1,25 @@
+// Cleans node_modules from each test/react/<version> directory while preserving
+// the package.json file.
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const reactDir = path.join(process.cwd(), 'test', 'react')
+
+fs.readdirSync(reactDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .forEach((entry) => {
+    const dir = path.join(reactDir, entry.name)
+    const pkgJsonPath = path.join(dir, 'package.json')
+
+    if (!fs.existsSync(pkgJsonPath)) {
+      return
+    }
+
+    // Preserve package.json by copying to a temporary location.
+    const tmpPath = path.join(os.tmpdir(), `${entry.name}-package.json`)
+    fs.copyFileSync(pkgJsonPath, tmpPath)
+    fs.rmSync(dir, { force: true, recursive: true })
+    fs.mkdirSync(dir, { recursive: true })
+    fs.copyFileSync(tmpPath, pkgJsonPath)
+  })

scripts/jest/config.src.js

@@ -1,10 +1,74 @@
+const path = require('path')
+
+// When REACT_VERSION is set (e.g. "18.0"), resolve react, react-dom and
+// @testing-library/react from the matching test/react/<version> directory so
+// the test suite runs against that specific React version.
+const generateReactVersionMappings = (reactVersion) => {
+  if (!reactVersion) {
+    return {}
+  }
+
+  const testDir = path.join(process.cwd(), 'test', 'react', reactVersion)
+  const [major] = reactVersion.split('.').map(Number)
+
+  const reactDir = path.dirname(
+    require.resolve('react/package.json', { paths: [testDir] }),
+  )
+  const reactDomDir = path.dirname(
+    require.resolve('react-dom/package.json', { paths: [testDir] }),
+  )
+
+  const mappings = {
+    '^react$': require.resolve('react', { paths: [testDir] }),
+    '^react-dom$': require.resolve('react-dom', { paths: [testDir] }),
+    '^react-dom/(.*)$': `${reactDomDir}/$1`,
+    '^react/(.*)$': `${reactDir}/$1`,
+  }
+
+  // React 16 and 17 use @testing-library/react 12.x which does not export
+  // renderHook. A shim re-exports it from @testing-library/react-hooks instead.
+  if (major < 18) {
+    mappings['^@testing-library/react$'] = path.join(
+      testDir,
+      '..',
+      'testing-library-shim.js',
+    )
+  } else {
+    mappings['^@testing-library/react$'] = require.resolve(
+      '@testing-library/react',
+      { paths: [testDir] },
+    )
+  }
+
+  return mappings
+}
+
+// React 16 and 17 boundary tests produce harmless "wrong act()" warnings from
+// @testing-library/react-hooks. A setup file suppresses them.
+const generateSetupFiles = (reactVersion) => {
+  if (!reactVersion) {
+    return []
+  }
+
+  const [major] = reactVersion.split('.').map(Number)
+  if (major < 18) {
+    return [path.join(__dirname, 'setupReact.js')]
+  }
+
+  return []
+}
+
 module.exports = {
   collectCoverage: true,
   collectCoverageFrom: ['src/*.{ts,tsx}'],
   moduleFileExtensions: ['ts', 'tsx', 'js'],
+  moduleNameMapper: {
+    ...generateReactVersionMappings(process.env.REACT_VERSION),
+  },
   preset: 'ts-jest',
   rootDir: process.cwd(),
   roots: ['<rootDir>/test'],
+  setupFilesAfterEnv: generateSetupFiles(process.env.REACT_VERSION),
   testEnvironment: 'jsdom',
   testMatch: ['<rootDir>/test/*.spec.ts?(x)'],
   transform: { '^.+\\.(js|tsx?)$': 'ts-jest' },

scripts/jest/setupReact.js

@@ -0,0 +1,15 @@
+// Suppresses the "wrong act()" console.error warnings that
+// @testing-library/react-hooks emits on React 16 and 17. The package uses
+// react-test-renderer internally while state updates flow through react-dom,
+// triggering a harmless mismatch warning.
+const originalError = console.error
+
+console.error = (...args) => {
+  if (
+    typeof args[0] === 'string' &&
+    args[0].includes("It looks like you're using the wrong act()")
+  ) {
+    return
+  }
+  originalError.call(console, ...args)
+}

scripts/test-react.js

@@ -0,0 +1,39 @@
+// Installs dependencies and runs the src test suite against each React version
+// defined in test/react/<version>.
+const { execSync } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+const reactDir = path.join(process.cwd(), 'test', 'react')
+
+const versions = fs
+  .readdirSync(reactDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .filter((entry) =>
+    fs.existsSync(path.join(reactDir, entry.name, 'package.json')),
+  )
+  .map((entry) => entry.name)
+  .sort()
+
+for (const version of versions) {
+  const dir = path.join(reactDir, version)
+
+  console.log(`Starting React ${version} tests`)
+
+  execSync('npm i --no-package-lock --quiet --no-progress', {
+    cwd: dir,
+    stdio: 'inherit',
+  })
+
+  try {
+    execSync(
+      `REACT_VERSION=${version} npx jest --config ./scripts/jest/config.src.js --coverage false`,
+      { stdio: 'inherit' },
+    )
+  } catch {
+    console.error(`Fail testing React ${version}`)
+    process.exit(1)
+  }
+
+  console.log(`Success testing React ${version}`)
+}

test/react/16.14/package.json

@@ -0,0 +1,10 @@
+{
+  "private": true,
+  "devDependencies": {
+    "@testing-library/react": "12.x",
+    "@testing-library/react-hooks": "8.x",
+    "react": "16.14.x",
+    "react-dom": "16.14.x",
+    "react-test-renderer": "16.14.x"
+  }
+}

test/react/17.0/package.json

@@ -0,0 +1,10 @@
+{
+  "private": true,
+  "devDependencies": {
+    "@testing-library/react": "12.x",
+    "@testing-library/react-hooks": "8.x",
+    "react": "17.0.x",
+    "react-dom": "17.0.x",
+    "react-test-renderer": "17.0.x"
+  }
+}

test/react/18.0/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "devDependencies": {
+    "@testing-library/react": "16.x",
+    "react": "18.0.x",
+    "react-dom": "18.0.x"
+  }
+}

test/react/18.3/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "devDependencies": {
+    "@testing-library/react": "16.x",
+    "react": "18.3.x",
+    "react-dom": "18.3.x"
+  }
+}