@metagptx/vite-plugin-testid-checker/dist/README.md

A Vite plugin for testid checker

# @metagptx/vite-plugin-testid-checker

[![npm version](https://badge.fury.io/js/@metagptx%2Fvite-plugin-testid-checker.svg)](https://badge.fury.io/js/@metagptx%2Fvite-plugin-testid-checker)
 
A Vite plugin that checks for required attributes (like `data-testid`) on interactive elements in Vue and React/JSX files during the build process.

## Features

- 🔍 **Automatic Detection**: Identifies interactive elements that need test IDs
- 🚀 **Framework Support**: Works with Vue and React/JSX/TSX files
- ⚡ **Fast**: Built-in caching mechanism for optimal performance
- 🛠️ **Configurable**: Customize which attributes to check and which files to include/exclude
- 🎯 **Build-time Validation**: Catches missing test IDs before they reach production

## Installation

```bash
npm install @metagptx/vite-plugin-testid-checker --save-dev
```

or

```bash
pnpm add @metagptx/vite-plugin-testid-checker -D
```

or

```bash
yarn add @metagptx/vite-plugin-testid-checker --dev
```

## Usage

Add the plugin to your `vite.config.ts`:

```typescript
import { defineConfig } from 'vite'
import { vitePluginTestIdChecker } from '@metagptx/vite-plugin-testid-checker'

export default defineConfig({
  plugins: [
    vitePluginTestIdChecker({
      // Optional configuration
      attributes: ['data-testid'],
      include: ['src/**/*.{vue,jsx,tsx,js,ts}'],
      exclude: ['src/**/*.test.{js,ts,jsx,tsx}']
    })
  ]
})
```

## Configuration

The plugin accepts the following options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `attributes` | `string[]` | `['data-testid']` | Array of attribute names to check for |
| `include` | `string \| string[]` | `['src/**/*.{vue,jsx,tsx,js,ts}']` | Files to include (glob patterns) |
| `exclude` | `string \| string[]` | `[]` | Files to exclude (glob patterns) |

## What Elements Are Checked

The plugin checks for required attributes on the following interactive elements:

### HTML Elements
- `<a>` - Links
- `<button>` - Buttons
- `<input>` - Input fields
- `<textarea>` - Text areas
- `<select>` - Select dropdowns
- `<option>` - Select options

### React/JSX Elements
Elements with event handlers (e.g., `onClick`, `onChange`, `onSubmit`, etc.)

### Vue Elements
Elements with the following Vue directives:
- `@click`
- `@change`
- `@input`
- `@focus`
- `@blur`
- `@mouseover`
- `@mouseout`
- `@mouseenter`
- `@mouseleave`
- `@mousemove`
- `@mouseup`
- `@mousedown`
- `@mousewheel`
- `@keydown`
- `@keyup`
- `@keypress`

## Examples

### Vue Example

❌ **This will cause a build error:**
```vue
<template>
  <button @click="handleClick">Click me</button>
</template>
```

✅ **This will pass:**
```vue
<template>
  <button @click="handleClick" data-testid="click-button">Click me</button>
</template>
```

### React/JSX Example

❌ **This will cause a build error:**
```jsx
function MyComponent() {
  return (
    <button onClick={handleClick}>Click me</button>
  );
}
```

✅ **This will pass:**
```jsx
function MyComponent() {
  return (
    <button onClick={handleClick} data-testid="click-button">Click me</button>
  );
}
```

### Custom Attributes

You can configure the plugin to check for custom attributes:

```typescript
vitePluginTestIdChecker({
  attributes: ['data-testid', 'data-cy', 'data-test']
})
```

Now the plugin will check for any of these attributes:

```jsx
// Any of these will pass:
<button onClick={handleClick} data-testid="button">Click</button>
<button onClick={handleClick} data-cy="button">Click</button>
<button onClick={handleClick} data-test="button">Click</button>
```

## Error Messages

When the plugin detects missing attributes, it will show descriptive error messages:

```
data-testid is required for button in src/components/Button.vue:15:8
data-testid is required for input in src/components/Form.tsx:22:12
```

## Build Integration

The plugin runs during the build process and will:

1. ✅ Pass silently if all interactive elements have required attributes
2. ❌ Throw an error and stop the build if any required attributes are missing

## Performance

The plugin includes built-in caching to ensure optimal performance:
- Files are cached based on their content hash
- Only changed files are re-processed
- Minimal impact on build times

## Requirements

- Node.js >= 14.0.0
- Vite ^3.0.0 || ^4.0.0 || ^5.0.0