John Dvorak
dd64e1e34a
Root package: renamed to imhotep-monorepo, fixed broken scripts (test:unit/integration/e2e), removed inappropriate root deps, fixed build order, updated clean script CI: branch trigger main->master, npm ci->npm install, GitHub cache URL->Gitea Docs: replaced scaffolded root README with real project README, added package READMEs for imhotep/imhotep-playwright/imhotep-dsl/imhotep-core, added RELEASE.md checklist Version: all 14 packages and root aligned to 1.1.0, CHANGELOG test count fixed (1125) Metadata: 14 repository URLs github->gitea, 13 package descriptions added, imhotep-cli exports field added, SECURITY.md updated for Gitea+disclosure email Quality: noEmitOnError:true in 13 tsconfigs, collapsed duplicate interfaces in public.ts, clippedBy test->test.skip, fixed broken dynamic import in imhotep index.test.ts, 694 generated src artifacts cleaned, V8 logs removed, .gitignore updated
123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
# 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.
|
|
|
|
```typescript
|
|
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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
npm test
|
|
```
|
|
|
|
### Key commands
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
npm test -w imhotep-dsl
|
|
npm test -w imhotep-playwright
|
|
npx playwright test --config packages/imhotep-fixtures/playwright.config.ts
|
|
```
|
|
|
|
## Assertion Styles
|
|
|
|
**Fluent API:**
|
|
```typescript
|
|
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:**
|
|
```typescript
|
|
ui.spec('.button leftOf .icon gap 8px');
|
|
ui.spec('all .card centeredWithin .container');
|
|
ui.spec('forall $c in .card: $c width >= 200');
|
|
```
|
|
|
|
**Property-based:**
|
|
```typescript
|
|
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
|