Skip to content

Add initial README with some setup and runner instructions #258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danleh merged 4 commits into from
Jan 14, 2026
+105 −25
Merged

Add initial README with some setup and runner instructions #258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d7c64e3
add initial README with some setup and runner instructions
danleh Jan 14, 2026
fbd86b3
fix links
danleh Jan 14, 2026
4d5659c
add descriptions for preloading and compression, more details on scoring
danleh Jan 14, 2026
ff781d0
s/Web Assembly/WebAssembly in in-depth, update some outdated information
danleh Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# What is JetStream?

JetStream 3 is a JavaScript and WebAssembly benchmark suite.
For more information see the index and in-depth pages of the deployed benchmark.

A preview of the current main branch is available at [https://webkit-jetstream-preview.netlify.app/](https://webkit-jetstream-preview.netlify.app/).

<img src="./resources/screenshot.png">

## Open Governance

See [Governance.md](Governance.md) for more information.

## Getting Started, Setup Instructions

- Install Node.js and (optionally) [jsvu](https://github.com/GoogleChromeLabs/jsvu) for conveniently getting recent builds of engine shells.
- `npm install` the necessary dependencies.
- `npm run server` for starting a local development server, then browse to http://localhost:8010.
- `npm run test:shell` for running the benchmark in engine shells, or alternatively running directly, e.g., via `jsc cli.js`.

See [package.json](package.json) and [.github/workflows/test.yml](.github/workflows/test.yml) for more details and available commands.

### Shell Runner

For the shell runner, see the available options by passing `--help` to `cli.js`. (Note that this requires `--` for JavaScriptCore and V8 to separate VM arguments from script arguments.):

```
$ v8 cli.js -- --help
JetStream Driver Help

Options:
--help Print this help message.
--iteration-count Set the default iteration count.
...

Available tags:
all
...

Available tests:
8bitbench-wasm
...
```

### Browser Runner

The browser version also supports passing parameters as URL query parameters, e.g., pass the `test` parameter (aliases are `tests` or `testList`) with a comma-separated list to run only specific workloads: [https://webkit-jetstream-preview.netlify.app/?test=8bitbench-wasm,web-ssr](https://webkit-jetstream-preview.netlify.app/?test=8bitbench-wasm,web-ssr).
See [utils/params.js](utils/params.js) and [JetStreamDriver.js](JetStreamDriver.js) for more details.

## Technical Details

The main file of the benchmark harness is `JetStreamDriver.js`, which lists the individual workloads and their parameters, implements measurement and scoring, etc.
The individual workloads are in subdirectories.

### Preloading and Compression

The JetStream driver (both in the browser and shell runners) _preloads_ some large assets and source files.
Copy link
Contributor

@kmiller68 kmiller68 Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit unclear what preloading means in this context. Might be worth splitting this into two parts e.g.

#### Network prefetching

In order to avoid the CPU frequency spinning down between tests we prefetch all assets before any of the tests start in the browser (In the CLI we assume all assets are on disk). Assets are saved in a blob URL so they can be cached on disk. This lowers the peak memory footprint of the benchmark to a sustainable level.

#### Large Asset preloading
The JetStream driver (both in the browser and shell runners) _preloads_ some large assets and source files. This avoids extensive disk I/O from the memory.

Copy link
Contributor Author

@danleh danleh Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good points, I'll use that tomorrow in a follow-up (or feel free to send a quick PR, whatever works).

That is, it reads those files from disk or fetches them from the network before running the workloads.
This is in order to exclude network latency and disk I/O from the benchmark measurements and reduce variance. Otherwise, OS scheduling or CPU frequency scaling may affect the measurement.

Some workloads also utilize large assets (e.g., ML models, heavy JavaScript bundles in the order of 10s of MBs).
In order to limit the repository size and network transfers, such large assets are stored as compressed .z files.
Preloading handles the decompression of these assets (using `DecompressionStream` or a Wasm-based zlib polyfill) upfront so that decompression overhead does not affect the benchmark score.

Both preloading and compression can be disabled, e.g., to inspect raw files or because it sometimes helps with debugging (e.g., proper URLs instead of Blobs for resources).

- Compression: Run `npm run decompress` to decompress all .z files before running the benchmark.
- No prefetching for shells: Pass the `--no-prefetch` flag, e.g., `jsc cli.js -- --no-prefetch`.
- No prefetching in browsers: Append the query parameter `?prefetchResources=false` to the URL.

See `JetStreamDriver.js` and `utils/compress.mjs` for more details.

### Score Calculation

Scores in JetStream are dimensionless floats, where a higher score is better.
When scores are aggregated (e.g., multiple sub-scores for each workload, or to determine the total score of the full benchmark suite), we use the [geometric mean](https://en.wikipedia.org/wiki/Geometric_mean).
The geometric mean ensures that a multiplicative improvement of any individual score has the same effect on the aggregated score, regardless of the absolute value of the individual score.
For example, an improvement by 5% of the sub score of benchmark A has the same effect on the total score as an improvement by 5% of the sub score of benchmark B.

See the [in-depth.html](https://webkit-jetstream-preview.netlify.app/in-depth.html) and `JetStreamDriver.js` for more details.
46 changes: 23 additions & 23 deletions in-depth.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@

<title>JetStream 3 In-Depth Analysis</title>

<link rel="stylesheet" href="ressources/JetStream.css">
<link rel="stylesheet" href="resources/JetStream.css">

</head>
<body class="overflow-scroll">
Expand All @@ -43,7 +43,7 @@ <h1 class="logo">
<h2>In-Depth Analysis</h2>

<p>
JetStream 3 combines together a variety of JavaScript and Web Assembly benchmarks, covering a variety of
JetStream 3 combines together a variety of JavaScript and WebAssembly benchmarks, covering a variety of
advanced workloads and programming techniques, and reports a single score that
balances them using a geometric mean.
</p>
Expand All @@ -56,9 +56,11 @@ <h2>In-Depth Analysis</h2>
</p>

<p>
Each benchmark in JetStream 3 computes its own individual score. JetStream 3 weighs each
benchmark equally, taking the geometric mean over each individual benchmark's score to compute
the overall JetStream 3 score.
Each benchmark in JetStream 3 computes its own individual score.
Scores in JetStream are dimensionless floats, where a higher score is better.
JetStream weighs each benchmark equally, taking the <a href="https://en.wikipedia.org/wiki/Geometric_mean">geometric mean</a> over each individual benchmark's score to compute the overall JetStream 3 score.
The geometric mean ensures that a multiplicative improvement of any individual score has the same effect on the aggregated score, regardless of the absolute value of the individual score.
For example, an improvement by 5% of the sub score of benchmark A has the same effect on the total score as an improvement by 5% of the sub score of benchmark B.
</p>

<p>
Expand All @@ -70,7 +72,7 @@ <h2>In-Depth Analysis</h2>
</p>

<p>
For most of the JavaScript benchmarks in JetStream 3, individual scores
For most of the JavaScript and WebAssembly benchmarks in JetStream 3, individual scores
equally weigh startup performance, worst case performance, and average case
performance. These three metrics are crucial to running performant JavaScript
in the browser. Fast startup times lead browsers to loading pages more quickly. Good
Expand All @@ -79,11 +81,10 @@ <h2>In-Depth Analysis</h2>
</p>

<p>
For JetStream 3's Web Assembly benchmarks, individual scores equally weigh startup time and
total execution time. An important component of JetStream 1 were the asm.js subset of benchmarks. With the release
of Web Assembly, the importance of asm.js has lessened since many users of asm.js are
now using Web Assembly. JetStream 3 has converted many of the asm.js benchmarks from
JetStream 1 into Web Assembly.
An important component of JetStream 1 were the asm.js subset of benchmarks. With the release
of WebAssembly, the importance of asm.js has lessened since many users of asm.js are
now using WebAssembly. JetStream 3 has converted many of the asm.js benchmarks from
JetStream 1 into WebAssembly.
</p>

<p>
Expand All @@ -106,14 +107,13 @@ <h2>In-Depth Analysis</h2>
<p>
JetStream 3 includes parts of these benchmark suites that came before it: <a href="https://webkit.org/perf/sunspider/sunspider.html">SunSpider</a>,
<a href="https://developers.google.com/octane/">Octane 2</a>, <a href="https://browserbench.org/JetStream1.1/">JetStream 1</a>,
<a href="https://browserbench.org/ARES-6/">ARES-6</a>, and <a href="https://v8.github.io/web-tooling-benchmark/">Web Tooling Benchmark</a>.
JetStream 3 also includes new benchmarks inspired by <a href="https://krakenbenchmark.mozilla.org">Kraken</a>.
JetStream 3 also includes a new set of benchmarks that measure the performance of Web Assembly, Web Workers,
<a href="https://browserbench.org/ARES-6/">ARES-6</a>, <a href="https://v8.github.io/web-tooling-benchmark/">Web Tooling Benchmark</a>, and benchmarks inspired by <a href="https://krakenbenchmark.mozilla.org">Kraken</a>.
JetStream 3 also includes a new set of benchmarks that measure the performance of WebAssembly, Web Workers,
Promises, async iteration, unicode regular expressions, and JavaScript parsing.
</p>

<p>
JetStream 3 runs the same benchmarks as JetStream 3, but updates the benchmark driver to
JetStream 3 includes several benchmarks from earlier JetStream versions, but updates the benchmark driver to
improve score stability. This is achieved by pre-fetching network resources prior to running
the benchmarks. This can reduce perturbations on the measurement of JavaScript execution
time due to second order effects of pause times induced by network latency.
Expand Down Expand Up @@ -168,7 +168,7 @@ <h3>
<dt id="tsf-wasm">tsf-wasm</dt>
<dd>
Runs Filip Pizlo's &mdash; of the WebKit team &mdash; implementation of a <a href="http://www.filpizlo.com/tsf/"> Typed Stream Format </a>
in Web Assembly. The original code is compiled from C to Web Assembly using <a href="https://emscripten.org">Emscripten</a>.
in WebAssembly. The original code is compiled from C to WebAssembly using <a href="https://emscripten.org">Emscripten</a>.
Source code: <a href="wasm/TSF">TSF</a>
</dd>

Expand All @@ -179,7 +179,7 @@ <h3>

<dt id="argon2-wasm">argon2-wasm</dt>
<dd>
Tests <a href="https://github.com/P-H-C/phc-winner-argon2">Argon2</a>, a password-hashing function (the winner of Password Hashing Competition), in Web Assembly. This is test is based on <a href="https://github.com/antelle/argon2-browser">argon2-browser</a> library. Source code: <a href="wasm/">ARGON2</a>.
Tests <a href="https://github.com/P-H-C/phc-winner-argon2">Argon2</a>, a password-hashing function (the winner of Password Hashing Competition), in WebAssembly. This is test is based on <a href="https://github.com/antelle/argon2-browser">argon2-browser</a> library. Source code: <a href="wasm/">ARGON2</a>.
</dd>

<dt id="tagcloud-SP">tagcloud-SP</dt>
Expand Down Expand Up @@ -246,8 +246,8 @@ <h3>
<dt id="richards-wasm">richards-wasm</dt>
<dd>
Martin Richard's <a href="http://www.cl.cam.ac.uk/~mr10/Bench.html">system language
benchmark</a> compiled to a hybrid of Web Assembly and JavaScript. It stresses how quickly
JavaScript can call into Web Assembly code.
benchmark</a> compiled to a hybrid of WebAssembly and JavaScript. It stresses how quickly
JavaScript can call into WebAssembly code.
Source code: <a href="wasm/richards.c">richards.c</a>, <a href="wasm/richards.js">richards.js</a>
</dd>

Expand Down Expand Up @@ -302,7 +302,7 @@ <h3>

<dt id="quicksort-wasm">quicksort-wasm</dt>
<dd>
Quicksort benchmark, compiled to Web Assembly with <a href="https://emscripten.org">Emscripten</a>.
Quicksort benchmark, compiled to WebAssembly with <a href="https://emscripten.org">Emscripten</a>.
The original C version of this benchmark was previously published in the LLVM test suite.
Source code: <a href="wasm/quicksort.c">quicksort.c</a>, <a href="wasm/quicksort.js">quicksort.js</a>
</dd>
Expand Down Expand Up @@ -418,8 +418,8 @@ <h3>

<dt id="HashSet-wasm">HashSet-wasm</dt>
<dd>
A Web Assembly benchmark replaying a set of hash table operations performed in WebKit when loading
a web page. This benchmark was compiled from C++ to Web Assembly using <a href="https://emscripten.org">Emscripten</a>.
A WebAssembly benchmark replaying a set of hash table operations performed in WebKit when loading
a web page. This benchmark was compiled from C++ to WebAssembly using <a href="https://emscripten.org">Emscripten</a>.
Source code: <a href="wasm/HashSet.cpp">HashSet.cpp</a>, <a href="wasm/HashSet.js">HashSet.js</a>
</dd>

Expand All @@ -434,7 +434,7 @@ <h3>

<dt id="gcc-loops-wasm">gcc-loops-wasm</dt>
<dd>
Example loops used to tune the GCC and LLVM vectorizers, compiled to Web Assembly with
Example loops used to tune the GCC and LLVM vectorizers, compiled to WebAssembly with
<a href="https://emscripten.org">Emscripten</a>. The original C++ version of this benchmark was previously published in the LLVM test suite.
Source code: <a href="wasm/gcc-loops.cpp">gcc-loops.cpp</a>, <a href="wasm/gcc-loops.js">gcc-loops.js</a>
</dd>
Expand Down
2 changes: 1 addition & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ <h1 class="logo">
</h1>

<main>
<p class="summary">JetStream 3 is a JavaScript and WebAssembly benchmark suite focused on the most advanced web applications. It rewards browsers that start up quickly, execute code quickly, and run smoothly. For more information, read the <a href="resources/in-depth.html">in-depth analysis</a>. Bigger scores are better.</p>
<p class="summary">JetStream 3 is a JavaScript and WebAssembly benchmark suite focused on the most advanced web applications. It rewards browsers that start up quickly, execute code quickly, and run smoothly. For more information, read the <a href="/in-depth.html">in-depth analysis</a>. Bigger scores are better.</p>
<div id="non-default-params">
<h2>Non-standard Parameters</h2>
<p>
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
"prepare": "node utils/version-check.mjs",
"server": "npm run prepare --silent && node tests/server.mjs",
"compress": "npm run prepare --silent && node utils/compress.mjs",
"decompress": "npm run prepare --silent && node utils/compress.mjs --decompress --keep ",
"decompress": "npm run prepare --silent && node utils/compress.mjs --decompress --keep",
"lint:check": "npm run prepare --silent && eslint **/*.{js,mjs,jsx,ts,tsx}",
"pretty:check": "npm run prepare --silent && prettier --check ./",
"pretty:format": "npm run prepare --silent && prettier --write ./",
Expand Down
Binary file added resources/screenshot.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading