# client-epic-state

Common module for Web, Mobile & Server Side Rendering repos containing required abstractions for state management, data transformation & async network communication.

## Testing Best Practices

### Local Development

- Use `pnpm test` to run the full suite before pushing to `master` or publishing.
- Build command has test suite integration:
  - `pnpm build` runs the full test suite along with linting and TypeScript compilation
  - Tests are run using Vitest to ensure all tests pass before building
  - If any tests fail, the build process will be terminated
  - Test files are automatically excluded from the final build output

### Test & Typecheck Commands

- **Run all tests and typecheck test files:**

  ```sh
  pnpm test
  ```

  This will typecheck all `.vitest.ts` files and their dependencies, then run the full test suite. The build will fail if there are any TypeScript errors in test files.

- **Typecheck only test files:**

  ```sh
  pnpm test:typecheck
  ```

  This will only typecheck `.vitest.ts` files and their dependencies, and print the time taken.

- **Typecheck and run a single test file:**
  ```sh
  pnpm run test:file <filename-or-unique-substring>
  ```
  Example:
  ```sh
  pnpm run test:file testTransactionsViewReducer
  ```
  This will search for a file in `src/` whose name contains the given string (case-insensitive), typecheck it, and run only its tests.
  - If multiple files match, you'll see a list and must be more specific.
  - If no files match, you'll get an error.

#### Note on Typechecking

Testing types with `tsc` and Vitest is an experimental feature. Breaking changes might not follow SemVer, so please pin Vitest's version when using it. See [Vitest docs](https://vitest.dev/guide/testing-types.html) for more info.

### Vitest

- Fast framework for running unit, integration, and component tests in modern TypeScript/JavaScript projects.
- Provides instant feedback with watch mode, built-in coverage, and Jest-compatible APIs.
- Recommended for new tests and as a drop-in replacement for legacy Jest/Chai setups.

---

## Available NPM Scripts

### Test & Typecheck

- `pnpm test` — Typechecks all `.vitest.ts` files and runs the full test suite.
- `pnpm test:typecheck` — Typechecks only `.vitest.ts` files and their dependencies, prints time taken.
- `pnpm run test:file <file>` — Typechecks and runs tests for a single file.

### Build & Clean

- `pnpm build` — Runs ESLint, typechecks, tests, and then cleans up mocks/test helpers.
- `pnpm only-build` — Runs ESLint and typechecks, then cleans up mocks/test helpers.
- `pnpm clean` — Removes the `lib` directory.

### Lint & Format

- `pnpm lint` — Runs ESLint with auto-fix on all JS/TS files.
- `pnpm format` — Formats all source files with Prettier.
- `pnpm format-watch` — Formats only changed/added TS/TSX files with Prettier.

### Code Quality & Analysis

- `pnpm find-dead-code` — Finds unused code using ts-prune.
- `pnpm find-unused-exports` — Finds unused exports using ts-unused-exports.
- `pnpm circular-dependency` — Detects circular dependencies using madge.

### Release & Versioning

- `pnpm prepublishOnly` — Runs branch validation, updates Slack topic, checks version, cleans, and builds before publishing.
- `pnpm version` — Stages all changes in `src` for versioning.
- `pnpm postversion` — Pushes commits and tags after version bump.
- `pnpm check-version` — Checks the current version using a custom script.
- `pnpm check-dependencies` — Checks dependencies using a custom script.
- `pnpm clean-resolutions` — Cleans up resolutions using a custom script.
- `pnpm create-or-update-release-branch` — Runs the release branch creation/update script.
- `pnpm bump-versions-master` — Bumps versions and publishes all client repos on master end-to-end (per-repo PR + auto-merge + publish; v2 bumps only, no deploy).
- `pnpm bump-versions-beta` — Selectable upstream→downstream beta publish chain (CES / analytics / web-components / app-ui / cockpit) tagged `beta<initials>`. v2 step is a local-only dep repointing (no commit, no publish). Single-popup config.
- `pnpm bump-update-web-app-cockpit-beta` — Runs the cockpit beta update script.
- `pnpm send-release-notes` — Sends release notes using a custom script.
- `pnpm update-slack-group-topic` — Updates the Slack group topic using a custom script.
- `pnpm build-beta-and-copy` — Runs the beta build and copy script.
- `pnpm pr-approvals-update` — Updates PR approvals using a custom script.
- `pnpm raise-pr-automation` — Runs the PR automation script.