Installation

This guide will help you install and set up @rageltd/bun-test-utils in your project.

Prerequisites

Install the Package

From npm Registry

bun install @rageltd/bun-test-utils

From GitHub Package Registry

If you prefer to install from GitHub's package registry:

# Configure npm to use GitHub Package Registry for this scope
echo "@rageltd:registry=https://npm.pkg.github.com" >> ~/.npmrc

# Install the package
bun install @rageltd/bun-test-utils

Verify Installation

Create a simple test file to verify the installation:

// test/verify-installation.test.ts
import { test, expect } from 'bun:test';
import { setupTestCleanup, createModuleMocker } from '@rageltd/bun-test-utils';

test('bun-test-utils is working', () => {
  setupTestCleanup();
  const mockModules = createModuleMocker();

  expect(mockModules).toBeDefined();
  expect(typeof mockModules.mock).toBe('function');
});

Run the test:

bun test test/verify-installation.test.ts

TypeScript Configuration

If you're using TypeScript, ensure your tsconfig.json includes the necessary configuration:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "types": ["bun-types"]
  }
}

Package.json Scripts

Add helpful scripts to your package.json:

{
  "scripts": {
    "test": "bun test",
    "test:watch": "bun test --watch",
    "test:coverage": "bun test --coverage"
  }
}

Project Structure

Organize your tests in a logical structure:

your-project/
├── src/
│   ├── components/
│   ├── hooks/
│   └── utils/
├── test/
│   ├── __mocks__/
│   ├── components/
│   ├── hooks/
│   └── utils/
├── package.json
└── tsconfig.json

Development Dependencies

For React testing, you might also want to install:

# For React component testing
bun install --dev @testing-library/react @testing-library/jest-dom

# For user event testing
bun install --dev @testing-library/user-event

Environment Setup

Test Setup File

Create a test setup file to configure global test utilities:

// test/setup.ts
import '@testing-library/jest-dom';
import { setupTestCleanup } from '@rageltd/bun-test-utils';

// Global test cleanup
setupTestCleanup();

// Global test configuration
beforeAll(() => {
  // Setup global mocks or configuration
});

afterAll(() => {
  // Cleanup global resources
});

Bun Test Configuration

Configure Bun to use your setup file by adding to package.json:

{
  "bun": {
    "test": {
      "preload": ["./test/setup.ts"]
    }
  }
}

IDE Configuration

VSCode Settings

Add these settings to .vscode/settings.json for better development experience:

{
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "files.associations": {
    "*.test.ts": "typescript",
    "*.test.tsx": "typescriptreact"
  }
}

Troubleshooting

Module Resolution Issues

# Check if package is installed
bun list | grep bun-test-utils

# Reinstall if missing
bun install @rageltd/bun-test-utils

TypeScript Type Errors

Import Errors

// ✅ Correct - named imports
import { setupTestCleanup, createModuleMocker } from '@rageltd/bun-test-utils';

// ❌ Incorrect - default import
import bunTestUtils from '@rageltd/bun-test-utils';

Version Compatibility

Bun Version Package Version Status 1.0.x Latest ✅ Supported 1.1.x Latest ✅ Supported 0.8.x v1.x ⚠️ Limited

Next Steps

Now that you have the package installed, you're ready to start testing!