Add documentation

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. 

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 |

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.

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
-    );
 }