OpenParable
Skip to content
← Back to skills

Creating Visual Test Examples

Development
creating-visual-test-examples

Creating Visual Test Examples is an Agent Skill for development published in the handsontable/handsontable repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/handsontable/handsontable/blob/HEAD/.claude/skills/creating-visual-test-examples/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/creating-visual-test-examples, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.