What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	14848
title	Group whitebox E2E specs by domain
state	Closed
labels	enhancementairefactoringtesting
assignees	neo-gpt
createdAt	1:33 PM
updatedAt	5:11 PM
githubUrl	https://github.com/neomjs/neo/issues/14848
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	5:11 PM

Group whitebox E2E specs by domain

Closed Backlog/active-chunk-4 enhancementairefactoringtesting

neo-gpt commented on 1:33 PM

Context

The operator flagged test/playwright/e2e/ on 2026-07-05 as urgent debt: the directory had 36 flat .spec.mjs files at report time and 37 flat specs on fresh origin/dev after NeuralLinkTransactionArchiveReplay.spec.mjs landed, with only utils/ grouped. That flat shape now mixes grid proofs, Neural Link tool proofs, AgentOS cockpit flows, write-guard/concurrency proofs, live preview, markdown streaming, and harness endurance benchmarks in one namespace.

This is not a new E2E behavior request. It is a test-substrate hygiene fix so future whitebox-e2e work has obvious ownership and reviewers can quickly find the relevant proof family.

Live latest-open sweep: checked latest 20 open issues at 2026-07-05T11:32:08Z; no equivalent ticket found. The closest fresh issue, #14845, covers a hindcast helper naming collision, not E2E directory taxonomy.

Knowledge Base sweep: asked for existing test/playwright/e2e organization guidance; KB found only the current flat examples and no documented grouping convention or existing ticket.

Local synced-content sweep: resources/content/issues / resources/content/discussions contains related whitebox-e2e feature tickets such as #14591, #14685, #14830, and older grid E2E references, but no ticket for reorganizing the directory itself.

A2A in-flight sweep: final pre-create all-status mailbox scan found no recent [lane-claim] or [lane-intent] on this E2E directory organization scope.

The Problem

The current E2E tree is too large for a flat directory:

37 spec files live directly under test/playwright/e2e/ on fresh origin/dev.
The only grouping folder is test/playwright/e2e/utils/.
File families are already visible in names, but the filesystem does not encode them: Grid*, NeuralLink*, WriteGuard*, AgentOSCockpit, FleetCockpitLifecycleNL, HarnessEnduranceBenchmark, LivePreviewMultiWindow, MarkdownStreamingCoherenceNL, ButtonBaseNL, and DeltaCoherenceRegistryNL.

That imposes a real review and maintenance tax: every new whitebox-e2e proof lands into a growing undifferentiated bucket, and the directory stops communicating ownership by domain.

The Architectural Reality

Whitebox E2E tests are discovered through test/playwright/playwright.config.e2e.mjs, which sets testDir: './e2e'. Playwright discovery is recursive, so domain subdirectories should remain discoverable without changing the primary test command:

npm run test-e2e -- <path-or-pattern>

The current config also references ./e2e/custom-reporter.js. If reporter placement changes, the config must be updated explicitly. The safer first pass is to leave shared reporter/helpers in shared support paths and move only spec files into domain folders.

The whitebox-e2e protocol currently says E2E tests belong in test/playwright/e2e/. This ticket should preserve that root while adding a shallow taxonomy beneath it. It should not introduce a separate config per domain unless a concrete verifier proves the single recursive config is insufficient.

Relevant source surfaces:

test/playwright/e2e/*.spec.mjs
test/playwright/e2e/utils/browser-test-helpers.mjs
test/playwright/e2e/custom-reporter.js
test/playwright/playwright.config.e2e.mjs
.agents/skills/whitebox-e2e/references/whitebox-e2e-protocol.md
learn/guides/testing/WhiteboxE2E.md
ai/scripts/lifecycle/nightlyE2eRunner.mjs
ai/scripts/lifecycle/nightlyE2eDigest.mjs

The Fix

Reorganize test/playwright/e2e/ into shallow domain groups, keeping shared support at the root or under an explicit support folder.

Proposed first-pass taxonomy:

test/playwright/e2e/grid/ for Grid*.spec.mjs
test/playwright/e2e/neural-link/ for NeuralLink*.spec.mjs
test/playwright/e2e/agentos/ for AgentOS/fleet cockpit proofs
test/playwright/e2e/write-guard/ for write-guard concurrency proofs
test/playwright/e2e/rendering/ for button, delta coherence, live preview, and markdown rendering proofs
test/playwright/e2e/benchmarks/ for endurance/scroll/profile benchmark specs
shared support remains as custom-reporter.js and utils/ unless a better support-folder move is proven with config/test evidence

The implementer may adjust the exact bucket names if the diff inspection proves a cleaner local taxonomy, but the end state must remove the flat 30+ spec-file root.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
`test/playwright/e2e/` directory taxonomy	Operator 2026-07-05 debt report + observed 36 flat specs	Root contains only support files/folders and domain subdirectories; specs live in groups	If one spec is genuinely cross-cutting, place it in the closest domain and document why in the PR body	Whitebox E2E docs/skill path references updated if they name moved files	`find test/playwright/e2e -maxdepth 1 -type f -name '*.spec.mjs'` returns 0 or a justified minimal exception
E2E discovery	`test/playwright/playwright.config.e2e.mjs`	Existing recursive E2E config still discovers moved specs	Add config comments or targeted path fixes only if a verifier fails	`npm run test-e2e -- <moved spec>` examples stay valid	Focused moved-spec run or Playwright list/grep evidence using the custom E2E config
Shared reporter/helpers	`custom-reporter.js`, `utils/browser-test-helpers.mjs`	Shared support remains reachable after moves	Update reporter path/imports if support moves	Config and docs paths updated together	`node --check` for changed support files/config and E2E command starts with no reporter resolution error
Nightly E2E digest paths	`ai/scripts/lifecycle/nightlyE2eRunner.mjs`, `nightlyE2eDigest.mjs`	Digest code remains path-agnostic for nested spec paths	Add/adjust unit coverage only if path parsing assumes flat filenames	Existing runner docs remain accurate	Existing nightly digest unit tests pass or targeted equivalent passes

Decision Record Impact

None. This is test-directory hygiene inside the existing whitebox-e2e substrate, not a change to the E2E architecture or ADR authority.

Acceptance Criteria

test/playwright/e2e/ no longer contains 30+ flat .spec.mjs files; specs are grouped into shallow domain subdirectories.
The grouping taxonomy is visible and intentionally named; reviewers can infer domain ownership from folder names without reading every filename.
All moved imports still resolve, especially imports to ../fixtures.mjs, shared helpers, and any same-family spec references.
test/playwright/playwright.config.e2e.mjs still uses the custom E2E config and resolves the custom reporter.
Whitebox E2E docs/skill references to moved example files are updated where they would otherwise point at stale paths.
Nightly E2E runner/digest behavior remains compatible with nested spec paths.
Verification includes at minimum: git diff --check; node --check for changed .mjs/.js files; a recursive discovery/path verifier such as npm run test-e2e -- --list or targeted moved-spec run using test/playwright/playwright.config.e2e.mjs.

Out of Scope

Do not rewrite test assertions or broaden behavioral coverage.
Do not introduce new E2E features.
Do not split the E2E suite into multiple Playwright configs unless the current recursive config demonstrably cannot support the grouped layout.
Do not move unit/component/integration tests.
Do not rename specs for aesthetics unless required to avoid ambiguity after grouping.

Avoided Traps

Toaster move: adding another docs-only convention while leaving the flat directory in place. The debt is the filesystem shape; the fix must move files.
Over-splitting: one config per folder would add maintenance cost before there is evidence it is needed.
Behavior churn: this is a mechanical organization lane. Any red E2E behavior discovered during verification should become a follow-up bug unless caused by the move itself.

#14591 — related whitebox-e2e feature coverage, not a directory organization ticket.
#14685 — nightly whitebox-e2e runner must remain compatible with nested spec paths.
#14830 — recent individual E2E fix; should not absorb this tree-wide debt.

Handoff Retrieval Hints

Retrieval Hint: test/playwright/e2e flat grouped files whitebox-e2e directory taxonomy

tobiu referenced in commit ecbb21c - "chore(test): group whitebox e2e specs (#14848) (#14849) on 5:11 PM

tobiu closed this issue on 5:11 PM