docs: Add Overview and Benchmarking guides (#8879)

Author: tobiu

learn/guides/testing/Benchmarking.md

@@ -0,0 +1,44 @@
+# Benchmarking and Performance Testing
+
+> **Note:** The official Neo.mjs benchmarking suite and harness are maintained in a separate repository: [neomjs/benchmarks](https://github.com/neomjs/benchmarks).
+
+## Philosophy: Measuring Resilience
+
+Most web benchmarks (like Lighthouse or Core Web Vitals) focus on the "First Impression"—how fast a page loads. Neo.mjs, being an application engine for complex enterprise tools, focuses on the "Lived-In" experience.
+
+Our benchmarking philosophy is not about "Page Load" time. It is about **Resilience**:
+*   Can the UI handle 1,000 updates per second without freezing?
+*   Can a grid ingest 100,000 rows while the user is scrolling?
+*   Does the application remain responsive (60 FPS) during heavy background calculations?
+
+## The Challenges of Benchmarking
+
+Building a reliable benchmark for multi-threaded applications required solving three specific problems that standard test runners (like Playwright out-of-the-box) do not address.
+
+### 1. The Parallelism Trap
+**Problem:** Standard test runners execute tests in parallel to save time. This is disastrous for benchmarking because tests compete for CPU resources, causing massive variance in results (up to 50%).
+**Solution:** Our harness enforces **Serial Execution** (`--workers=1`). Every test gets the full, undivided attention of the CPU.
+
+### 2. The Latency Chasm
+**Problem:** Sending commands from Node.js (Test Runner) to the Browser introduces unpredictable network/process latency (The "Observer Effect").
+**Solution:** We use **Atomic Measurement**. The entire test sequence (Action -> Wait -> Measure) is injected into the browser via `page.evaluate()`. The measurement happens entirely within the browser's high-precision context, returning only the final result to Node.js.
+
+### 3. The Polling Fallacy
+**Problem:** Standard `waitFor()` functions use polling (checking every ~30ms). You cannot measure a 20ms event with a 30ms ruler.
+**Solution:** We reject polling in favor of **MutationObservers**. Our harness attaches a listener that checks the pass condition *synchronously* on every single DOM mutation, allowing us to stop the timer with microsecond precision.
+
+## Running the Benchmarks
+
+To run the benchmarks, you must clone the separate repository:
+
+```bash
+git clone https://github.com/neomjs/benchmarks.git
+cd benchmarks
+npm install
+npm run test
+```
+
+**Why a separate repository?**
+The benchmarking suite provides direct, apples-to-apples comparisons between **Neo.mjs**, **React**, **Angular**, and **AG Grid**. To ensure a fair comparison, we include the full production build environments for these frameworks. Keeping the benchmarks separate ensures that the core `neomjs/neo` repository remains lightweight and free of these heavy third-party dependencies.
+
+For detailed instructions on reproducing results and understanding the methodology, please refer to the documentation within that repository.

learn/guides/testing/Overview.md

@@ -0,0 +1,37 @@
+# Testing Neo.mjs Applications
+
+Testing is a critical part of the Neo.mjs ecosystem. Because of the framework's unique multi-threaded architecture, our testing strategy is divided into three distinct pillars, each serving a specific purpose.
+
+## 1. Unit Testing (Logic & State)
+**Focus:** Core logic, State Management, VDOM Diffing.
+**Environment:** Simulated Single-Thread Node.js (via Playwright).
+
+Unit tests in Neo.mjs are designed for extreme speed and debugging simplicity. We simulate the entire worker architecture (App, VDom, Data) inside a single Node.js thread. This allows you to step through code execution across "workers" without context switching and verify logic without the overhead of a real browser.
+
+[Read the Unit Testing Guide](UnitTesting.md)
+
+## 2. Component Testing (Visual & Interaction)
+**Focus:** DOM Events, CSS, Layout, Browser APIs.
+**Environment:** Real Browser (Chrome/Firefox/Webkit).
+
+Component tests run your actual application code inside a real browser environment. This is where you verify that your buttons click, your layouts resize correctly, and your CSS renders as expected. We use a specialized "Remote Control" architecture to drive the App Worker from the test runner.
+
+[Read the Component Testing Guide](ComponentTesting.md)
+
+## 3. Benchmarking (Performance & Resilience)
+**Focus:** Concurrency, FPS, Memory Leaks, Resilience under Load.
+**Environment:** Specialized High-Precision Harness (Separate Repository).
+
+Standard functional tests pass if the UI "eventually" reaches the correct state. Benchmarks measure *how* it gets there. We focus on "Resilience Testing"—measuring if the application can handle high-frequency updates, massive datasets, and background calculations without dropping frames.
+
+**Note:** The benchmarking suite is maintained in a separate repository to ensure a sterile, isolation-focused environment.
+
+[Read the Benchmarking Guide](Benchmarking.md)
+
+## Summary
+
+| Type | Environment | Use Case |
+| :--- | :--- | :--- |
+| **Unit** | Node.js (Simulated) | "Does the logic work?" (Store filtering, VDOM generation) |
+| **Component** | Real Browser | "Does it look right and react to clicks?" (Drag & drop, Focus) |
+| **Benchmark** | Specialized Harness | "Is it fast and stable under pressure?" (100k rows, 60 FPS) |

learn/tree.json

@@ -67,8 +67,10 @@
                 {"name": "Custom Events",                              "parentId": "guides/userinteraction/events",                       "id": "guides/userinteraction/events/CustomEvents"},
                 {"name": "DOM Events",                                 "parentId": "guides/userinteraction/events",                       "id": "guides/userinteraction/events/DomEvents"},
         {"name": "Testing",                                            "parentId": "guides",                             "isLeaf": false, "id": "guides/testing", "collapsed": true},
+            {"name": "Overview",                                       "parentId": "guides/testing",                                      "id": "guides/testing/Overview"},
             {"name": "Unit Testing",                                   "parentId": "guides/testing",                                      "id": "guides/testing/UnitTesting"},
             {"name": "Component Testing",                              "parentId": "guides/testing",                                      "id": "guides/testing/ComponentTesting"},
+            {"name": "Benchmarking",                                   "parentId": "guides/testing",                                      "id": "guides/testing/Benchmarking"},
         {"name": "Specific Applications/Features",                     "parentId": "guides",                             "isLeaf": false, "id": "guides/specificfeatures", "collapsed": true},
             {"name": "Multi-Window Applications",                      "parentId": "guides/specificfeatures",                             "id": "guides/specificfeatures/MultiWindow", "hidden":  true},
             {"name": "Mixins",                                         "parentId": "guides/specificfeatures",                             "id": "guides/specificfeatures/Mixins", "hidden": true},