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	8881
title	Enhance Testing Guides with Practical Workflow & Safety Protocols
state	Closed
labels	documentationdeveloper-experienceaitesting
assignees	tobiu
createdAt	Jan 26, 2026, 12:17 PM
updatedAt	Jan 26, 2026, 12:27 PM
githubUrl	https://github.com/neomjs/neo/issues/8881
author	tobiu
commentsCount	1
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jan 26, 2026, 12:27 PM

Enhance Testing Guides with Practical Workflow & Safety Protocols

Closed v11.24.0/archive-v11-24-0-chunk-1 documentationdeveloper-experienceaitesting

tobiu commented on Jan 26, 2026, 12:17 PM

Context: The current testing guides (UnitTesting.md and ComponentTesting.md) provide a good architectural overview but lack practical "Day 1" developer experience details. We need to bridge the gap between "knowing the architecture" and "running the first test".

Missing Information & Required Updates:

Running Specific Tests (The "Focus Mode"):
- Explain how to run a single test file to avoid waiting for the full suite during development.
- Command: npx playwright test test/playwright/unit/my/file.spec.mjs -c test/playwright/playwright.config.unit.mjs
- Why: This is the standard workflow for TDD / debugging.
The "Safety Net" (Cross-Test Side Effects):
- Explicitly warn that running a single test is not enough before committing.
- The Trap: Because Neo.mjs unit tests run in a shared worker process (for speed), a test in File A can pollute the global namespace/state for File B.
- The Rule: "Always run npm run test-unit (full suite) before pushing to verify isolation."
Debugging & Filtering:
- Mention the --debug flag for stepping through tests.
- Mention the --grep flag for filtering tests by name.
File Organization:
- Clarify where new tests should live (mirroring src structure).

Goal: Update both guides to include a "Developer Workflow" section that covers these practical commands and safety protocols.

tobiu added the documentation label on Jan 26, 2026, 12:17 PM

tobiu added the developer-experience label on Jan 26, 2026, 12:17 PM

tobiu added the ai label on Jan 26, 2026, 12:17 PM

tobiu Jan 26, 2026, 12:26 PM

Input from Gemini 3 Pro:

✦ I have updated the testing guides to include a practical "Developer Workflow" section.

Changes:

learn/guides/testing/UnitTesting.md:

Added "Running a Single File (Focus Mode)": Documented the npx playwright test ... -c ... command.

Added "Debugging": Documented --debug and -g (grep) flags.

Added "The Safety Net": Clarified the Playwright worker process model vs. Neo.mjs SharedWorkers. Explicitly warned about namespace collisions and the strategy of using unique namespaces for test classes.

learn/guides/testing/ComponentTesting.md:

Added "Developer Workflow": Documented how to run single component files.

Added "Visual Debugging": Documented the --headed flag.

These updates bridge the gap between architectural theory and daily usage, helping developers get up to speed faster while avoiding common pitfalls.