Testing the Walkontable Rendering Engine
Paradigm note: Walkontable follows the same freeze as the main suite. It now has a Playwright home at tests/e2e/walkontable/ (which drives overlay / frozen-pane / scroll-sync behavior through a real grid — see tests/fixtures/pages/WalkontablePage.ts). So: maintenance edits to existing *.spec.js here are allowed; new or flaky walkontable tests move to Playwright (the presence gate blocks a new walkontable *.spec.js). In CI the legacy Jasmine/Puppeteer walkontable job and the Playwright e2e job run in parallel; walkontable migrates by attrition, worst/flakiest first. The guide below is for maintaining the frozen Jasmine specs.
Separate Test Pipeline
Walkontable has its own dedicated test runner. Do NOT run Walkontable tests through the main test:e2e or test:unit commands -- they will not be picked up.
- Run command:
npm run test:walkontable --prefix handsontable
- Test location:
src/3rdparty/walkontable/test/
The directory contains two sub-pipelines:
test/spec/ -- E2E-style specs (Jasmine + Puppeteer, same as main E2E but with a separate Rspack config and bootstrap)test/unit/ -- Unit-style specs for calculators, filters, renderers, and utilities
Writing Tests
The same async/await rules that apply to main E2E tests apply here. All it() callbacks that call rendering APIs must be async, and those API calls must be await-ed.
Tests are organized by subsystem: overlay/, scroll/, selection/, renderer/, table/, viewport.spec.js, etc. Place new tests in the directory that matches the subsystem you are modifying.
What to Cover
- Frozen rows and columns: The overlay system (6 overlay types) is the most fragile part of Walkontable. Always include tests with frozen rows/columns to catch overlay positioning and synchronization regressions.
- Viewport calculations: Test with various container sizes (small containers that clip content, containers larger than the data, and containers that resize dynamically).
- Scroll synchronization: Verify that scrolling the main table keeps frozen overlays aligned. Test both horizontal and vertical scroll.
- Large datasets: Include performance-oriented tests with 10k+ rows. Use
forEach loops to populate data arrays -- never arr.push(...largeArray).
Common Mistakes
- Running Walkontable tests via
test:e2e -- they have their own command and will not execute.
- Skipping frozen row/column scenarios -- this misses the overlay edge cases where most regressions occur.
- Testing only small datasets -- Walkontable bugs often surface at scale.
- Modifying Walkontable test bootstrap/Rspack config without verifying that both
spec/ and unit/ sub-pipelines still pass.
- Clearing an inline overflow longhand with jQuery:
$el.css('overflow-x', '') does not clear an inline overflow-x in this harness, so the "clip removed" branch of a spec keeps the clip and asserts against the wrong layout. Write el.style.overflowX = '' on the element and assert the intermediate fact (getComputedStyle(el).overflowX === 'visible') before the behavior.
- Trusting the spec count. Until the bridge reporter sanitized failed expectations (
test/helpers/jasmine-bridge-reporter.js), a failing spec whose expected or actual was a cyclic object (toBe(window), toEqual([overlay, …])) could not cross the Puppeteer bridge and was dropped from the run: Running 16 specs. in --verbose mode, 15 specs, 0 failures at the end, exit code 0. The getOverlays spec sat in that state from #12951 on. The bridge now reports such a spec as a normal failure with the value described ([unserializable Window]); if a count ever comes up short again, compare the Running N specs. line against the summary line with npm run test:walkontable -- --testPathPattern=<file> --verbose.
- Turning on the uniform-size flags (
rowHeightsUniform/columnWidthsUniform) in a bare Walkontable spec and then asserting scrollbar-dependent row/column counts: the bare harness overflows content without rendering a real scrollbar, while the single-pass layout snapshot predicts one — so predicted and measured diverge there. Assert the snapshot booleans directly, or use a fixture that renders a real scrollbar; don't compare snapshot-predicted scrollbars/counts against the bare DOM.
1---2name: walkontable-testing3description: Use when writing tests for the Walkontable rendering engine - has its own separate test pipeline, runner, and configuration distinct from main Handsontable E2E tests4---56# Testing the Walkontable Rendering Engine78> **Paradigm note:** Walkontable follows the **same freeze** as the main suite. It now has a **Playwright home** at `tests/e2e/walkontable/` (which drives overlay / frozen-pane / scroll-sync behavior through a real grid — see `tests/fixtures/pages/WalkontablePage.ts`). So: **maintenance edits to existing `*.spec.js` here are allowed; new or flaky walkontable tests move to Playwright** (the presence gate blocks a new walkontable `*.spec.js`). In CI the legacy Jasmine/Puppeteer walkontable job and the Playwright e2e job run **in parallel**; walkontable migrates by attrition, worst/flakiest first. The guide below is for *maintaining* the frozen Jasmine specs.910## Separate Test Pipeline1112Walkontable has its own dedicated test runner. Do NOT run Walkontable tests through the main `test:e2e` or `test:unit` commands -- they will not be picked up.1314- **Run command:** `npm run test:walkontable --prefix handsontable`15- **Test location:** `src/3rdparty/walkontable/test/`1617The directory contains two sub-pipelines:1819- `test/spec/` -- E2E-style specs (Jasmine + Puppeteer, same as main E2E but with a separate Rspack config and bootstrap)20- `test/unit/` -- Unit-style specs for calculators, filters, renderers, and utilities2122## Writing Tests2324The same async/await rules that apply to main E2E tests apply here. All `it()` callbacks that call rendering APIs must be `async`, and those API calls must be `await`-ed.2526Tests are organized by subsystem: `overlay/`, `scroll/`, `selection/`, `renderer/`, `table/`, `viewport.spec.js`, etc. Place new tests in the directory that matches the subsystem you are modifying.2728## What to Cover2930- **Frozen rows and columns:** The overlay system (6 overlay types) is the most fragile part of Walkontable. Always include tests with frozen rows/columns to catch overlay positioning and synchronization regressions.31- **Viewport calculations:** Test with various container sizes (small containers that clip content, containers larger than the data, and containers that resize dynamically).32- **Scroll synchronization:** Verify that scrolling the main table keeps frozen overlays aligned. Test both horizontal and vertical scroll.33- **Large datasets:** Include performance-oriented tests with 10k+ rows. Use `forEach` loops to populate data arrays -- never `arr.push(...largeArray)`.3435## Common Mistakes3637- Running Walkontable tests via `test:e2e` -- they have their own command and will not execute.38- Skipping frozen row/column scenarios -- this misses the overlay edge cases where most regressions occur.39- Testing only small datasets -- Walkontable bugs often surface at scale.40- Modifying Walkontable test bootstrap/Rspack config without verifying that both `spec/` and `unit/` sub-pipelines still pass.41- Clearing an inline overflow longhand with jQuery: `$el.css('overflow-x', '')` does not clear an inline `overflow-x` in this harness, so the "clip removed" branch of a spec keeps the clip and asserts against the wrong layout. Write `el.style.overflowX = ''` on the element and assert the intermediate fact (`getComputedStyle(el).overflowX === 'visible'`) before the behavior.42- Trusting the spec count. Until the bridge reporter sanitized failed expectations (`test/helpers/jasmine-bridge-reporter.js`), a failing spec whose `expected` or `actual` was a cyclic object (`toBe(window)`, `toEqual([overlay, …])`) could not cross the Puppeteer bridge and was dropped from the run: `Running 16 specs.` in `--verbose` mode, `15 specs, 0 failures` at the end, exit code 0. The `getOverlays` spec sat in that state from #12951 on. The bridge now reports such a spec as a normal failure with the value described (`[unserializable Window]`); if a count ever comes up short again, compare the `Running N specs.` line against the summary line with `npm run test:walkontable -- --testPathPattern=<file> --verbose`.43- Turning on the uniform-size flags (`rowHeightsUniform`/`columnWidthsUniform`) in a bare Walkontable spec and then asserting scrollbar-dependent row/column counts: the bare harness overflows content without rendering a real scrollbar, while the single-pass layout snapshot predicts one — so predicted and measured diverge there. Assert the snapshot booleans directly, or use a fixture that renders a real scrollbar; don't compare snapshot-predicted scrollbars/counts against the bare DOM.
handsontable