@sudobility/testomniac_runner 0.0.128

package/plans/DATA.md

@@ -0,0 +1,703 @@
+# Testomniac Data Model
+
+## Entity Hierarchy
+
+```text
+Entity (organization)
+ └── Product
+      ├── Runner
+      │    ├── Test Suite Bundle ── uid?
+      │    │    └── Test Suite Bundle ↔ Test Suite (junction)
+      │    ├── Test Suite ── uid?
+      │    │    └── Test Case ── uid?
+      │    ├── Scaffold
+      │    ├── Page
+      │    │    └── Page State
+      │    │         ├── Page State Scaffold (junction)
+      │    │         └── Page State Pattern
+      │    └── Element Identity
+      ├── Persona
+      │    └── Use Case
+      │         └── Input Value
+      ├── Test Credential
+      ├── Test Environment
+      ├── Product Settings
+      ├── API Key
+      └── Test File
+```
+
+## Execution Hierarchy
+
+```text
+Test Run ── runner, discovery, scanUrl, sizeClass, runnerInstanceId
+ ├── → Test Suite Bundle Run
+ │    └── Test Suite Run
+ │         └── Test Case Run ── expectedOutcome, observedOutcome
+ │              └── Test Run Finding
+ ├── → Test Suite Run
+ │    └── Test Case Run
+ │         └── Test Run Finding
+ └── → Test Case Run
+      └── Test Run Finding
+```
+
+A Test Run points to exactly one of: Test Case Run, Test Suite Run, or Test Suite Bundle Run.
+
+---
+
+## Persisted Objects
+
+### Entity
+
+Managed by `@sudobility/entity_service`. Represents an organization.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | UUID | PK |
+
+### Product
+
+A software product owned by an entity.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| entityId | TEXT | Owning entity |
+| title | TEXT | NOT NULL |
+| description | TEXT | |
+| contactEmail | TEXT | |
+| claimedByUserId | TEXT | Firebase uid of claimer |
+| claimedAt | TIMESTAMPTZ | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+| updatedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Runner
+
+A target application under a product. Each runner represents a specific app to test.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| productId | BIGSERIAL | FK → products, NOT NULL |
+| title | TEXT | NOT NULL |
+| type | TEXT | NOT NULL, DEFAULT 'worker'. Values: 'worker', 'extension' |
+| ownerEntityId | TEXT | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+---
+
+### Test Suite Bundle
+
+A user-created grouping of test suites. Links to test suites via a junction table.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners, NOT NULL |
+| title | TEXT | NOT NULL |
+| description | TEXT | |
+| uid | TEXT | **NEW** — Firebase uid of the developer who created it. NULL if created from website. |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+| updatedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+**Junction: test_suite_bundle_suites**
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| testSuiteBundleId | BIGSERIAL | FK → test_suite_bundles, NOT NULL, CASCADE DELETE |
+| testSuiteId | BIGSERIAL | FK → test_suites, NOT NULL, CASCADE DELETE |
+
+Unique index on (testSuiteBundleId, testSuiteId).
+
+### Test Suite
+
+A collection of test cases for a specific area of the application (a page, a scaffold, a pattern, etc.).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners, NOT NULL |
+| decompositionJobId | BIGSERIAL | Links to the AI job that created it |
+| title | TEXT | NOT NULL |
+| description | TEXT | NOT NULL |
+| startingPageStateId | BIGSERIAL | FK → page_states |
+| startingPath | TEXT | NOT NULL — relative URL path |
+| sizeClass | TEXT | NOT NULL, DEFAULT 'desktop'. Values: 'desktop', 'mobile' |
+| dependencyTestCaseId | BIGSERIAL | Test case that must pass before this suite runs |
+| personaIdsJson | JSONB | Array of persona IDs |
+| scaffoldId | BIGSERIAL | FK → scaffolds. Set if this suite tests a specific scaffold |
+| scaffoldType | TEXT | HtmlComponentType value (e.g., 'topMenu', 'footer') |
+| patternType | TEXT | UiPatternType value (e.g., 'form', 'table'). Set if testing a pattern |
+| priority | INTEGER | NOT NULL, DEFAULT 3 |
+| suiteTags | TEXT[] | NOT NULL, DEFAULT [] |
+| estimatedDurationMs | INTEGER | |
+| uid | TEXT | **NEW** — Firebase uid. NULL if created from website. |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Case
+
+An individual test scenario with steps and expectations.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners |
+| testSuiteId | BIGSERIAL | FK → test_suites |
+| title | TEXT | NOT NULL |
+| testType | TEXT | NOT NULL. Values: 'render', 'interaction', 'form', 'form_negative', 'password', 'navigation', 'e2e' |
+| sizeClass | TEXT | NOT NULL, DEFAULT 'desktop' |
+| suiteTags | TEXT[] | NOT NULL, DEFAULT [] |
+| priority | INTEGER | NOT NULL, DEFAULT 3 |
+| scaffoldId | BIGSERIAL | FK → scaffolds |
+| patternType | TEXT | |
+| dependencyTestCaseId | BIGSERIAL | Must pass before this case runs |
+| pageId | BIGSERIAL | FK → pages |
+| personaId | BIGSERIAL | FK → personas |
+| useCaseId | BIGSERIAL | FK → use_cases |
+| startingPageStateId | BIGSERIAL | FK → page_states |
+| startingPath | TEXT | Relative URL |
+| stepsJson | JSONB | Array of TestStep objects |
+| globalExpectationsJson | JSONB | Array of Expectation objects |
+| estimatedDurationMs | INTEGER | |
+| uid | TEXT | **NEW** — Firebase uid. NULL if created from website. |
+| generatedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### TestStep (embedded in stepsJson)
+
+```typescript
+{
+  action: TestAction;
+  expectations: Expectation[];
+  description: string;
+  continueOnFailure: boolean;
+}
+```
+
+### TestAction (embedded in TestStep)
+
+```typescript
+{
+  actionType: PlaywrightAction;    // 'goto', 'click', 'fill', 'hover', etc.
+  pageStateId?: number;
+  elementIdentityId?: number;
+  containerType?: HtmlComponentType;
+  containerElementIdentityId?: number;
+  value?: string;
+  path?: string;
+  playwrightCode: string;          // Actual Playwright code to execute
+  description: string;
+}
+```
+
+### Expectation (embedded in TestStep and globalExpectations)
+
+```typescript
+{
+  expectationType: ExpectationType;  // 'page_loaded', 'element_visible', 'no_console_errors', etc.
+  elementIdentityId?: number;
+  expectedValue?: string;
+  attributeName?: string;
+  severity: ExpectationSeverity;     // 'must_pass', 'should_pass', 'info'
+  description: string;
+  playwrightCode: string;
+}
+```
+
+---
+
+### Test Suite Bundle Run
+
+Execution record for a test suite bundle.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| testSuiteBundleId | BIGSERIAL | FK → test_suite_bundles, NOT NULL |
+| status | TEXT | NOT NULL, DEFAULT 'pending'. Values: 'pending', 'running', 'completed', 'failed' |
+| startedAt | TIMESTAMPTZ | |
+| completedAt | TIMESTAMPTZ | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Suite Run
+
+Execution record for a test suite.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| testSuiteId | BIGSERIAL | FK → test_suites, NOT NULL |
+| testSuiteBundleRunId | BIGSERIAL | FK → test_suite_bundle_runs. Set if this suite run is part of a bundle run. |
+| status | TEXT | NOT NULL, DEFAULT 'pending' |
+| startedAt | TIMESTAMPTZ | |
+| completedAt | TIMESTAMPTZ | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Case Run
+
+Execution record for a single test case.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| testCaseId | BIGSERIAL | FK → test_cases, NOT NULL |
+| testSuiteRunId | BIGSERIAL | FK → test_suite_runs. Set if this case run is part of a suite run. |
+| status | TEXT | NOT NULL, DEFAULT 'pending'. Values: 'pending', 'running', 'completed', 'failed' |
+| durationMs | INTEGER | |
+| errorMessage | TEXT | Error details if failed |
+| expectedOutcome | TEXT | **NEW** — Aggregated expected outcomes from expertises |
+| observedOutcome | TEXT | **NEW** — Aggregated observed outcomes from expertises |
+| screenshotPath | TEXT | Captured on warning/error |
+| consoleLog | TEXT | Captured on warning/error |
+| networkLog | TEXT | Captured on warning/error |
+| startedAt | TIMESTAMPTZ | |
+| completedAt | TIMESTAMPTZ | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Run
+
+Top-level run object. Represents a single invocation of the runner.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners, NOT NULL |
+| testCaseRunId | BIGSERIAL | FK → test_case_runs. Set if running a single test case. |
+| testSuiteRunId | BIGSERIAL | FK → test_suite_runs. Set if running a test suite. |
+| testSuiteBundleRunId | BIGSERIAL | FK → test_suite_bundle_runs. Set if running a bundle. |
+| testEnvironmentId | BIGSERIAL | **NEW** — FK → test_environments. Required. Specifies which environment this run targets. |
+| discovery | BOOLEAN | NOT NULL, DEFAULT FALSE. If true, auto-discover new test suites/cases. |
+| parentTestRunId | BIGSERIAL | FK → test_runs. For child runs. |
+| rootTestRunId | BIGSERIAL | FK → test_runs. Root of the run tree. |
+| sizeClass | TEXT | NOT NULL, DEFAULT 'desktop' |
+| status | TEXT | NOT NULL, DEFAULT 'pending'. Values: 'pending', 'planned', 'running', 'completed', 'failed' |
+| createdByUserId | TEXT | Firebase uid of the user who started the run |
+| ownedByUserId | TEXT | Firebase uid of the run owner |
+| runnerInstanceId | TEXT | **NEW** — UUID of the runner instance executing this run |
+| runnerInstanceName | TEXT | **NEW** — Human-readable name of the runner instance |
+| scanUrl | TEXT | Starting URL for the scan |
+| pagesFound | INTEGER | Stats |
+| pageStatesFound | INTEGER | Stats |
+| testRunsCompleted | INTEGER | Stats |
+| aiSummary | TEXT | AI-generated summary |
+| totalDurationMs | INTEGER | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+| startedAt | TIMESTAMPTZ | |
+| completedAt | TIMESTAMPTZ | |
+
+### Test Run Finding
+
+An issue discovered during a test case run.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| testCaseRunId | BIGSERIAL | FK → test_case_runs, NOT NULL |
+| expertiseRuleId | BIGSERIAL | FK → expertise_rules. Links to the rule that flagged it. |
+| type | TEXT | NOT NULL. Values: 'error', 'warning' |
+| title | TEXT | NOT NULL |
+| description | TEXT | NOT NULL |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+---
+
+### Page
+
+A URL path discovered under a runner.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners |
+| relativePath | TEXT | NOT NULL — URL path relative to base URL |
+| routeKey | TEXT | Normalized route key (e.g., `/users/:id`) |
+| requiresLogin | BOOLEAN | DEFAULT FALSE |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Page State
+
+A snapshot of a page at a point in time. Multiple states can exist per page (different viewports, different content).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| pageId | BIGSERIAL | FK → pages |
+| sizeClass | TEXT | NOT NULL, DEFAULT 'desktop' |
+| htmlHash | CHAR(64) | SHA-256 of raw HTML |
+| normalizedHtmlHash | CHAR(64) | SHA-256 of normalized HTML |
+| textHash | CHAR(64) | SHA-256 of visible text |
+| actionableHash | CHAR(64) | SHA-256 of actionable items |
+| fixedBodyHash | CHAR(64) | SHA-256 of body minus scaffolds and patterns |
+| scaffoldsHash | CHAR(64) | SHA-256 of scaffold type:hash pairs |
+| patternsHash | CHAR(64) | SHA-256 of pattern type:count pairs |
+| bodyHtmlElementId | BIGSERIAL | FK → html_elements |
+| contentHtmlElementId | BIGSERIAL | FK → html_elements |
+| fixedBodyHtmlElementId | BIGSERIAL | FK → html_elements |
+| screenshotPath | TEXT | |
+| rawHtmlPath | TEXT | |
+| contentText | TEXT | Extracted visible text |
+| createdByTestRunId | BIGSERIAL | Which test run captured this state |
+| capturedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Scaffold
+
+A detected reusable UI region (header, footer, nav, sidebar, etc.) that appears across multiple pages.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners, NOT NULL |
+| type | TEXT | NOT NULL. HtmlComponentType: 'topMenu', 'footer', 'breadcrumb', 'leftMenu', 'hamburgerMenu', 'rightSidebar', 'searchBar', 'userMenu', 'cookieBanner', 'chatWidget', 'socialLinks', 'skipNav', 'languageSwitcher', 'announcementBar', 'backToTop' |
+| htmlElementId | BIGSERIAL | FK → html_elements, NOT NULL |
+| htmlHash | CHAR(64) | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+Unique index on (runnerId, type, htmlElementId).
+
+**Junction: page_state_scaffolds**
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| pageStateId | BIGSERIAL | FK → page_states, NOT NULL |
+| scaffoldId | BIGSERIAL | FK → scaffolds, NOT NULL |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+Unique index on (pageStateId, scaffoldId).
+
+### Page State Pattern
+
+A detected UI pattern instance on a page state.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| pageStateId | BIGSERIAL | FK → page_states, NOT NULL |
+| patternType | TEXT | NOT NULL. UiPatternType: 'card', 'table', 'form', 'modal', 'toast', 'alert', 'tabs', 'accordion', 'carousel', 'dropdown', 'pagination', 'skeleton', 'emptyState', 'errorMessage', 'progressBar', 'tooltip', 'badge', 'avatar', 'tag', 'stepper' |
+| selector | TEXT | NOT NULL — CSS selector for the pattern |
+| count | INTEGER | NOT NULL, DEFAULT 0 — instance count on the page |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### HTML Element
+
+Deduplicated HTML content storage, referenced by scaffolds and page states.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| html | TEXT | NOT NULL — raw HTML markup |
+| hash | CHAR(64) | NOT NULL, UNIQUE — SHA-256 for deduplication |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Element Identity
+
+Persistent identity for an interactive element across scans. Allows stable references even when selectors change.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners, NOT NULL |
+| role | TEXT | NOT NULL — ARIA role |
+| computedName | TEXT | ARIA computed name |
+| tagName | TEXT | NOT NULL |
+| labelText | TEXT | |
+| groupName | TEXT | |
+| placeholder | TEXT | |
+| altText | TEXT | |
+| testId | TEXT | data-testid value |
+| inputType | TEXT | |
+| nthInGroup | INTEGER | Position in group |
+| formContext | TEXT | Parent form context |
+| headingContext | TEXT | Nearest heading |
+| landmarkAncestor | TEXT | Parent ARIA landmark |
+| playwrightLocator | TEXT | NOT NULL — primary locator string |
+| playwrightScopeChain | TEXT | Scoped locator chain |
+| isUniqueOnPage | BOOLEAN | NOT NULL, DEFAULT TRUE |
+| cssSelector | TEXT | NOT NULL — fallback CSS selector |
+| locators | JSONB | NOT NULL, DEFAULT [] — array of ElementLocator |
+| firstSeenTestRunId | BIGSERIAL | |
+| lastSeenTestRunId | BIGSERIAL | |
+| timesSeen | INTEGER | NOT NULL, DEFAULT 1 |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+| updatedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Actionable Item
+
+An interactive element on a page state (button, input, link, etc.).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| htmlElementId | BIGSERIAL | FK → html_elements |
+| stableKey | TEXT | Deterministic key for deduplication |
+| selector | TEXT | CSS selector |
+| tagName | TEXT | |
+| role | TEXT | ARIA role |
+| actionKind | TEXT | 'click', 'fill', 'select', 'navigate', 'radio_select' |
+| accessibleName | TEXT | |
+| disabled | BOOLEAN | |
+| visible | BOOLEAN | |
+| attributesJson | JSONB | All HTML attributes |
+| scaffoldId | BIGSERIAL | If this item belongs to a scaffold |
+| elementIdentityId | BIGSERIAL | FK → element_identities |
+
+---
+
+### Expertise
+
+A registered expertise category (e.g., SEO, Security, Performance).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| slug | TEXT | NOT NULL, UNIQUE — e.g., 'seo', 'security' |
+| title | TEXT | NOT NULL |
+| description | TEXT | NOT NULL |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Expertise Rule
+
+A specific rule within an expertise (e.g., "Title tag present" under SEO).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| expertiseId | BIGSERIAL | FK → expertises, NOT NULL |
+| title | TEXT | NOT NULL |
+| description | TEXT | NOT NULL |
+| aiEndpointUrl | TEXT | Optional AI evaluation endpoint |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+---
+
+### Persona
+
+An AI-generated user persona for a product.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| productId | BIGSERIAL | FK → products |
+| title | TEXT | NOT NULL |
+| description | TEXT | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Use Case
+
+A use case for a persona with specific input values.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| personaId | BIGSERIAL | FK → personas |
+| title | TEXT | NOT NULL |
+| description | TEXT | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Input Value
+
+A stored form field value for a use case.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| useCaseId | BIGSERIAL | FK → use_cases |
+| fieldSelector | TEXT | NOT NULL |
+| fieldName | TEXT | |
+| value | TEXT | NOT NULL |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Credential
+
+Stored login credentials for a product, optionally tied to a persona.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| productId | BIGSERIAL | FK → products, NOT NULL |
+| personaId | BIGSERIAL | FK → personas |
+| signic | BOOLEAN | NOT NULL, DEFAULT FALSE — whether to use Signic email service |
+| email | TEXT | |
+| password | TEXT | |
+| verificationCode | TEXT | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Environment
+
+A deployment environment for a product (e.g., dev, staging, production).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| productId | BIGSERIAL | FK → products, NOT NULL |
+| title | TEXT | NOT NULL |
+| baseUrl | TEXT | NOT NULL |
+| githubBranch | TEXT | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+| updatedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+### Test Schedule
+
+A recurring schedule for automated test runs.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | BIGSERIAL | PK |
+| runnerId | BIGSERIAL | FK → runners, NOT NULL |
+| title | TEXT | NOT NULL |
+| testSuiteId | BIGSERIAL | FK → test_suites |
+| testCaseId | BIGSERIAL | FK → test_cases |
+| testSuiteBundleId | BIGSERIAL | FK → test_suite_bundles |
+| discovery | BOOLEAN | NOT NULL, DEFAULT FALSE |
+| recurrenceType | TEXT | NOT NULL. Values: 'one_time', 'weekday', 'daily', 'weekly' |
+| timeOfDay | TEXT | NOT NULL — e.g., '09:00' |
+| dayOfWeek | INTEGER | 0-6 for weekly |
+| timezone | TEXT | NOT NULL |
+| enabled | BOOLEAN | NOT NULL, DEFAULT TRUE |
+| sizeClass | TEXT | NOT NULL, DEFAULT 'desktop' |
+| createdByUserId | TEXT | NOT NULL — Firebase uid |
+| lastRunAt | TIMESTAMPTZ | |
+| nextRunAt | TIMESTAMPTZ | |
+| createdAt | TIMESTAMPTZ | DEFAULT NOW() |
+| updatedAt | TIMESTAMPTZ | DEFAULT NOW() |
+
+---
+
+## In-Memory Objects (Runner Service)
+
+### Outcome
+
+Produced by each expertise during test case evaluation.
+
+```typescript
+interface Outcome {
+  expected: string;   // What was expected
+  observed: string;   // What was actually observed
+  result: 'pass' | 'warning' | 'error';
+}
+```
+
+### ExpertiseContext
+
+Passed to each expertise for evaluation.
+
+```typescript
+interface ExpertiseContext {
+  html: string;                              // Full page HTML including <head>
+  scaffolds: DetectedScaffoldRegion[];       // Decomposed scaffold list
+  patterns: DetectedPatternWithInstances[];  // Decomposed pattern list
+  consoleLogs: string[];                     // Console output during test case
+  networkLogs: NetworkLogEntry[];            // Network requests/responses
+  expectations: Expectation[];               // Test case expectations (for Tester)
+}
+```
+
+### Expertise (interface)
+
+```typescript
+interface Expertise {
+  name: string;
+  evaluate(context: ExpertiseContext): Outcome[];
+}
+```
+
+Implementations:
+
+| Name | Behavior |
+|------|----------|
+| Tester | Checks each test case expectation is met. Creates error findings for failures. |
+| SEO | Checks meta tags: title, description, keywords, canonical, og:* |
+| Security | Checks network calls for insecure practices (API keys in URLs, HTTP links) |
+| Performance | Checks network timing — all render-blocking content returned within threshold (500ms) |
+| Content | No-op. Returns empty list. |
+| UI | No-op. Returns empty list. |
+| Accessibility | No-op. Returns empty list. |
+
+### PageAnalyzer (singleton)
+
+Used only when `discovery = true`.
+
+```typescript
+interface PageAnalyzer {
+  // Called BEFORE expertises — generates baseline expectations
+  generateExpectations(testCase: TestCase): Expectation[];
+
+  // Called AFTER expertises — generates new test cases for scaffolds/patterns
+  generateTestCases(...): void;
+}
+```
+
+### Runner Instance
+
+```typescript
+interface RunnerInstance {
+  id: string;     // Random UUID, generated at startup
+  name: string;   // Human-readable name
+}
+```
+
+Set on the Test Run object to claim it and prevent concurrent execution by multiple runners.
+
+---
+
+## Enums
+
+### SizeClass
+
+`'desktop' | 'mobile'`
+
+### TestType
+
+`'render' | 'interaction' | 'form' | 'form_negative' | 'password' | 'navigation' | 'e2e'`
+
+### TestRunStatus
+
+`'pending' | 'planned' | 'running' | 'completed' | 'failed'`
+
+### FindingType
+
+`'error' | 'warning'`
+
+### PlaywrightAction
+
+`'goto' | 'goBack' | 'goForward' | 'reload' | 'click' | 'dblclick' | 'fill' | 'clear' | 'type' | 'press' | 'selectOption' | 'check' | 'uncheck' | 'hover' | 'focus' | 'scrollIntoView' | 'uploadFile' | 'screenshot' | 'waitForLoadState' | 'waitForURL' | 'waitForTimeout'`
+
+### ExpectationType
+
+60+ values. Key ones:
+
+- **Element**: `element_visible`, `element_hidden`, `element_exists`, `element_not_exists`, `element_count`, `element_enabled`, `element_disabled`, `element_focused`, `element_checked`, `element_editable`
+- **Text**: `text_content`, `text_contains`, `text_matches`, `text_on_page`, `text_not_on_page`
+- **Input**: `input_value`
+- **Attribute**: `attribute_equals`, `attribute_contains`, `has_class`, `not_has_class`
+- **URL**: `url_equals`, `url_contains`, `url_matches`, `url_changed`, `url_unchanged`
+- **Page**: `page_loaded`, `title_equals`, `title_contains`
+- **Console**: `no_console_errors`, `no_console_warnings`, `console_contains`, `console_not_contains`
+- **Network**: `no_network_errors`, `no_server_errors`, `network_request_made`, `network_response_status`, `no_pending_requests`
+- **Accessibility**: `no_aria_violations`, `element_has_role`, `element_has_label`
+- **Performance**: `load_time_within`, `no_layout_shift`
+- **Form**: `validation_message_visible`, `validation_message_hidden`, `form_submitted_successfully`, `error_state_visible`, `error_state_cleared`
+- **Navigation**: `redirected_to`, `history_length_changed`
+- **Storage**: `cookie_exists`, `cookie_not_exists`, `cookie_value`, `local_storage_value`, `session_storage_value`
+- **Security**: `no_mixed_content`, `sensitive_data_not_in_url`
+- **Visual**: `screenshot_match`
+
+### ExpectationSeverity
+
+`'must_pass' | 'should_pass' | 'info'`
+
+### HtmlComponentType (Scaffold Types)
+
+`'topMenu' | 'footer' | 'breadcrumb' | 'leftMenu' | 'hamburgerMenu' | 'rightSidebar' | 'searchBar' | 'userMenu' | 'cookieBanner' | 'chatWidget' | 'socialLinks' | 'skipNav' | 'languageSwitcher' | 'announcementBar' | 'backToTop'`
+
+### UiPatternType
+
+`'card' | 'table' | 'form' | 'modal' | 'toast' | 'alert' | 'tabs' | 'accordion' | 'carousel' | 'dropdown' | 'pagination' | 'skeleton' | 'emptyState' | 'errorMessage' | 'progressBar' | 'tooltip' | 'badge' | 'avatar' | 'tag' | 'stepper'`
+
+### RunnerType
+
+`'worker' | 'extension'`
+
+### RecurrenceType
+
+`'one_time' | 'weekday' | 'daily' | 'weekly'`