rust_browser/docs/test262_roadmap.md

# Test262 Roadmap

What needs to be built to run real [Test262](https://github.com/tc39/test262) conformance tests.

## Current State

We have a custom JS262 harness (`tests/js262_harness.rs`) with 127 hand-written tests that
mimic Test262 patterns. The real Test262 suite has 50,000+ tests. To run even a subset, the
interpreter must support the features that Test262's own harness files (`assert.js`, `sta.js`)
require, plus the syntax used in the test files themselves.

## Tier 1: Test262 Harness Requirements

These features are used by `assert.js` and `sta.js` — the support files that every Test262
test includes. **All of these must work before any real Test262 test can run.**

| Feature | Used For | Parser | Interpreter | Effort |
|---------|----------|--------|-------------|--------|
| `try` / `catch` / `finally` | `assert.throws()` wraps test code in try/catch | **Done** | **Done** | Medium |
| `throw` statement | `sta.js` throws `Test262Error` on failure | **Done** | **Done** | Small |
| Logical `&&` / `\|\|` | Short-circuit guards in assertions | **Done** | **Done** | Small |
| Object literals `{ k: v }` | Building error message objects | **Done** | **Done** | Medium |
| Property assignment `obj.prop = v` | `assert.sameValue = function ...` | **Done** (dot only) | **Done** (host + plain objects) | — |
| Prototype chain | `Test262Error.prototype.toString = ...` | N/A | Missing | Large |
| `this` keyword | Constructor bodies: `this.message = msg` | **Done** | **Done** | — |
| `switch` / `case` | `assert._toString` type formatting | **Done** | **Done** | Medium |
| Template literals `` `${x}` `` | Assertion error messages | **Done** | **Done** | — |
| `new` + constructor functions | `new Test262Error(msg)` | **Done** | Partial (host only) | Extend to JS functions |
| String methods (`.name`, `.call`) | `Object.prototype.toString.call()` | **Done** | **Done** | Medium |

### Minimum viable slice

To run the simplest Test262 tests, implement in this order:

1. ~~**`throw`** — trivial addition to parser + interpreter~~ **Done**
2. ~~**`try` / `catch`** — parser + interpreter control flow~~ **Done**
3. ~~**Logical operators `&&` / `||`** — parser + short-circuit eval~~ **Done**
4. ~~**Object literals** — parser + runtime plain-object type~~ **Done**
5. ~~**`this` keyword** — parser + interpreter binding~~ **Done**
6. ~~**`switch` / `case`** — parser + interpreter control flow~~ **Done**
7. ~~**Template literals** — tokenizer + parser + string interpolation eval~~ **Done**

After these 7 features, we can shim `assert.js` and `sta.js` and run Test262 tests that
only use basic syntax (variable declarations, functions, if/else, comparisons).

## Tier 2: Common Test File Features

Most Test262 tests go beyond basic syntax. These features unlock large swaths of the suite.

| Feature | % of Test262 tests using it | Parser | Interpreter | Effort |
|---------|----------------------------|--------|-------------|--------|
| `for` loops | ~60% | **Done** | **Done** | Medium |
| `for...in` / `for...of` | ~25% | Missing | Missing | Medium |
| `while` / `do...while` | ~15% | **Done** | **Done** | Small |
| Array literals `[1,2,3]` | ~50% | **Done** | **Done** | Medium |
| Computed member `obj[key]` | ~40% | **Done** | **Done** | Small |
| Arrow functions `=>` | ~30% | **Done** | **Done** | Medium |
| Ternary `? :` | ~20% | Missing | Missing | Small |
| Compound assignment `+=` etc. | ~20% | **Done** | **Done** | Small |
| Increment/decrement `++`/`--` | ~15% | **Done** | **Done** | Small |
| Destructuring | ~10% | Missing | Missing | Large |
| Spread / rest `...` | ~10% | Missing | Missing | Medium |
| `class` declarations | ~10% | Missing | Missing | Large |

### Recommended implementation order

After Tier 1 is complete:

1. ~~**`for` loops** — unlocks the most tests~~ **Done**
2. ~~**Array literals + computed member** — tightly coupled, unlock array tests~~ **Done**
3. ~~**Arrow functions** — widely used in modern test262 tests~~ **Done**
4. ~~**`while` / `do...while`** — small effort, moderate test coverage~~ **Done**
5. **Ternary `? :`** — trivial parser change
6. ~~**Compound assignment / increment-decrement** — small parser + desugar~~ **Done**

## Tier 3: Richer Runtime

These require more substantial runtime work beyond parsing and basic interpretation.

| Feature | What it unlocks | Effort |
|---------|----------------|--------|
| Plain JS objects (not just host) | Object literal basics work; no enumeration/prototype yet | Medium |
| Prototype chain / `Object.create` | Inheritance tests, method resolution | Large |
| `JSON.stringify` / `JSON.parse` | Harness error messages, JSON tests | Medium |
| `String.prototype` methods | `.length`, `.charAt()`, `.slice()`, `.indexOf()` | Medium |
| `Array.prototype` methods | `.push()`, `.pop()`, `.map()`, `.forEach()` | Large |
| `RegExp` | Regex literal tests, string matching | Very Large |
| Closures over mutable state | Counter patterns, module-like scoping | Medium |
| Strict mode (`"use strict"`) | Half of Test262 tests run in both sloppy and strict | Medium |
| `Symbol`, `WeakMap`, `Proxy` | Advanced ES6+ tests | Very Large |

## Integration Plan

### Phase A: Shim the Harness (after Tier 1) — **Done**

1. ~~Add `mode = "test262"` to the JS262 manifest schema~~ **Done**
2. ~~Before running each test, prepend the contents of `sta.js` and `assert.js`~~ **Done**
3. ~~Map `Test262Error` exceptions to test failure outcomes~~ **Done**
4. ~~Vendor a curated subset of ~50 basic Test262 tests into `tests/external/js262/test262/`~~ **Done**
5. ~~Add manifest entries with `mode = "test262"` and feature tags from Test262 metadata~~ **Done**

#### Phase A Results

- **50** real Test262 tests vendored from `tc39/test262`
- **35 pass** (70%), **15 known_fail** (30%)
- Feature areas covered: ASI (5), block-scope (20), comments (5), directive-prologue (5), expressions (15)
- Known-fail breakdown: ASI gaps (2), label syntax (2), function declarations in blocks (2), strict mode (5), other parser gaps (4)
- New JS feature added during Phase A: function property support (`fn.prop = val`, `fn.prop`, `fn.method()`)

### Phase B: Expand Coverage (after Tiers 1+2)

1. Vendor ~500 tests covering variables, expressions, functions, control flow
2. Use Test262's `features` metadata to filter to supported features only
3. Script the manifest generation: parse Test262 YAML frontmatter → TOML entries
4. Track pass rate as a project metric

### Phase C: Continuous Integration

1. Vendor full Test262 suite (or download on CI)
2. Run supported-feature subset on every PR
3. Run full suite nightly, track known-fail count trending down
4. Target: 90%+ pass rate on ES5.1 subset as first major milestone

## Quick Reference: Feature Gap Summary

**Blocking Test262 harness (must fix first):**
~~`this`~~, ~~`switch`~~, ~~template literals~~, ~~string methods / `.name` / `.call()`~~ — Prototype chain remains.

**Blocking large test coverage:**
*(none — arrow functions now implemented)*

**Already implemented:**
`var`/`let`/`const`, `if`/`else`, functions (declaration + expression + `new`),
`typeof`, `===`/`!==`/`==`/`!=`, arithmetic, string concat, `!` (not),
object literals, `try`/`catch`/`finally`, `throw`, `&&`/`||`,
string methods (`.length`, `.charAt()`, `.indexOf()`, `.slice()`, etc.),
`Function.name`, `Function.prototype.call()`, `Object.prototype.toString.call()`,
`for`/`while`/`do-while` loops, `break`/`continue`, `++`/`--`, `+=`/`-=`/`*=`,
function properties (`fn.prop = val`, `fn.method()`),
array literals (`[1,2,3]`), computed member access (`obj[key]`),
array methods (`.push()`, `.pop()`, `.join()`, `.indexOf()`, `.slice()`, `.concat()`),
Promises, setTimeout, queueMicrotask, DOM bindings, event dispatch

**JS262 conformance:** 127 tests, 121 pass, 5 known_fail. **Test262:** 50 vendored, 35 pass (70%) — Phase A complete. See `docs/js_conformance_report.md`.

See `docs/js_feature_matrix.md` for the full current feature status.