{"id":31554709,"url":"https://github.com/rageltd/bun-test-utils","last_synced_at":"2025-10-04T21:13:14.187Z","repository":{"id":298973877,"uuid":"1001707972","full_name":"RageLtd/bun-test-utils","owner":"RageLtd","description":"A collection of utilities to work around https://github.com/oven-sh/bun/issues/7823","archived":false,"fork":false,"pushed_at":"2025-09-08T22:43:15.000Z","size":297,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T20:14:39.355Z","etag":null,"topics":["bun","testing","testing-tools"],"latest_commit_sha":null,"homepage":"http://bun-test-utils.rageltd.ca","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RageLtd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T21:28:41.000Z","updated_at":"2025-09-08T22:40:23.000Z","dependencies_parsed_at":"2025-06-13T23:28:44.535Z","dependency_job_id":null,"html_url":"https://github.com/RageLtd/bun-test-utils","commit_stats":null,"previous_names":["rageltd/bun-test-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RageLtd/bun-test-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RageLtd%2Fbun-test-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RageLtd%2Fbun-test-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RageLtd%2Fbun-test-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RageLtd%2Fbun-test-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RageLtd","download_url":"https://codeload.github.com/RageLtd/bun-test-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RageLtd%2Fbun-test-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278373516,"owners_count":25976150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","testing","testing-tools"],"created_at":"2025-10-04T21:13:13.040Z","updated_at":"2025-10-04T21:13:14.179Z","avatar_url":"https://github.com/RageLtd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @rageltd/bun-test-utils\n\n![Tests](https://github.com/rageltd/bun-test-utils/workflows/Pull%20Request%20Tests/badge.svg)\n![Release](https://github.com/rageltd/bun-test-utils/workflows/Release/badge.svg)\n![npm](https://img.shields.io/npm/v/@rageltd/bun-test-utils)\n\nA collection of test utilities for Bun projects, designed to work around common issues with `bun:test` mocking and provide helpful testing patterns.\n\n## Installation\n\n```bash\nbun install @rageltd/bun-test-utils\n```\n\n## API Reference\n\n### Module Mocking\n\n#### `createModuleMocker(): ModuleMocker`\nCreate a module mocker with proper cleanup for handling bun:test mocking issues.\n\n```typescript\nimport { createModuleMocker } from '@rageltd/bun-test-utils';\n\nconst mockModules = createModuleMocker();\n\n// Mock a module\nawait mockModules.mock('@/hooks', () =\u003e ({\n  useUser: () =\u003e ({ id: 1, name: 'Test User' })\n}));\n\n// Restore specific module\nmockModules.restore('@/hooks');\n\n// Restore all modules\nmockModules.restoreAll();\n```\n\n#### `restoreModules(modulesMap: Record\u003cstring, unknown\u003e): void`\nPattern for manually restoring modules to their original state.\n\n```typescript\nimport { restoreModules } from '@rageltd/bun-test-utils';\n\n// Store originals\nconst originals = {\n  hooks: await import('@/hooks'),\n  utils: await import('@/utils'),\n};\n\n// Restore after tests\nrestoreModules({\n  '@/hooks': originals.hooks,\n  '@/utils': originals.utils,\n});\n```\n\n#### `clearMockRegistry(): void`\nClear the mock registry (useful for test cleanup).\n\n```typescript\nimport { clearMockRegistry } from '@rageltd/bun-test-utils';\n\nafterEach(() =\u003e {\n  clearMockRegistry();\n});\n```\n\n### Cleanup Utilities\n\n#### `setupTestCleanup(): void`\nSetup automatic cleanup for tests (call once per test file).\n\n```typescript\nimport { setupTestCleanup } from '@rageltd/bun-test-utils';\n\nsetupTestCleanup(); // Call at top of test file\n```\n\n#### `withMockCleanup(testSuiteFn: () =\u003e void): void`\nHigher-order function to create test suites with proper mock cleanup.\n\n```typescript\nimport { withMockCleanup, createModuleMocker } from '@rageltd/bun-test-utils';\n\nwithMockCleanup(() =\u003e {\n  describe('My Test Suite', () =\u003e {\n    // Your tests here - cleanup is handled automatically\n  });\n});\n```\n\n## Usage Examples\n\n### Basic Testing Pattern\n\n```typescript\nimport { \n  createModuleMocker, \n  setupTestCleanup,\n  clearMockRegistry\n} from '@rageltd/bun-test-utils';\n\n// Setup cleanup once per file\nsetupTestCleanup();\n\nconst mockModules = createModuleMocker();\n\ndescribe('Component Tests', () =\u003e {\n  beforeEach(async () =\u003e {\n    await mockModules.mock('@/hooks', () =\u003e ({\n      useUser: () =\u003e ({ id: 1, name: 'Test User' })\n    }));\n  });\n\n  afterEach(() =\u003e {\n    clearMockRegistry();\n  });\n\n  afterAll(() =\u003e {\n    mockModules.restoreAll();\n  });\n\n  it('should handle mocked modules', () =\u003e {\n    // Your test here\n  });\n});\n```\n\n### Using withMockCleanup Pattern\n\n```typescript\nimport { withMockCleanup, createModuleMocker } from '@rageltd/bun-test-utils';\n\nwithMockCleanup(() =\u003e {\n  describe('My Test Suite', () =\u003e {\n    const mockModules = createModuleMocker();\n\n    beforeEach(async () =\u003e {\n      await mockModules.mock('@/services', () =\u003e ({\n        apiService: { getData: () =\u003e Promise.resolve({ data: 'test' }) }\n      }));\n    });\n\n    it('should work with automatic cleanup', () =\u003e {\n      // Test implementation\n    });\n  });\n});\n```\n\n## Known Issues\n\nThis package addresses the known bug in bun:test where `mock.restore()` doesn't properly restore modules that were mocked with `mock.module()`.\n\nSee: https://github.com/oven-sh/bun/issues/7823\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Build\nbun run build\n\n# Test\nbun test\n\n# Lint\nbun run lint\n```\n\n## Contributing\n\nThis project uses semantic-release for automated versioning and publishing based on conventional commits.\n\n### Conventional Commits\n\nUse the interactive commit tool:\n```bash\nbun run commit\n```\n\nOr format commits manually:\n```\n\u003ctype\u003e[optional scope]: \u003cdescription\u003e\n\n[optional body]\n\n[optional footer(s)]\n```\n\n**Commit Types for Releases**:\n- `fix:` - Bug fixes (patch release: 1.0.1)\n- `feat:` - New features (minor release: 1.1.0)\n- `BREAKING CHANGE` or `!` - Breaking changes (major release: 2.0.0)\n- Other types (`docs:`, `style:`, `refactor:`, `test:`, `chore:`) don't trigger releases\n\n### Workflow\n\n1. Fork and create a feature branch\n2. Install dependencies: `bun install`\n3. Make changes and add tests\n4. Commit using conventional format: `bun run commit`\n5. Push and open a Pull Request\n\nCI will automatically handle testing, building, and releasing when merged to main.\n\n## Features\n\n- 🚀 Built with Bun for performance\n- 📦 Dual package (ESM + CommonJS) support\n- 🔧 Full TypeScript support\n- 🧪 Module mocking utilities\n- 🔄 Automatic cleanup utilities\n- ⚡ Automated CI/CD with semantic versioning","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frageltd%2Fbun-test-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frageltd%2Fbun-test-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frageltd%2Fbun-test-utils/lists"}