From ad0c8d4f781aaf9907b5f3a90bc7d00a13c51153 Mon Sep 17 00:00:00 2001
From: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
Date: Mon, 21 Jun 2021 21:13:38 -0400
Subject: [PATCH] Add documentation

---
 README.md                         | 28 ++++++++++++++++++++++++++++
 wgpu/examples/README.md           |  2 +-
 wgpu/examples/wgpu-info/README.md | 17 +++++++++++++++++
 wgpu/examples/wgpu-info/main.rs   | 18 +++++++++---------
 4 files changed, 55 insertions(+), 10 deletions(-)
 create mode 100644 wgpu/examples/wgpu-info/README.md

diff --git a/README.md b/README.md
index a18829e564..e0687304e4 100644
--- a/README.md
+++ b/README.md
@@ -32,3 +32,31 @@ If you are looking for the native implementation or bindings to the API in other
   GLes3  |                    |                    |                    |
 
 :white_check_mark: = Primary support — :ok: = Secondary support — :construction: = Unsupported, but support in progress
+
+## Testing Infrastructure
+
+wgpu features a set of unit, integration, and example based tests. All framework based examples are automatically reftested against the screenshot in the example directory. The `wgpu-info` example contains the logic which can automatically run the tests multiple times for all the adapters present on the system. These tests are also run on CI on windows and linux over Vulkan/DX12/DX11/GL on software adapters.
+
+To run the test suite, run the following command:
+
+```
+cargo run --example wgpu-info -- cargo test
+```
+
+To run any individual test on a specific adapter, populate the following environment variables:
+- `WGPU_ADAPTER_NAME` with a substring of the name of the adapter you want to use (ex. "1080" will match "NVIDIA GeForce 1080ti").
+- `WGPU_BACKEND` with the name of the backend you want to use (`vulkan`, `metal`, `dx12`, `dx11`, or `gl`).
+
+Then to run an example's reftests, run:
+
+```
+cargo test --example <example-name>
+```
+
+Or run a part of the integration test suite:
+
+```
+cargo test -p wgpu -- <name-of-test>
+```
+
+If you are a user and want a way to help contribute to wgpu, we always need more help writing test cases. 
diff --git a/wgpu/examples/README.md b/wgpu/examples/README.md
index 46eeefebd0..ad7b342fa2 100644
--- a/wgpu/examples/README.md
+++ b/wgpu/examples/README.md
@@ -9,7 +9,7 @@ Notably, `capture` example shows rendering without a surface/window. It reads ba
 
 All the examples use [WGSL](https://gpuweb.github.io/gpuweb/wgsl.html) shaders unless specified otherwise.
 
-All framework-based examples render to the window.
+All framework-based examples render to the window and are reftested against the screenshot in the directory.
 
 ## Feature matrix
 | Feature                      | boids  | bunnymark | cube   | mipmap | msaa-line | shadow | skybox | texture-arrays | water  | conservative-raster |
diff --git a/wgpu/examples/wgpu-info/README.md b/wgpu/examples/wgpu-info/README.md
new file mode 100644
index 0000000000..186577163a
--- /dev/null
+++ b/wgpu/examples/wgpu-info/README.md
@@ -0,0 +1,17 @@
+# wgpu-info
+
+This example is a command line utility that does two different functions. 
+
+#### Listing Adapters
+
+When called with no arguments, wgpu-info will list all adapters visible to wgpu and all the information about them we have.
+
+```
+cargo run --example wgpu-info
+```
+
+#### Running Test on many Adapters
+
+When called with any amount of arguments it will interpret all of the arguments as a command to run. It will run this command N different times, one for every combination of adapter and backend on the system.
+
+For every command invocation, it will set `WGPU_ADAPTER_NAME` to the name of the adapter name and `WGPU_BACKEND` to the name of the backend. This is used as the primary means of testing across many adapters.
diff --git a/wgpu/examples/wgpu-info/main.rs b/wgpu/examples/wgpu-info/main.rs
index 72970d1c8b..8b921b4f75 100644
--- a/wgpu/examples/wgpu-info/main.rs
+++ b/wgpu/examples/wgpu-info/main.rs
@@ -84,13 +84,13 @@ fn main() {
         .collect();
     let adapter_count = adapters.len();
 
-    let all_start = Instant::now();
-
     if args.is_empty() {
         for (idx, adapter) in adapters.into_iter().enumerate() {
             print_info_from_adapter(&adapter, idx)
         }
     } else {
+        let all_start = Instant::now();
+        
         for (idx, adapter) in adapters.into_iter().enumerate() {
             let adapter_start_time = Instant::now();
             let idx = idx + 1;
@@ -134,12 +134,12 @@ fn main() {
                 exit(1);
             }
         }
+
+        let all_time = all_start.elapsed().as_secs_f32();
+
+        println!(
+            "=========== {} adapters PASSED in {:.3}s ===========",
+            adapter_count, all_time
+        );
     }
-
-    let all_time = all_start.elapsed().as_secs_f32();
-
-    println!(
-        "=========== {} adapters PASSED in {:.3}s ===========",
-        adapter_count, all_time
-    );
 }