Imhotep/README.md

# 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