Imhotep

Declarative, relational UI testing for web applications. Imhotep lets you express spatial, semantic, dimensional, and property-based layout assertions using a fluent API or a dense DSL, then evaluates them through browser geometry extraction and a first-order logic solver.

import { imhotep } from 'imhotep';

const ui = await imhotep(page);
ui.expect('.header').to.be.above('.content', { minGap: 16 });
ui.expect('button').to.be.atLeast('44px').tall;
const result = await ui.checkAll();
// result.passed, result.diagnostics, result.normalizedContracts

Packages

Package	Purpose
imhotep	Meta-package bundling the full public API
imhotep-core	Types, AST/IR definitions, diagnostics, contracts, canonical lowering
imhotep-dsl	Fluent API, dense DSL parser, FOL compiler, validator
imhotep-solver	Constraint solver with directional relations, gap/alignment/size predicates
imhotep-playwright	Playwright integration, page wrapping, runtime pooling, property runners
imhotep-extractor	DOM/geometry extraction and fact planning
imhotep-cdp	Chrome DevTools Protocol session management and DOM queries
imhotep-reporter	Diagnostic formatting, failure analysis, replay, shrinking
imhotep-geometry	Bounding-box computation, rect algebra, transform math
imhotep-topology	Stacking contexts, transform-aware evaluation, formatting contexts
imhotep-state	ARIA and native element state materialization
imhotep-fixtures	E2E test harness, fixture pages, Playwright test suite
imhotep-cli	Scaffolding CLI with framework presets
imhotep-bench	Performance benchmarks and profiling tools

Quick Start (Consumer)

npm install imhotep
npx imhotep init --preset react
npx playwright install chromium
npm test

Available presets: react, vue, storybook, next, nuxt, remix, astro.

Development (Contributor)

npm install
npm run build
npm test

Key commands

npm run lint                    # ESLint across all packages
npm run typecheck               # tsc --noEmit on every workspace
npm run build                   # Compile all 14 packages in dependency order
npm test                        # Unit tests across all workspaces
npm run test:e2e                # Playwright E2E suite (215 tests)
npm run test:integration        # Integration tests (pooling, property runner)
npm run test:external-smoke     # Full smoke in a clean temp directory
npm run clean                   # Remove dist, tsbuildinfo, and generated src artifacts

Targeted runs

npm test -w imhotep-dsl
npm test -w imhotep-playwright
npx playwright test --config packages/imhotep-fixtures/playwright.config.ts

Assertion Styles

Fluent API:

ui.expect('.button').to.be.leftOf('.icon', { minGap: 8 });
ui.expect('.button').to.be.atLeast('44px').tall;
ui.expect.all('.card').to.be.centeredWithin('.container');

Dense DSL:

ui.spec('.button leftOf .icon gap 8px');
ui.spec('all .card centeredWithin .container');
ui.spec('forall $c in .card: $c width >= 200');

Property-based:

const fixture = imhotepFixture('grid.html');
await fixture.forAllProps(page, buttonDomain, async (scene, { width, label }) => {
  scene.expect('[data-testid="btn"]').to.be.atLeast(`${width}px`).wide;
});

Diagnostics

Every assertion failure produces structured diagnostics with error codes, measured geometry, expected/observed comparisons, source references, and fix hints. Failing checks never pass silently.

Category	Prefix
Parse	IMH_PARSE_*
Validation	IMH_VALID_*
Extraction	IMH_EXTRACT_*, IMH_SELECTOR_*
Relation	IMH_RELATION_*
Size	IMH_SIZE_*
Cardinality	IMH_CARDINALITY_*
Logic	IMH_LOGIC_*

Requirements

• Node.js >= 18
• npm >= 9
• Chromium (auto-installed via Playwright)

CDP extraction requires a local Chromium-based browser session. Remote/debugging protocol access is not enabled by default.

License

MIT