From 125a63d349e8ff40ee22f753b8f44e9377de3050 Mon Sep 17 00:00:00 2001
From: Max Desiatov <m_desiatov@apple.com>
Date: Thu, 11 Dec 2025 09:06:42 +0000
Subject: [PATCH] docs/WebAssembly.md: add Wasm stdlib testing steps (#85947)

Added instructions for building and running Wasm stdlib tests, including filtering options and environment variable usage.
---
 docs/WebAssembly.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/docs/WebAssembly.md b/docs/WebAssembly.md
index 777323ee24c..de59364c199 100644
--- a/docs/WebAssembly.md
+++ b/docs/WebAssembly.md
@@ -30,10 +30,46 @@ tools, and also builds WasmKit to execute stdlib tests:
 
 On macOS it's also best to avoid cross-compiling host tools from arm64 to x86 and vice versa, add this option to avoid that: `--infer-cross-compile-hosts-on-darwin=false`.
 
+If you need to only run compiler/stdlib tests after building everything with the `build-script` command listed above, switch to the build directory first:
+
+```
+cd build/Ninja-RelWithDebInfoAssert
+```
+
+Then run the compiler and stdlib test suite via `ninja` (assuming your host is arm64 macOS, adjust paths accordingly otherwise):
+
+```
+PATH="$(pwd)/wasmkit-macosx-arm64/bin:$(pwd)/llvm-macosx-arm64/bin:$PATH" \
+  ninja check-swift-wasi-wasm32-custom check-swift-embedded-wasi -C wasmstdlib-macosx-arm64
+```
+
+Filter to a subset of tests you'd like to run with `LIT_FILTER`. Here's an example to run only tests with `embedded` in their file path:
+
+```
+LIT_FILTER='(embedded)' PATH="$(pwd)/wasmkit-macosx-arm64/bin:$(pwd)/llvm-macosx-arm64/bin:$PATH" \
+  ninja check-swift-wasi-wasm32-custom check-swift-embedded-wasi -C wasmstdlib-macosx-arm64
+```
+
+Filter out tests you don't want to run with `LIT_FILTER_OUT`. Here's an example that excludes tests containing `KeyPath` in their file path:
+
+```
+LIT_FILTER_OUT='(KeyPath)' PATH="$(pwd)/wasmkit-macosx-arm64/bin:$(pwd)/llvm-macosx-arm64/bin:$PATH" \
+  ninja check-swift-wasi-wasm32-custom check-swift-embedded-wasi -C wasmstdlib-macosx-arm64
+```
+
+Values passed to these environment variables are regular expressions, thus to exclude both `embedded` and `KeyPath`
+use `|` regex operator:
+
+```
+LIT_FILTER_OUT='(embedded|KeyPath)' PATH="$(pwd)/wasmkit-macosx-arm64/bin:$(pwd)/llvm-macosx-arm64/bin:$PATH" \
+  ninja check-swift-wasi-wasm32-custom check-swift-embedded-wasi -C wasmstdlib-macosx-arm64
+```
+
+
 ## Building Swift SDK for WebAssembly
 
 The [Swift SDK](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md)
-for WebAssembly is built and tested using the following command:
+for WebAssembly is built and tested using the following command (exclude `--sccache` if it's not installed or build caching is not needed):
 
 ```bash
 ./utils/build-script --sccache --build-wasm-stdlib --wasmkit --install-llvm --install-swift --swiftpm --install-swiftpm \