Update docs for running CTS - Document --force_low_power_gpu and --force_high_performance_gpu - Clarify which args you're most likely to need - Remove the power preference args from Android because Android devices only have one GPU No-Try: true Bug: none Change-Id: I93f1930d3f706f09a2a14c36339c888dd3f6be3c Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/239457 Reviewed-by: Antonio Maiorano <amaiorano@google.com> Commit-Queue: Kai Ninomiya <kainino@chromium.org>
diff --git a/webgpu-cts/README.md b/webgpu-cts/README.md index fffa292..1b1933c 100644 --- a/webgpu-cts/README.md +++ b/webgpu-cts/README.md
@@ -1,25 +1,40 @@ # Running the WebGPU CTS Locally with Chrome Running the WebGPU CTS locally with Chrome requires a Chromium checkout. +Follow [these instructions](https://www.chromium.org/developers/how-tos/get-the-code/) +for checking out and building Chrome. -Follow [these instructions](https://www.chromium.org/developers/how-tos/get-the-code/) for checking out -and building Chrome. You'll also need to build the `telemetry_gpu_integration_test` target. +**Build the `telemetry_gpu_integration_test` targets.** At the root of a Chromium checkout, run: `./content/test/gpu/run_gpu_integration_test.py webgpu_cts --browser=exact --browser-executable=path/to/your/chrome-executable` If you don't want to build Chrome, you can still run the CTS, by passing the path to an existing Chrome executable to the `--browser-executable` argument. However, if you would like to use all harness functionality (symbolizing stack dumps, etc.). You will still need to build the `telemetry_gpu_integration_test` target. -Useful command-line arguments: - - `--help`: See more options and argument documentation. - - `-l`: List all tests that would be run. - - `--test-filter`: Filter tests. - - `--passthrough --show-stdout`: Show browser output. See also `--browser-logging-verbosity`. - - `--extra-browser-args`: Pass extra args to the browser executable. - - `--jobs=N`: Run with multiple parallel browser instances. - - `--stable-jobs`: Assign tests to each job in a stable order. Used on the bots for consistency and ease of reproduction. - - `--enable-dawn-backend-validation`: Enable Dawn's backend validation. - - `--use-webgpu-adapter=[default,swiftshader,compat]`: Forwarded to the browser to select a particular WebGPU adapter. +You will probably want these command line arguments: + +- `--passthrough --show-stdout`: Show browser output. See also `--browser-logging-verbosity`. +- `--test-filter`: Filter tests. +- `--jobs=1`: Run just one browser instance, best for debugging. Omit or set higher if you need to run more than a few tests. + +These GPU-specific arguments are often needed: + +- `--force_low_power_gpu` and `--force_high_performance_gpu`: Set the GPU used by the whole browser, + and thus the (default) adapter for WebGPU. (On dual-GPU Macs, only, Chrome can use multiple GPUs. + [`--use-webgpu-power-preference`][use-webgpu-power-preference] can be used to control which one WebGPU chooses.) +- `--enable-dawn-backend-validation`: Enable Dawn's backend validation. +- `--use-webgpu-adapter=[default,swiftshader,compat]`: Forwarded to the browser to select a particular WebGPU adapter. + +[use-webgpu-power-preference]: https://source.chromium.org/chromium/chromium/src/+/main:gpu/command_buffer/service/service_utils.cc;l=114-121;drc=73bcf25e4b0c06b1a86422a2fc30023c7b850f33 + +Other useful command-line arguments: + +- `--help`: See more options and argument documentation. +- `-l`: List all tests that would be run. +- `--extra-browser-args`: Pass extra args to the browser executable. +- `--stable-jobs`: Assign tests to each job in a stable order. Used on the bots + for consistency and ease of reproduction. If you are reproducing + order-dependent issues that appear on bots, you'll need this and `--jobs=N`. ## Running the CTS locally on Android @@ -32,7 +47,7 @@ An example of a known-working command line is: ```sh -./content/test/gpu/run_gpu_integration_test.py webgpu_cts --show-stdout --browser=android-chromium --stable-jobs --jobs=1 --extra-browser-args="--enable-logging=stderr --js-flags=--expose-gc --force_high_performance_gpu --use-webgpu-power-preference=default-high-performance" +./content/test/gpu/run_gpu_integration_test.py webgpu_cts --show-stdout --browser=android-chromium --stable-jobs --jobs=1 --extra-browser-args="--enable-logging=stderr --js-flags=--expose-gc" ``` Be aware that running the tests locally on Android is *SLOW*. Expect it to take 4 hrs+.