Add an integration test suite (#412)

* test: add vitest test suite with ported react-select tests

Adds vitest + jsdom + @testing-library/{react,user-event,jest-dom} as
devDependencies and configures a Chakra-provider-wrapped render helper.
Ports the upstream react-select tests (Select, Async, Creatable,
AsyncCreatable, StateManaged + the constants fixture) from
react-select@5.10.2 with the adaptations the wrapper needs: imports
from the package source, userEvent v14 async migration, and a small
jest-in-case shim that honors per-case skip/only flags.

Adds dedicated coverage for the props this package layers on top of
react-select (size, variant, invalid, disabled, readOnly, chakraStyles,
tagColorPalette, tagVariant, selectedOptionStyle,
selectedOptionColorPalette, focusRingColor, useChakraSelectProps),
using a probe pattern that captures chakraStyles slot state to bypass
jsdom CSS-engine flakiness.

Also fixes a small accessibility gap surfaced while writing tests:
passing \`invalid\` directly to Select now propagates to aria-invalid on
the rendered input, matching how Field.Root invalid inheritance already
worked.

A CI workflow runs the suite on push to main/v5 and on PR. Final tally:
271 passing, 4 skipped (upstream's own QUESTION-marked tests and
intentional Chakra divergences). The .oxlintrc.json ignores src/tests/
since upstream's style differs from our strict project rules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: limit test workflow push trigger to main

Each branch's workflow only knows about its code, so listing both
[main, v5] in a single workflow file is a footgun — only the branch
whose name matches will actually run, and pushing to the other
branch silently fires nothing useful from this file. Matches the
existing convention used by lint.yml, pkg-pr.yml, and zizmor.yml.

A parallel copy in the v5 branch should reference [v5] only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: extract lint-staged config and filter ignored paths

Moves the lint-staged config from package.json into .lintstagedrc.cjs
so we can use a function to filter file lists before invoking oxlint.
oxlint exits non-zero with "No files found to lint" when every staged
path matches its ignorePatterns (e.g. a commit touching only files
under src/tests/), which broke the pre-commit hook for test-only
changes. The filter drops src/tests/ paths before invoking oxlint;
oxfmt still formats them via the catch-all glob.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: pin react-select source version in ported test files

Each ported test file now carries a header comment with a permalink to
the exact upstream source at react-select@5.10.2 plus a brief re-port
checklist for future dep bumps. constants.ts gets a verbatim note
since its data fixtures should stay bit-identical with upstream.

No behavior change — comments only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: run tests across Node 20 and 24

Adds a Node version matrix to the test workflow so we catch regressions
that depend on the runtime — particularly relevant given the test suite
relies on jsdom whose CSS serialization differs across versions (we
already hit a jsdom 22 -> 25 change in caret-color handling). 20 is the
current LTS, 24 is the latest stable. fail-fast: false so a failure on
one runner doesn't cancel the other and obscure which is broken.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: document the test suite in CONTRIBUTING

Adds a `pnpm test` bullet to the pre-PR checklist and a new Tests
section explaining the suite layout, the file naming convention, and
the manual re-port checklist for `react-select` dep bumps. The intent
is to make the porting boundary explicit so future contributors don't
fold chakra-specific assertions back into the ported files or skip
the upstream-source comments.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: switch lint-staged config to ESM

`.cjs` was unnecessary in a `type: commonjs` project — a plain `.js`
file already would have been CommonJS — and ESM is the better default
for new config files. Behavior unchanged from the previous .cjs
version. Uses `import.meta.dirname` (Node 20.11+); our CI matrix
requires Node 20+.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: lint-clean .lintstagedrc.mjs

Two layers:

* In source: name the default export (satisfies
  import/no-anonymous-default-export) and add braces to the bare
  if/return (satisfies eslint/curly). Both fixes are easy improvements
  that match project style.
* In config: add a *.mjs override that disables rules which
  fundamentally don't apply to root tooling configs —
  import/no-nodejs-modules (Node tooling legitimately imports
  node:built-ins) and the three typescript/no-unsafe-* rules (a .mjs
  file has no TS declarations, so type-aware oxlint sees everything as
  `any`).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: enable oxlint on the test suite

Removes `src/tests/` from `.oxlintrc.json` `ignorePatterns` so the
tests now get linted alongside source. A scoped override exempts the
small set of rules that legitimately don't apply to spy/mock-style
test code: TS unsafe checks, the `cases()` non-null assertions,
react-perf inline-prop rules, jsx-a11y rules for synthetic fixtures,
and a handful of unicorn opinions that don't fit our jsdom env.

Also adds the `vitest` plugin and enables most of its rules
project-wide; the disables for vitest stylistic preferences
(`prefer-to-be*`, `prefer-lowercase-title`, etc.) live at the top
level since those rules are no-ops outside test files anyway.

Source side: a sweep that converts the upstream-ported style to
project conventions — `let` → `const` where appropriate, type-only
import splits, `toHaveLength`/`toStrictEqual` matcher upgrades,
function declarations to expressions, a few prefer-destructuring
rewrites, regex `u` flags, etc. Two intentional patterns get
per-line `oxlint-disable-next-line` comments (definite-assignment
`let event!:`, the 4th-element index in state-managed-select).

`init-declarations` ends up off project-wide. It conflicts with
`unicorn/no-useless-undefined` (one wants `= undefined`, the other
forbids it); we pick the no-useless-undefined style so
`let captured: T | undefined;` stays uninitialised. The change goes
at the top level rather than in the test override because the
preference is consistent for source code too.

Test counts: 271 passing, 4 skipped, 0 lint errors. Remaining lint
output is 4 `no-warning-comments` warnings (2 pre-existing project
TODOs in src/chakra-components, 2 upstream-ported `TODO: Cover more
scenarios` in select.test.tsx) — kept as warnings intentionally to
keep TODOs visible.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: csandman

.github/workflows/test.yml

@@ -0,0 +1,39 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20, 24]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+
+      - name: Install Dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test

.lintstagedrc.mjs

@@ -0,0 +1,34 @@
+// lint-staged config — moved here from package.json so we can use a
+// function to filter file lists before invoking oxlint. The default glob
+// picks up files under src/tests/, but oxlint excludes that directory via
+// ignorePatterns in .oxlintrc.json; passing it nothing-but-ignored files
+// makes oxlint exit non-zero with "No files found to lint", which breaks
+// the pre-commit hook for test-only changes. The filter drops src/tests/
+// paths before invoking oxlint; oxfmt still formats them.
+
+import path from "node:path";
+
+const IGNORED = ["src/tests/"];
+
+const filterLintable = (files) =>
+  files.filter((file) => {
+    const rel = path.relative(import.meta.dirname, file);
+    return !IGNORED.some((prefix) => rel.startsWith(prefix));
+  });
+
+const config = {
+  "demo/**/*.{js,jsx,ts,tsx}":
+    "oxlint -c demo/.oxlintrc.json --disable-nested-config --fix",
+  "!(demo|codemod)/**/*.{js,jsx,ts,tsx}": (files) => {
+    const lintable = filterLintable(files);
+    if (lintable.length === 0) {
+      return [];
+    }
+    return `oxlint -c .oxlintrc.json --disable-nested-config --fix ${lintable
+      .map((f) => JSON.stringify(f))
+      .join(" ")}`;
+  },
+  "*": "oxfmt",
+};
+
+export default config;

.oxlintrc.json

@@ -11,7 +11,8 @@
     "jsdoc",
     "jsx-a11y",
     "node",
-    "promise"
+    "promise",
+    "vitest"
   ],
   "categories": {
     "correctness": "error",
@@ -58,7 +59,15 @@
     "no-proto": "error",
     "no-regex-spaces": "warn",
     "no-sequences": "error",
-    "no-unused-vars": ["error", { "ignoreRestSiblings": true }],
+    "no-unused-vars": [
+      "error",
+      {
+        "ignoreRestSiblings": true,
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "caughtErrorsIgnorePattern": "^_"
+      }
+    ],
     "no-var": "error",
     "no-void": "warn",
     "prefer-const": "error",
@@ -94,6 +103,7 @@
     "@typescript-eslint/strict-boolean-expressions": "off",
     "capitalized-comments": "off",
     "id-length": "off",
+    "init-declarations": "off",
     "import/exports-last": "off",
     "import/group-exports": "off",
     "import/no-named-export": "off",
@@ -122,7 +132,60 @@
     "react-perf/jsx-no-new-function-as-prop": "off",
     "sort-imports": "off",
     "sort-keys": "off",
-    "unicorn/no-null": "off"
+    "unicorn/no-null": "off",
+
+    "vitest/consistent-test-it": [
+      "error",
+      { "fn": "test", "withinDescribe": "test" }
+    ],
+    "vitest/max-expects": "off",
+    "vitest/no-conditional-in-test": "off",
+    "vitest/no-hooks": "off",
+    "vitest/no-importing-vitest-globals": "off",
+    "vitest/no-standalone-expect": "off",
+    "vitest/prefer-called-times": "off",
+    "vitest/prefer-called-with": "off",
+    "vitest/prefer-expect-assertions": "off",
+    "vitest/prefer-lowercase-title": "off",
+    "vitest/prefer-strict-boolean-matchers": "off",
+    "vitest/prefer-to-be": "off",
+    "vitest/prefer-to-be-falsy": "off",
+    "vitest/prefer-to-be-truthy": "off",
+    "vitest/require-hook": "off",
+    "vitest/require-mock-type-parameters": "off"
   },
-  "overrides": []
+  "overrides": [
+    {
+      "files": ["*.mjs"],
+      "rules": {
+        "import/no-nodejs-modules": "off",
+        "@typescript-eslint/no-unsafe-argument": "off",
+        "@typescript-eslint/no-unsafe-call": "off",
+        "@typescript-eslint/no-unsafe-return": "off"
+      }
+    },
+    {
+      "files": ["src/tests/**/*.{ts,tsx}"],
+      "rules": {
+        // ─── TS strictness relaxed for spy/mock-style test code ───
+        "@typescript-eslint/no-non-null-assertion": "off",
+        "@typescript-eslint/no-useless-default-assignment": "off",
+
+        // ─── General style/correctness rules tests legitimately break ───
+        "no-console": "off",
+        "no-param-reassign": "off",
+        "no-underscore-dangle": "off",
+
+        // ─── JSX/a11y/perf rules not applicable to test fixtures ───
+        "jsx-a11y/no-autofocus": "off",
+        "react-perf/jsx-no-new-array-as-prop": "off",
+        "react-perf/jsx-no-new-object-as-prop": "off",
+
+        // ─── Unicorn opinions that don't fit test patterns ───
+        "unicorn/consistent-function-scoping": "off",
+        "unicorn/prefer-at": "off",
+        "unicorn/prefer-global-this": "off"
+      }
+    }
+  ]
 }

CONTRIBUTING.md

@@ -15,6 +15,9 @@ Before you open a PR:
 - Please ensure all the examples work correctly after your change.
 - Also run `pnpm lint` to ensure that the change meets the projects code style
   setup.
+- Run `pnpm test` to verify the test suite still passes. The suite covers both
+  behavior ported from `react-select` and chakra-specific extensions — see the
+  [Tests](#tests) section below.
 - Make sure there's an issue open for any work you take on and intend to submit
   as a pull request - it helps core members review your concept and direction
   early and is a good way to discuss what you're planning to do.
@@ -23,3 +26,45 @@ Before you open a PR:
   your hard work.
 - All new features and changes need documentation. If you don't have time to
   write any, leave a note in your PR.
+
+## Tests
+
+The test suite lives in [`src/tests/`](./src/tests/) and runs with
+[Vitest](https://vitest.dev) against a `jsdom` environment plus
+`@testing-library/react`:
+
+- `select.test.tsx`, `async-select.test.tsx`, `creatable-select.test.tsx`,
+  `async-creatable-select.test.tsx`, `state-managed-select.test.tsx` — ported
+  from `react-select`'s own `__tests__` directory. Each file's header
+  comment carries a permalink to the upstream source at the pinned version.
+- `chakra-specific.test.tsx` — exercises the props this package adds on
+  top of `react-select` (`size`, `variant`, `invalid`, `chakraStyles`,
+  `tagColorPalette`, `selectedOptionStyle`, etc.).
+- `constants.ts` — option fixtures, copied verbatim from upstream.
+- `render.tsx`, `setup.ts`, `cases.ts` — local helpers (Chakra-wrapped
+  render, jsdom polyfills, `jest-in-case` shim).
+
+Useful commands:
+
+- `pnpm test` — run the suite once
+- `pnpm test:watch` — re-run on file changes
+
+### When bumping the `react-select` dependency
+
+If a `react-select` bump introduces test changes, port them in as a manual
+step rather than rewriting the ported files from scratch:
+
+1. Diff the upstream
+   [`__tests__/` folder](https://github.com/JedWatson/react-select/tree/master/packages/react-select/src/__tests__)
+   between the old and new tag — the header comment in each ported file links
+   to the source at the currently pinned tag.
+2. For each upstream test that's new or whose body changed, port it
+   following the same adaptations already in use:
+   - imports from `../index` (not `../Select` etc.)
+   - `render` from `./render` (provides Chakra context)
+   - `userEvent.setup()` + `await user.click/type` (v14 async API)
+   - `vi.fn` instead of `jest.fn`
+   - skip snapshot tests
+3. Update each ported file's header permalink to point at the new tag.
+4. Leave chakra-specific tests in `chakra-specific.test.tsx` — don't fold
+   chakra-only assertions into the ported files.

package.json

@@ -62,38 +62,42 @@
     "lint:types": "tsc",
     "lint-fix": "oxlint -c .oxlintrc.json --fix",
     "prepare": "husky",
-    "prepublishOnly": "pnpm build && pnpm lint",
+    "prepublishOnly": "pnpm build && pnpm lint && pnpm test",
     "postpublish": "git push --follow-tags",
-    "lint:publish": "publint"
+    "lint:publish": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "react-select": "^5.10.2"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@chakra-ui/react": "~3.35.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.0",
     "concurrently": "^9.2.1",
     "husky": "^9.1.7",
+    "jsdom": "^25.0.1",
     "lint-staged": "^17.0.4",
     "next-themes": "~0.4.6",
     "oxfmt": "^0.49.0",
     "oxlint": "^1.64.0",
     "oxlint-tsgolint": "^0.22.1",
     "publint": "^0.3.21",
     "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
     "@chakra-ui/react": "3.x",
     "next-themes": "0.x",
     "react": "18.x || 19.x"
   },
-  "lint-staged": {
-    "demo/**/*.{js,jsx,ts,tsx}": "oxlint -c demo/.oxlintrc.json --disable-nested-config --fix",
-    "!(demo|codemod)/**/*.{js,jsx,ts,tsx}": "oxlint -c .oxlintrc.json --disable-nested-config --fix",
-    "*": "oxfmt"
-  },
   "packageManager": "pnpm@11.1.1+sha512.d1fdf5f73c617b64fa1a56a81c3c8dfe0e966e33a6010aa256b517ae77be21d93e05affc0de1a83b0e4f29d569f68b446ae8f068cd7247c0bb3df0fb4d7bdf9a"
 }