README.md

Custom Jest/Vitest Matchers Library

A collection of custom matchers for use with Jest and Vitest to enhance your testing capabilities. These matchers allow you to write more descriptive and powerful test assertions for DOM elements and other JavaScript objects.

Features

• Custom matchers to assert DOM roles, text content, and more.
• Compatible with Jest and Vitest testing frameworks.
• TypeScript support with proper type definitions for all matchers.
• Modular: Import all matchers or just the ones you need.

Installation

Using npm

npm install @your-username/custom-matchers

Using Yarn

yarn add @your-username/custom-matchers

Direct Tarball Install (if hosted privately)

npm install https://github.com/your-username/custom-matchers/releases/download/v1.0.0/custom-matchers-1.0.0.tgz

Usage

Extending Jest or Vitest with Custom Matchers

You can extend Jest or Vitest with all the custom matchers from this library by adding them to your test setup file.

import { matchers } from '@your-username/custom-matchers'

expect.extend(matchers)

Now you can use the custom matchers in your tests.

Example Matchers

toContainRole

Check if a container contains a specific number of elements with a given role.

test('should contain the specified role', () => {
  const container = render(<MyComponent />)
  expect(container).toContainRole('button', 2) // Expects 2 buttons in the DOM
})

toHaveText

Check if a container has the specified text content.

test('should contain the expected text', () => {
  const container = render(<MyComponent />)
  expect(container).toHaveText('Submit') // Expects the text 'Submit' to be present
})

Available Matchers

1. toContainRole(container, role, quantity = 1)

Asserts whether the container has a specific number of elements with the provided role.

Parameters:

• container: The DOM element or container to search within.
• role: The ARIA role to search for (e.g., button, textbox).
• quantity: The number of elements with the specified role (default: 1).

Example:

expect(container).toContainRole('button', 2)

2. toHaveText(container, expectedText)

Asserts whether the container contains the specified text.

Parameters:

• container: The DOM element or container to search within.
• expectedText: The expected text to be found.

Example:

expect(container).toHaveText('Hello World')

Writing Your Own Matchers

You can add more matchers by following the pattern in src/matchers/. Each matcher function should return an object with a pass boolean indicating whether the test passed, and an optional message function to provide a descriptive error message if the test fails.

Example Custom Matcher

export function toBeCustom(value) {
  const pass = value === 'custom'
  return {
    pass,
    message: () =>
      pass ? `Expected value not to be custom` : `Expected value to be custom`,
  }
}

Development

Running Tests

To run tests for the matchers, use either Vitest or Jest:

# With Vitest
npm run test

# With Jest
npm run jest

Adding New Matchers

1. Create a new file in the src/matchers/ directory.
2. Write the matcher function and export it.
3. Add tests for the matcher in the tests/ directory.

Building the Library

If you're using Vite or Rollup for building the library, simply run:

npm run build

This will bundle your matchers for use in other projects.

Contributing

Contributions are welcome! Please follow the contribution guidelines outlined in the CONTRIBUTING.md file.

License

This project is licensed under the MIT License - see the LICENSE file for details.