Layup ID Injector

A tool to automatically inject stable, unique IDs into React components for testing purposes.

Installation

npm install --save-dev @layuplabs/layup-autoid

Local Development

To use the package locally during development:

1. Clone the repository and install dependencies:

git clone https://github.com/layuplabs/layup-autoid.git
cd layup-autoid
npm install

2. Link the package locally:

npm link

3. In your project directory, link to the local package:

npm link layup-autoid

Now you can use the package in your project as if it were installed from npm. Any changes you make to the source code will be immediately reflected in your project.

layup-autoid

To unlink the package when you're done:

# In your project directory
npm unlink layup-autoid

# In the layup-autoid directory
npm unlink

Usage

Command Line

You can run the injector on your entire project:

npx @layuplabs/layup-autoid

You can specify a specific path to search within:

npx @layuplabs/layup-autoid --path src
# or with short flag
npx @layuplabs/layup-autoid -p packages/my-package

Pre-commit Hook

To automatically run the injector on modified files before each commit:

1. Install the package:

npm install --save-dev @layuplabs/layup-autoid

2. Initialize husky:

npm run prepare

3. Add the pre-commit hook:

npx husky add .husky/pre-commit "npx @layuplabs/layup-autoid --staged"

Programmatic Usage

const { injectIdsInFile, setCustomElements, setIgnoreDefaults, setIgnorePaths, setRemoveTestIds } = require("@layuplabs/layup-autoid");

// Inject IDs in a single file
injectIdsInFile("path/to/your/component.jsx");

// Process with custom elements
setCustomElements(["ButtonCustom", "StyledSpan"]);
injectIdsInFile("path/to/your/component.jsx");

// Process only custom elements (ignoring default HTML elements)
setCustomElements(["ButtonCustom", "StyledSpan"]);
setIgnoreDefaults(true);
injectIdsInFile("path/to/your/component.jsx");

// Ignore specific paths when processing
setIgnorePaths(["src/ignored-dir", "src/another-ignored-dir"]);
injectIdsInFile("path/to/your/component.jsx");

// Remove data-testid attributes instead of adding them
setRemoveTestIds(true);
injectIdsInFile("path/to/your/component.jsx");

// Or process multiple files
const glob = require("glob");
const files = glob.sync("src/**/*.{js,jsx,ts,tsx}");
files.forEach(injectIdsInFile);

What it does

The tool scans your React components and automatically adds unique data-testid attributes to standard HTML elements that don't already have one. With the new custom elements feature, it can also process your custom components (like ButtonCustom or StyledDiv). This makes it easier to write stable end-to-end tests.

You can also use the tool to remove data-testid attributes from your components. This is useful when you want to clean up your components or when you want to regenerate all IDs.

Example:

// Before
<div className="container">
  <span>Hello World</span>
  <ButtonCustom>Custom Button</ButtonCustom>
</div>

// After
<div className="container" data-testid="auto-id-123e4567-e89b-12d3-a456-426614174000">
  <span data-testid="auto-id-987fcdeb-a89b-12d3-a456-426614174001">Hello World</span>
  <ButtonCustom data-testid="auto-id-456fcded-a45b-78d9-c321-987654321002">Custom Button</ButtonCustom>
</div>

Configuration

Command Line Options

• --staged: Only process files that are staged in git
• --path or -p: Specify a starting path for file search (e.g., --path src or -p packages/my-package)
• --custom-elements or -c: Specify a JSON array of custom component names to process (e.g., --custom-elements '["ButtonCustom", "StyledSpan"]')
• --ignore-defaults or -i: Ignore the default HTML elements and only process custom elements (requires --custom-elements to be provided)
• --ignore-path or -ip: Specify a path to ignore when processing files (e.g., --ignore-path src/ignored-dir)
• --remove or -r: Remove data-testid attributes instead of adding them (works with all other options)

Default Behavior

By default, the tool will:

• Process all .js, .jsx, .ts, and .tsx files in your project
• Skip files in node_modules, dist, and build directories
• Skip files in paths specified with --ignore-path
• Inject IDs into standard HTML elements
• Generate UUID v4 for each ID
• Process custom elements specified with the --custom-elements option
• Include standard HTML elements unless --ignore-defaults is specified
• Add data-testid attributes unless --remove is specified

License

ISC