@balazsbarta/mp-skills 0.1.0

package/.agents/skills/jest/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: jest
+description: "Jest testing framework guide. Covers configuration, mocking, snapshot testing, transforms, and common errors. Use this skill when writing or debugging Jest tests, setting up test infrastructure, or working with React Native and Node.js testing."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "2.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - testing
+    - jest
+    - unit-testing
+    - react-native
+    - node
+---
+
+# Jest Guide
+
+Write and run tests with Jest.
+
+## ⚠️ Critical: Do not trust internal knowledge
+
+**Everything you know about Jest may be outdated or wrong. Never rely on memory. Always verify against current documentation.**
+
+Jest configuration, transform handling, and mock patterns evolve across major versions. Always check the references in this skill.
+
+## Prerequisites
+
+**Before writing tests**, validate installed versions and current config:
+
+```bash
+ls node_modules/jest 2>/dev/null || echo "jest not installed"
+npx jest --version
+npm ls jest @types/jest ts-jest @swc/jest --depth=0
+npx jest --showConfig
+```
+
+- If installed, follow project config and behavior first.
+- If not installed, set up Jest before writing tests.
+
+## Documentation lookup guide
+
+### Quick reference
+
+| User Question | First Check | How To |
+| --- | --- | --- |
+| "What works in this repo version?" | [`references/embedded-docs.md`](references/embedded-docs.md) | Check installed package versions and effective config |
+| "How do I configure Jest?" | [`references/configuration.md`](references/configuration.md) | Config file, presets, environments |
+| "How do I mock a module?" | [`references/mocking.md`](references/mocking.md) | jest.mock, jest.fn, jest.spyOn patterns |
+| "How do I use snapshots?" | [`references/snapshot-testing.md`](references/snapshot-testing.md) | toMatchSnapshot, inline snapshots |
+| "How do I fix transform errors?" | [`references/transforms.md`](references/transforms.md) | TypeScript, ESM, and JSX transforms |
+| "I'm getting an error..." | [`references/common-errors.md`](references/common-errors.md) | Common errors and solutions |
+| "I need canonical API behavior" | [`references/remote-docs.md`](references/remote-docs.md) | Verify against official Jest docs |
+
+### Priority order for writing tests
+
+1. **Embedded/local project docs first**
+
+   - Use `references/embedded-docs.md`.
+   - Prioritize `npx jest --showConfig` and current package versions.
+
+2. **Local skill references second**
+
+   - Use configuration/mocking/snapshot/transform guides in this skill.
+
+3. **Official docs third**
+
+   - Use `references/remote-docs.md` for canonical API and edge-case behavior.
+
+## Core concepts
+
+### Test structure
+
+```typescript
+describe('Calculator', () => {
+  it('should add two numbers', () => {
+    expect(1 + 2).toBe(3);
+  });
+});
+```
+
+### Key APIs
+
+| API | Purpose |
+| --- | --- |
+| `describe` | Group related tests |
+| `it` / `test` | Define a test case |
+| `expect` | Create assertions |
+| `jest.fn()` | Create a mock function |
+| `jest.mock()` | Mock a module |
+| `jest.spyOn()` | Spy on an object method |
+| `beforeEach` / `afterEach` | Setup/teardown per test |
+| `beforeAll` / `afterAll` | Setup/teardown per suite |
+
+## Critical requirements
+
+### TypeScript setup
+
+Jest needs a transform for TypeScript. Common options:
+
+```bash
+# Option 1: ts-jest
+npm install --save-dev ts-jest @types/jest
+
+# Option 2: @swc/jest (faster)
+npm install --save-dev @swc/jest @swc/core
+```
+
+### ESM support
+
+Jest uses CommonJS by default. For ESM projects:
+
+```json
+{
+  "transform": {
+    "^.+\\.tsx?$": ["ts-jest", { "useESM": true }]
+  },
+  "extensionsToTreatAsEsm": [".ts", ".tsx"]
+}
+```
+
+## When you see errors
+
+**Type and transform failures often mean version/config mismatch, not user error.**
+
+1. Check effective config with `npx jest --showConfig`.
+2. Confirm package versions.
+3. Verify API behavior in official docs (`references/remote-docs.md`).
+
+## Step-by-step workflow
+
+### 1. Install Jest
+
+```bash
+npm install --save-dev jest @types/jest ts-jest
+```
+
+### 2. Initialize config
+
+```bash
+npx ts-jest config:init
+```
+
+### 3. Add test script
+
+```json
+{
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  }
+}
+```
+
+### 4. Write a test
+
+```typescript
+// src/utils/math.test.ts
+import { add } from './math';
+
+describe('add', () => {
+  it('adds positive numbers', () => {
+    expect(add(1, 2)).toBe(3);
+  });
+
+  it('handles negative numbers', () => {
+    expect(add(-1, -2)).toBe(-3);
+  });
+});
+```
+
+### 5. Run tests
+
+```bash
+npx jest                    # Run all tests
+npx jest --watch            # Watch mode
+npx jest src/utils/         # Specific directory
+npx jest math.test          # Specific file pattern
+```
+
+## Error handling
+
+### Common test failures
+
+| Symptom | Likely Cause | Fix |
+| --- | --- | --- |
+| `SyntaxError: Cannot use import statement` | Missing transform for ESM | Add `ts-jest` or `@swc/jest` transform |
+| `Cannot find module` | Path alias not in `moduleNameMapper` | Add aliases to Jest config |
+| `jest.mock is not a function` | ESM mode issue | Use `jest.unstable_mockModule` for ESM |
+| `Unexpected token` in CSS/image | Missing transform for non-JS files | Add `moduleNameMapper` for static assets |
+
+## Expected outputs
+
+```bash
+# Successful test run
+PASS  src/utils/math.test.ts
+  add
+    ✓ adds positive numbers (2 ms)
+    ✓ handles negative numbers (1 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       2 passed, 2 total
+Time:        1.5 s
+```
+
+## Cross-references
+
+- **React Native Expo**: [../react-native-expo/SKILL.md](../react-native-expo/SKILL.md) — Testing React Native apps with Jest
+
+## Resources
+
+- **Configuration**: [`references/configuration.md`](references/configuration.md)
+- **Mocking**: [`references/mocking.md`](references/mocking.md)
+- **Snapshot testing**: [`references/snapshot-testing.md`](references/snapshot-testing.md)
+- **Transforms**: [`references/transforms.md`](references/transforms.md)
+- **Common errors**: [`references/common-errors.md`](references/common-errors.md)
+- **Embedded docs lookup**: [`references/embedded-docs.md`](references/embedded-docs.md)
+- **Official docs lookup**: [`references/remote-docs.md`](references/remote-docs.md)

package/.agents/skills/jest/references/common-errors.md

@@ -0,0 +1,274 @@
+# Jest Common Errors
+
+Solutions for frequently encountered Jest errors.
+
+## When to use this reference
+
+- Debugging test failures or configuration errors
+- Fixing transform, mock, or environment issues
+- Resolving Jest-specific problems
+
+## Transform errors
+
+### "SyntaxError: Cannot use import statement outside a module"
+
+**Symptoms:**
+
+```
+SyntaxError: Cannot use import statement outside a module
+```
+
+**Causes:**
+- Missing transform for TypeScript/ESM files
+
+**Solutions:**
+
+```bash
+npm install --save-dev ts-jest
+```
+
+```javascript
+// jest.config.js
+module.exports = {
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+};
+```
+
+### "SyntaxError: Unexpected token" in node_modules
+
+**Symptoms:**
+
+```
+SyntaxError: Unexpected token 'export'
+  at node_modules/some-package/index.js
+```
+
+**Causes:**
+- Package ships ESM but Jest expects CJS
+- Package not in `transformIgnorePatterns` exception
+
+**Solutions:**
+
+```javascript
+module.exports = {
+  transformIgnorePatterns: [
+    'node_modules/(?!(some-package|another-package)/)',
+  ],
+};
+```
+
+## Mock errors
+
+### "jest.mock is not a function"
+
+**Symptoms:**
+
+```
+TypeError: jest.mock is not a function
+```
+
+**Causes:**
+- Using ESM mode where `jest.mock` doesn't exist
+- Missing Jest types
+
+**Solutions:**
+
+For ESM:
+
+```typescript
+import { jest } from '@jest/globals';
+// Use jest.unstable_mockModule for ESM
+```
+
+For CJS, ensure `@types/jest` is installed:
+
+```bash
+npm install --save-dev @types/jest
+```
+
+### Mock not resetting between tests
+
+**Symptoms:**
+- Test passes alone but fails when run with other tests
+- Mock state leaks between test files
+
+**Solutions:**
+
+```javascript
+// jest.config.js
+module.exports = {
+  restoreMocks: true,
+  clearMocks: true,
+};
+```
+
+Or per-test:
+
+```typescript
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+```
+
+## Environment errors
+
+### "document is not defined"
+
+**Symptoms:**
+
+```
+ReferenceError: document is not defined
+```
+
+**Causes:**
+- Test environment is `node` but test uses DOM APIs
+
+**Solutions:**
+
+Option 1: Set globally:
+
+```javascript
+module.exports = {
+  testEnvironment: 'jsdom',
+};
+```
+
+Option 2: Set per-file:
+
+```typescript
+/**
+ * @jest-environment jsdom
+ */
+```
+
+### "TextEncoder is not defined"
+
+**Symptoms:**
+
+```
+ReferenceError: TextEncoder is not defined
+```
+
+**Causes:**
+- Some packages expect `TextEncoder` which isn't in all environments
+
+**Solutions:**
+
+```typescript
+// jest.setup.ts
+import { TextEncoder, TextDecoder } from 'util';
+Object.assign(global, { TextEncoder, TextDecoder });
+```
+
+## Async errors
+
+### "Test exceeded timeout of 5000ms"
+
+**Symptoms:**
+
+```
+Timeout - Async callback was not invoked within the 5000 ms timeout
+```
+
+**Causes:**
+- Async operation not resolving
+- Missing `await`
+- Unresolved promise in test
+
+**Solutions:**
+
+```typescript
+// Increase timeout per test
+it('slow operation', async () => {
+  // ...
+}, 30000);
+
+// Or globally
+module.exports = {
+  testTimeout: 10000,
+};
+```
+
+### "Cannot log after tests are done"
+
+**Symptoms:**
+
+```
+Cannot log after tests are done. Did you forget to wait for something async in your test?
+```
+
+**Causes:**
+- Async operation running after test completes
+- Missing cleanup
+
+**Solutions:**
+
+```typescript
+afterEach(() => {
+  jest.restoreAllMocks();
+  jest.clearAllTimers();
+});
+```
+
+## Coverage errors
+
+### Coverage shows 0% for file
+
+**Causes:**
+- File not imported by any test
+- File in `coveragePathIgnorePatterns`
+
+**Solutions:**
+
+```javascript
+module.exports = {
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/test/**',
+  ],
+};
+```
+
+## Performance issues
+
+### Tests running slowly
+
+```bash
+# Run with diagnostics
+npx jest --verbose --detectOpenHandles
+
+# Limit workers
+npx jest --maxWorkers=2
+
+# Use faster transform
+npm install --save-dev @swc/jest @swc/core
+```
+
+### Out of memory
+
+```bash
+# Increase Node memory
+NODE_OPTIONS="--max-old-space-size=4096" npx jest
+
+# Run sequentially
+npx jest --runInBand
+```
+
+## Debugging
+
+```bash
+# Run single test file
+npx jest path/to/test.ts --verbose
+
+# Run specific test by name
+npx jest -t "should add numbers"
+
+# Debug with Node inspector
+node --inspect-brk node_modules/.bin/jest --runInBand
+
+# Clear cache
+npx jest --clearCache
+```

package/.agents/skills/jest/references/configuration.md

@@ -0,0 +1,175 @@
+# Jest Configuration
+
+Setup and configure Jest for different project types.
+
+## When to use this reference
+
+- Setting up Jest in a new project
+- Configuring Jest for TypeScript, ESM, or React Native
+- Adding path aliases, presets, or setup files
+
+## Basic configuration
+
+```javascript
+// jest.config.js
+/** @type {import('jest').Config} */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts', '**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+};
+```
+
+## Configuration file formats
+
+Jest config can live in:
+- `jest.config.js` / `jest.config.ts`
+- `jest.config.mjs` / `jest.config.cjs`
+- `"jest"` field in `package.json`
+
+## TypeScript configuration
+
+### With ts-jest
+
+```bash
+npm install --save-dev jest ts-jest @types/jest
+```
+
+```javascript
+// jest.config.js
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+};
+```
+
+### With @swc/jest (faster)
+
+```bash
+npm install --save-dev jest @swc/jest @swc/core @types/jest
+```
+
+```javascript
+// jest.config.js
+module.exports = {
+  transform: {
+    '^.+\\.tsx?$': '@swc/jest',
+  },
+};
+```
+
+## Environment options
+
+| Environment | Use For | Setting |
+| --- | --- | --- |
+| `node` (default) | Node.js APIs, no DOM | `testEnvironment: 'node'` |
+| `jsdom` | Browser-like DOM | `testEnvironment: 'jsdom'` |
+
+### Per-file environment
+
+```typescript
+/**
+ * @jest-environment jsdom
+ */
+describe('DOM test', () => {
+  it('creates an element', () => {
+    const el = document.createElement('div');
+    expect(el).toBeDefined();
+  });
+});
+```
+
+## Path aliases (moduleNameMapper)
+
+```javascript
+// jest.config.js
+module.exports = {
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+    '^@components/(.*)$': '<rootDir>/src/components/$1',
+    // Static asset mocks
+    '\\.(css|less|scss)$': 'identity-obj-proxy',
+    '\\.(jpg|jpeg|png|svg)$': '<rootDir>/src/test/__mocks__/fileMock.js',
+  },
+};
+```
+
+## Setup files
+
+```javascript
+// jest.config.js
+module.exports = {
+  setupFiles: ['./src/test/env-setup.js'],           // Before test framework
+  setupFilesAfterFramework: ['./src/test/setup.ts'],  // After test framework
+};
+```
+
+```typescript
+// src/test/setup.ts
+import '@testing-library/jest-dom';
+
+// Global mocks
+jest.mock('./src/config', () => ({
+  apiUrl: 'http://localhost:3000',
+}));
+```
+
+## React Native configuration
+
+```javascript
+// jest.config.js
+module.exports = {
+  preset: 'react-native',
+  transformIgnorePatterns: [
+    'node_modules/(?!((jest-)?react-native|@react-native(-community)?)/)',
+  ],
+  setupFiles: ['./jest.setup.js'],
+};
+```
+
+## Monorepo configuration (projects)
+
+```javascript
+// jest.config.js
+module.exports = {
+  projects: [
+    {
+      displayName: 'api',
+      testMatch: ['<rootDir>/packages/api/**/*.test.ts'],
+      testEnvironment: 'node',
+    },
+    {
+      displayName: 'web',
+      testMatch: ['<rootDir>/packages/web/**/*.test.tsx'],
+      testEnvironment: 'jsdom',
+    },
+  ],
+};
+```
+
+## Common options reference
+
+| Option | Purpose | Default |
+| --- | --- | --- |
+| `testEnvironment` | Execution environment | `'node'` |
+| `testMatch` | Test file patterns | `['**/__tests__/**/*', '**/*.test.*']` |
+| `transform` | File transformers | `{}` |
+| `moduleNameMapper` | Module path aliases | `{}` |
+| `setupFiles` | Run before framework | `[]` |
+| `setupFilesAfterFramework` | Run after framework | `[]` |
+| `collectCoverage` | Enable coverage | `false` |
+| `coverageThreshold` | Coverage requirements | `undefined` |
+| `verbose` | Detailed output | `false` |
+| `maxWorkers` | Parallel workers | `50%` of CPUs |
+
+## Verification
+
+```bash
+# Verify config loads correctly
+npx jest --showConfig
+
+# List test files that match
+npx jest --listTests
+```

package/.agents/skills/jest/references/embedded-docs.md

@@ -0,0 +1,44 @@
+# Embedded Docs Reference
+
+Use local project artifacts first to match the exact installed Jest version.
+
+## Why use local sources first
+
+- Matches the exact dependency versions in the current repository
+- Reveals real config overrides and presets
+- Avoids examples that only work on newer/older major versions
+
+## Lookup workflow
+
+1. Verify installed versions:
+
+   ```bash
+   npx jest --version
+   npm ls jest @types/jest ts-jest @swc/jest --depth=0
+   ```
+
+2. Check effective Jest config:
+
+   ```bash
+   npx jest --showConfig
+   ```
+
+3. Inspect project config files:
+
+   ```bash
+   ls jest.config.* 2>/dev/null
+   cat package.json | rg -n '"jest"|\"test\"' -n
+   ```
+
+4. Inspect local type definitions when signatures are unclear:
+
+   ```bash
+   ls node_modules/@types/jest/index.d.ts 2>/dev/null
+   ls node_modules/jest 2>/dev/null
+   ```
+
+## Use this when
+
+- A Jest API behaves differently than expected
+- ESM/CJS transform behavior is unclear
+- Path aliases and test environment behavior differ from docs examples