@jmlweb/jest-config 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @jmlweb/jest-config
 
+## 0.1.3
+
+### Patch Changes
+
+- 4a9ece1: Update documentation to use pnpm commands instead of npm
+
+## 0.1.2
+
+### Patch Changes
+
+- 6b73301: Add changelog section with link to CHANGELOG.md in package READMEs
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -20,9 +20,11 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/jest-config jest ts-jest @types/jest
+pnpm add -D @jmlweb/jest-config jest ts-jest @types/jest
 ```
 
+> 💡 **Upgrading from a previous version?** See the [Migration Guide](#-migration-guide) for breaking changes and upgrade instructions.
+
 ## 🚀 Quick Start
 
 Create a `jest.config.ts` file in your project root:
@@ -121,6 +123,38 @@ export default createJestConfig({
 });
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Tests should run reliably with meaningful coverage metrics that enforce code quality without being overly strict.
+
+This package provides a Jest configuration optimized for TypeScript projects with sensible coverage thresholds and test isolation. It balances strictness with practicality, enforcing coverage standards while keeping tests fast and maintainable.
+
+### Design Decisions
+
+**80% Coverage Thresholds**: Requires 80% coverage across all metrics
+
+- **Why**: 80% coverage strikes a good balance - it's high enough to ensure most code paths are tested but not so high that you waste time testing trivial code or struggle to reach unrealistic goals. It catches most bugs while allowing flexibility for edge cases that are hard to test
+- **Trade-off**: Some projects may want higher coverage (90%+) or lower (60%). This is easily adjustable per project
+- **When to override**: Increase for critical systems (financial, healthcare), decrease for experimental projects or when initially adding tests to legacy code
+
+**Automatic Mock Clearing (`clearMocks: true, restoreMocks: true`)**: Resets mocks between tests
+
+- **Why**: Test isolation is crucial for reliable tests. Automatically clearing and restoring mocks prevents test interdependence and the dreaded "works in isolation but fails in suite" problem. This eliminates an entire class of flaky tests
+- **Trade-off**: Can't rely on mock state persisting between tests. But tests shouldn't share state anyway
+- **When to override**: Rarely needed - test isolation is a best practice
+
+**Node Environment by Default (`testEnvironment: 'node'`)**: Server-side testing environment
+
+- **Why**: Most TypeScript projects tested with Jest are Node.js backends or libraries. The Node environment is lighter and faster than jsdom. For React/browser code, developers can override to jsdom per project
+- **Trade-off**: Need to explicitly set jsdom for browser/React testing
+- **When to override**: For React components or browser-specific code - set `testEnvironment: 'jsdom'` in your project config
+
+**5 Second Test Timeout**: Reasonable default for most tests
+
+- **Why**: Most unit tests should complete in milliseconds. 5 seconds is generous for integration tests while preventing truly hung tests from blocking CI indefinitely. It catches accidentally synchronous code or missing mocks
+- **Trade-off**: Some integration tests with real databases might need longer timeouts
+- **When to override**: For slow integration tests - increase per test suite or project-wide
+
 ## 📋 Configuration Details
 
 ### Default Settings
@@ -220,10 +254,10 @@ Add test scripts to your `package.json`:
 Then run:
 
 ```bash
-npm run test           # Run tests once
-npm run test:watch     # Run tests in watch mode
-npm run test:coverage  # Run tests with coverage
-npm run test:ci        # Run tests in CI mode
+pnpm test           # Run tests once
+pnpm test:watch     # Run tests in watch mode
+pnpm test:coverage  # Run tests with coverage
+pnpm test:ci        # Run tests in CI mode
 ```
 
 ### TypeScript Configuration
@@ -253,11 +287,36 @@ This package requires the following peer dependencies:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/vitest-config`](../vitest-config) - Vitest configuration for modern testing
 - [`@jmlweb/eslint-config-base`](../eslint-config-base) - ESLint config for TypeScript projects
 - [`@jmlweb/prettier-config-base`](../prettier-config-base) - Prettier config for consistent formatting
 - [`@jmlweb/tsconfig-base`](../tsconfig-base) - TypeScript configuration
 
+### External Tools
+
+- [Jest](https://jestjs.io/) - Delightful JavaScript testing framework
+- [ts-jest](https://kulshekhar.github.io/ts-jest/) - TypeScript preprocessor for Jest
+- [@testing-library/jest-dom](https://testing-library.com/docs/ecosystem-jest-dom/) - Custom Jest matchers for the DOM
+- [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) - React testing utilities (for React projects)
+
+## 🔄 Migration Guide
+
+### Upgrading to a New Version
+
+> **Note:** If no breaking changes were introduced in a version, it's safe to upgrade without additional steps.
+
+**No breaking changes have been introduced yet.** This package follows semantic versioning. When breaking changes are introduced, detailed migration instructions will be provided here.
+
+For version history, see the [Changelog](./CHANGELOG.md).
+
+**Need Help?** If you encounter issues during migration, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.
+
 ## 📄 License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlweb/jest-config",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Base Jest configuration for jmlweb projects with TypeScript support and coverage settings",
   "type": "module",
   "main": "./dist/index.cjs",