docs(tests): add tests/README.md and stable ForEach / LazyLoad / VirtualScroll tests by lucas-spin · Pull Request #24 · TypeComposer/typecomposer

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

lucas-spin · 2026-06-15T20:23:33Z

Summary

Closes two deferred roadmap items from PR #15:

tests/README.md — contributor documentation for the test suite.
tests/async-components.test.ts — stable tests for ForEach, LazyLoad, and VirtualScroll.

What's in each file

`tests/README.md`

Section	What it covers
Running tests	`npm run test` (watch) vs `npm run test:run` (CI)
Test structure	Every file in `tests/`, what each one tests
`tests/utils.ts` render helper	`render()` signature, auto-cleanup, example
`tests/setup.ts`	`MemoryStorage` polyfill, `beforeEach` storage clear
Assertion patterns	DOM structure, styles, reactivity, async flush
happy-dom layout limitations	Which APIs return 0 and how to avoid brittle tests
`vitest.config.ts` reference	Environment, globals, setupFiles
Adding new tests	Step-by-step checklist

`tests/async-components.test.ts`

ForEach (11 tests): custom element tag, empty innerHTML, item getter default, of setter/getAttribute round-trip, apply() no-throw and innerHTML-clear contract.

LazyLoad (11 tests): custom element tag, loader/loaderProps stored correctly, Component.lazyLoad spy asserts it is called with correct fallback/props on onConnected, not called when no loader provided.

VirtualScroll (13 tests, 1 skipped): custom element tag, inner container presence and position: relative, total height = items.length × itemHeight, overflow-y: auto, initial render slice under happy-dom (scrollTop=0 → buffer items), custom buffer, empty items, absolute positioning + px top + 100% width, renderItem factory call count, top = index × itemHeight, scroll event no-throw. Scroll-position windowing skipped with a note pointing to E2E.

Validation

npm run test:run
npx tsc --noEmit

Test Files 10 passed (10)
Tests 207 passed | 1 skipped (208)
Duration ~9s
tsc --noEmit: no errors

All pre-existing tests continue to pass.

Reviewers

@zico15

…croll tests - Add tests/README.md documenting npm run test, npm run test:run, the render() helper in tests/utils.ts, setup.ts behavior, and recommended assertion patterns including happy-dom limitations. - Add tests/async-components.test.ts covering: * ForEach: construction, attribute handling, apply() contract, and notes on why HTML-template rendering requires an HTML fixture (the #content capture is commented out in the current source). * LazyLoad: construction with and without loader, loaderProps storage, Component.lazyLoad invocation via the onConnected event path, and notes on why IntersectionObserver tests need a real browser. * VirtualScroll: construction, inner container height/position, overflow style, initial render slice under happy-dom (scrollTop=0 collapses the window to [0, buffer)), renderItem factory invocation, absolute positioning of rendered items, and a skipped describe block documenting the scroll-windowing tests deferred to E2E. All 209 tests pass; 1 test skipped with explanation.

…ise pattern comments

TypeComposer Contributorand others added 2 commits June 15, 2026 20:21

chore(tests): remove verbose limitation/explanation blocks, keep conc…
c7589b3
…ise pattern comments

joaodibba merged commit 0b8c361 into TypeComposer:mainJun 15, 2026
2 checks passed