vite-plugin-vue-testid 1.1.0 → 1.1.2

package/README.en.md

@@ -1,377 +0,0 @@
-# vite-plugin-vue-testid
-
-A Vite plugin that auto-injects `data-testid` into Vue component templates via compile-time + runtime transforms, tailored for ant-design-vue 4.x. Dramatically reduces the effort of locating elements in E2E tests.
-
-## Features
-
-- **Compile-time injection** — Automatically adds `data-testid` to component templates via Vue compiler `nodeTransform`
-- **Runtime injection** — Dynamically injects testIds into ant-design-vue teleported overlays (DatePicker, Cascader, Select, TreeSelect, etc.)
-- **`<a-table>` support** — bodyCell slot components receive unique testIds in the format `columnName + rowIndex + componentName + counter`
-- **Auto index destructuring** — If `#bodyCell="{ column, record }"` is missing `index`, the plugin patches it automatically
-- **Preserves existing testIds** — Elements with manually assigned `data-testid` are skipped
-- **Dual injection for teleport components** — DatePicker / RangePicker / Modal receive both `id` + `data-testid`
-- **Date panel mode awareness** — date / month / year / decade panels are distinguished automatically
-- **MutationObserver re-injection** — New DOM elements from panel switching, tree node expand/collapse are detected and injected automatically
-- **Extensible** — Custom component lists, testId generation rules, and overlay injection strategies are supported
-
----
-
-## Installation
-
-```bash
-pnpm add -D vite-plugin-vue-testid
-```
-
-> Requirements: `vite >= 5.0.0`, `vue >= 3.3.0`, `@vue/compiler-core >= 3.5.0`
-
----
-
-## Quick Start
-
-### 1. Compile-time injection (`vite.config.ts`)
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import { createVueTestIdTransform } from 'vite-plugin-vue-testid'
-
-export default defineConfig({
-  plugins: [
-    vue({
-      template: {
-        compilerOptions: {
-          nodeTransforms: [createVueTestIdTransform()]
-        }
-      }
-    })
-  ]
-})
-```
-
-### 2. Runtime injection (`main.ts`)
-
-```ts
-// main.ts
-import { createApp } from 'vue'
-import App from './App.vue'
-import { setupAntDropdownTestIds } from 'vite-plugin-vue-testid/runtime'
-
-const app = createApp(App)
-app.mount('#app')
-
-// Call after mount to observe teleported panels and auto-inject testIds
-setupAntDropdownTestIds()
-```
-
----
-
-## Generated testId Examples
-
-### Regular Components
-
-```html
-<!-- Source -->
-<a-input />
-<a-select />
-<a-button />
-
-<!-- Compiled -->
-<a-input data-testid="a-input-0" />
-<a-select data-testid="a-select-1" />
-<a-button data-testid="a-button-2" />
-```
-
-### Teleport Components (Dual Injection)
-
-```html
-<!-- Source -->
-<a-date-picker />
-<a-modal v-model:visible="show" title="Notice" />
-
-<!-- Compiled -->
-<a-date-picker id="a-date-picker-0" data-testid="a-date-picker-0" />
-<a-modal id="a-modal-1" data-testid="a-modal-1" />
-```
-
-### `<a-table>` bodyCell Components
-
-```
-Format: ${column.dataIndex}-${index}-${componentName}-${counter}
-
-Examples:
-- label-0-a-input-4    (label column, row 0)
-- value-2-a-input-5    (value column, row 2)
-```
-
-### Runtime DatePicker Panel
-
-```
-a-date-picker-0-dropdown                    # panel container
-a-date-picker-0-dropdown-prev               # previous month
-a-date-picker-0-dropdown-next               # next month
-a-date-picker-0-dropdown-header-date        # header container
-a-date-picker-0-dropdown-header-month-btn   # header month button
-a-date-picker-0-dropdown-header-year-btn    # header year button
-a-date-picker-0-dropdown-date-2026-06-15    # date cell
-a-date-picker-0-dropdown-ok                 # OK button
-```
-
-After switching to month/year panel (auto re-injected by MutationObserver):
-
-```
-a-date-picker-0-dropdown-header-month       # month panel header
-a-date-picker-0-dropdown-month-06           # June
-a-date-picker-0-dropdown-header-year        # year panel header
-a-date-picker-0-dropdown-year-2026          # year 2026
-a-date-picker-0-dropdown-decade-2020-2029   # decade 2020-2029
-```
-
-### Runtime RangePicker Panel
-
-```
-a-range-picker-0-dropdown-prev-left              # left panel prev month
-a-range-picker-0-dropdown-date-2026-05-15-left   # left panel date
-a-range-picker-0-dropdown-date-2026-06-20-right  # right panel date
-```
-
-### Runtime TimePicker
-
-```
-a-time-picker-0-dropdown-time-column-0      # hour column
-a-time-picker-0-dropdown-time-08            # 08 hour
-a-time-picker-0-dropdown-time-column-1      # minute column
-a-time-picker-0-dropdown-time-30            # 30 minutes
-```
-
-### Runtime Cascader
-
-```
-a-cascader-0-dropdown                       # panel container
-a-cascader-0-dropdown-menu-0                # level 1 menu
-a-cascader-0-dropdown-item-Zhejiang         # Zhejiang option
-a-cascader-0-dropdown-menu-1                # level 2 menu
-a-cascader-0-dropdown-item-Hangzhou         # Hangzhou option
-```
-
-### Runtime Select
-
-```
-a-select-0-dropdown                         # dropdown container
-a-select-0-dropdown-option-Option1          # option
-a-select-0-dropdown-option-Option2          # option
-```
-
-### Runtime TreeSelect
-
-```
-a-tree-select-0-dropdown                          # dropdown container
-a-tree-select-0-dropdown-tree-root-1              # root node
-a-tree-select-0-dropdown-tree-switcher-expand-root-1   # expand icon (collapsed)
-a-tree-select-0-dropdown-tree-switcher-collapse-root-1 # expand icon (expanded)
-a-tree-select-0-dropdown-tree-parent-1            # parent node (injected after expand)
-a-tree-select-0-dropdown-tree-my-leaf             # leaf node
-```
-
-### Compile-time + Runtime Menu
-
-```
-a-menu-0                          # menu container (compile-time)
-a-menu-item-Menu-Item-1           # menu item (runtime, text-based)
-a-menu-item-Sub-Item-3            # submenu item
-a-sub-menu-Submenu                # submenu (runtime)
-a-menu-item-group-Group           # menu item group (runtime)
-```
-
----
-
-## Configuration
-
-### Compile-time Options
-
-```ts
-import { createVueTestIdTransform } from 'vite-plugin-vue-testid'
-
-createVueTestIdTransform({
-  /**
-   * Component tag names to inject testIds into (kebab-case)
-   * @default see "Default Supported Components" below
-   */
-  components: ['a-input', 'a-select', 'my-button'],
-
-  /**
-   * Custom testId generation function
-   * @param tagName  component tag name
-   * @param count    global increment counter
-   * @returns testId string
-   */
-  generateId: (tagName, count) => `myapp-${tagName}-${count}`,
-
-  /**
-   * testId attribute name (use 'data-cy' for Cypress)
-   * @default 'data-testid'
-   */
-  attributeName: 'data-cy',
-
-  /**
-   * Components that also receive an id attribute
-   * @default ['a-date-picker', 'a-range-picker', 'a-time-picker', 'a-modal']
-   */
-  idComponents: ['a-date-picker', 'a-modal'],
-
-  /**
-   * id attribute name
-   * @default 'id'
-   */
-  idAttributeName: 'id',
-})
-```
-
-### Runtime Options
-
-```ts
-import { setupAntDropdownTestIds } from 'vite-plugin-vue-testid/runtime'
-
-// Default config
-const cleanup = setupAntDropdownTestIds()
-
-// Custom config
-const cleanup = setupAntDropdownTestIds({
-  /**
-   * testId attribute name, must match compile-time config
-   * @default 'data-testid'
-   */
-  attributeName: 'data-testid',
-
-  /**
-   * Custom panel selector → injection strategy mapping
-   * key: CSS selector
-   * value: injection function; set to undefined to disable a built-in panel
-   */
-  panels: {
-    '.ant-picker-dropdown': undefined,                     // disable built-in Picker panel injection
-    '.my-custom-dropdown': (ctx) => {
-      // ctx.container     — panel container HTMLElement
-      // ctx.trigger       — trigger HTMLElement | null
-      // ctx.triggerTestId — the trigger's testId value
-      // ctx.attrName      — testId attribute name
-      const prefix = `${ctx.triggerTestId}-dropdown`
-      ctx.container.setAttribute(ctx.attrName, prefix)
-      // ... custom injection logic
-    },
-  },
-})
-
-// Clean up observer on component unmount
-onUnmounted(cleanup)
-```
-
-### One-off Manual Injection
-
-```ts
-import { injectCurrentDropdowns } from 'vite-plugin-vue-testid/runtime'
-
-// For SSR / hydration scenarios where MutationObserver is not desired
-injectCurrentDropdowns({ attributeName: 'data-testid' })
-```
-
----
-
-## Default Supported Components
-
-| Component | Compile-time | Runtime |
-|-----------|:------------:|:-------:|
-| `a-input` | ✅ | — |
-| `a-textarea` | ✅ | — |
-| `a-input-number` | ✅ | — |
-| `a-select` | ✅ | ✅ dropdown |
-| `a-cascader` | ✅ | ✅ cascader panel |
-| `a-tree-select` | ✅ | ✅ tree select panel |
-| `a-radio-group` | ✅ | — |
-| `a-checkbox-group` | ✅ | — |
-| `a-date-picker` | ✅ id+testid | ✅ date panel |
-| `a-range-picker` | ✅ id+testid | ✅ dual panel |
-| `a-time-picker` | ✅ id+testid | ✅ time panel |
-| `a-switch` | ✅ | — |
-| `a-slider` | ✅ | — |
-| `a-rate` | ✅ | — |
-| `a-upload` | ✅ | — |
-| `a-form-item` | ✅ | — |
-| `a-button` | ✅ | — |
-| `a-modal` | ✅ id+testid | — |
-| `a-menu` | ✅ | — |
-| `a-menu-item` | ✅ id | 🔧 runtime (text) |
-| `a-sub-menu` | ✅ id | 🔧 runtime (text) |
-| `a-menu-item-group` | ✅ id | 🔧 runtime (text) |
-
----
-
-## Custom Panel Injection Strategies
-
-Support overlays from other UI libraries by providing custom strategies:
-
-```ts
-import type { PanelInjectStrategy } from 'vite-plugin-vue-testid/runtime'
-
-// Example: inject testIds into Element Plus overlays
-const injectElDropdown: PanelInjectStrategy = (ctx) => {
-  const { container, triggerTestId, attrName } = ctx
-  const prefix = `${triggerTestId}-dropdown`
-
-  container.setAttribute(attrName, prefix)
-
-  container.querySelectorAll('.el-select-dropdown__item').forEach((item) => {
-    const el = item as HTMLElement
-    const text = el.textContent?.trim() || ''
-    el.setAttribute(attrName, `${prefix}-option-${text}`)
-  })
-}
-
-setupAntDropdownTestIds({
-  panels: {
-    '.el-select-dropdown': injectElDropdown,
-    '.el-cascader-dropdown': injectElDropdown,
-  },
-})
-```
-
----
-
-## API Reference
-
-### Compile-time
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `createVueTestIdTransform(opts?)` | `(node: RootNode \| TemplateChildNode) => void` | Creates a Vue compiler nodeTransform |
-| `VueTestIdTransformOptions` | `interface` | Compile-time options type |
-
-### Runtime (`/runtime` subpath)
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `setupAntDropdownTestIds(opts?)` | `() => void` | Starts MutationObserver to auto-inject overlay testIds, returns cleanup function |
-| `injectCurrentDropdowns(opts?)` | `void` | One-off manual injection of currently visible overlays |
-| `RuntimeOptions` | `interface` | Runtime options type |
-| `PanelContext` | `interface` | Panel injection context type |
-| `PanelInjectStrategy` | `(ctx: PanelContext) => void` | Panel injection strategy function type |
-
----
-
-## How It Works
-
-### Compile-time
-
-Uses Vue's compiler `nodeTransform` hook to traverse template nodes at AST stage. When target component tags are matched, `data-testid` attribute nodes are appended directly. Since injection happens at compile time, there is zero runtime performance impact.
-
-### Runtime
-
-ant-design-vue 4.x components like DatePicker, Select, and Cascader use Teleport to render overlays into `document.body`, making them unreachable at compile time. The runtime module uses `MutationObserver` to watch DOM changes under `body`, matches ant-design panel CSS classes, and automatically injects trigger-associated testIds into panel elements.
-
-For components like DatePicker with `inheritAttrs: false`, `data-testid` injected at compile time cannot reach the DOM. The plugin works around this by also injecting an `id` attribute (which ant-design-vue explicitly forwards to the internal `<input>`) as a fallback identifier.
-
----
-
-## License
-
-MIT