creating-visual-test-examples - SKILL.md Agent Skill

name: creating-visual-test-examples path: examples/** description: Use when creating standalone examples in examples/next/docs/ for visual regression testing or documentation demos - covers the Vite-based example structure, sample data patterns, and multi-feature demonstration

Creating Visual Test Examples

This skill covers how to build standalone Vite-based examples in examples/next/docs/. These examples serve as both visual regression test targets and live documentation demos.

Example Location

All standalone demos live under examples/next/docs/js/. Each demo gets its own directory (e.g., examples/next/docs/js/demo/).

Directory Structure

examples/next/docs/js/demo/
  index.html          # Minimal HTML: just <div id="example"> and a script tag
  package.json        # Dependencies (handsontable, vite)
  vite.config.js      # Vite build configuration
  LICENSE.txt         # License file
  src/
    index.js          # Main entry - imports, registers, creates the grid
    constants.js      # Sample data arrays and configuration constants
    styles.css        # Custom styles for the demo
  spec/
    Smoke.spec.js     # Puppeteer smoke test

How to Build an Example

1. Import from handsontable/base and register explicitly. Do not use the full bundle. Import only the plugins, cell types, and features the demo needs:

import Handsontable from 'handsontable/base';
import { registerPlugin, ContextMenu, Filters } from 'handsontable/plugins';
import { registerCellType, NumericCellType } from 'handsontable/cellTypes';

registerPlugin(ContextMenu);
registerPlugin(Filters);
registerCellType(NumericCellType);

2. Demonstrate multiple features together. Unlike documentation examples (one concept each), visual test examples should combine several features in a single grid to verify they render correctly together. For example: column sorting + filters + dropdown menu + hidden columns + context menu.

3. Use comprehensive, realistic sample data. Extract data into src/constants.js. Use domain-appropriate content (company names, dates, currencies, countries) rather than placeholder strings. Aim for enough rows (20-50+) to demonstrate scrolling behavior.

4. Always include licenseKey: 'non-commercial-and-evaluation'.

5. Target the #example container defined in index.html.

Smoke Test

Every example must include a smoke test in spec/Smoke.spec.js. The smoke test launches Puppeteer, navigates to the dev server, and asserts that the grid rendered:

it('should render Handsontable', async () => {
  const hotCell = await page.$('.handsontable td');
  await expect(hotCell).toBeTruthy();
});

Use process.env.TEST_URL || 'http://localhost:8080' as the base URL.

Key Reference

See examples/next/docs/js/demo/src/index.js for a complete working example that registers plugins and cell types individually, configures column types, enables multiple features, and uses helper functions for sample data generation.