rust_browser/docs/test262_roadmap.md

Test262 Roadmap

What needs to be built to run real 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.