Create WGPUPY_WGPU_ADAPTER_NAME environment variable

similar to https://github.com/gfx-rs/wgpu?tab=readme-ov-file#environment-variables

README.md

@@ -178,3 +178,16 @@ differences.
 
 If you want to update the reference screenshot for a given example, you can grab
 those from the build artifacts as well and commit them to your branch.
+
+### Testing Locally
+
+Testing locally is possible, however pixel perfect results will differ from
+those on the CIs due to discrepencies in hardware, and driver (we use llvmpipe)
+versions.
+
+If you want to force the usage of LLVMPIPE to speed up local testing you
+may do so with the WGPUPY_WGPU_ADAPTER_NAME environment variable
+
+```
+WGPUPY_WGPU_ADAPTER_NAME=llvmpipe pytest -v examples/
+```

examples/tests/test_examples.py

@@ -96,7 +96,7 @@ def unload_module():
     if not is_lavapipe:
         pytest.skip(
             "screenshot comparisons are only done when using lavapipe. "
-            "Rerun with WGPU_FORCE_OFFSCREEN=true"
+            "Rerun your tests with WGPUPY_WGPU_ADAPTER_NAME=llvmpipe"
         )
 
     # regenerate screenshot if requested

wgpu/backends/wgpu_native/_api.py

@@ -367,6 +367,21 @@ def request_adapter_sync(
         This is the implementation based on wgpu-native.
         """
         check_can_use_sync_variants()
+        # Similar to https://github.com/gfx-rs/wgpu?tab=readme-ov-file#environment-variables
+        # It seems that the environment variables are only respected in their
+        # testing environments maybe????
+        # In Dec 2024 we couldn't get the use of their environment variables to work
+        # This should only be used in testing environments and API users
+        # should beware
+        # We chose the variable name WGPUPY_WGPU_ADAPTER_NAME instead WGPU_ADAPTER_NAME
+        # to avoid a clash
+        if adapter_name := os.getenv(("WGPUPY_WGPU_ADAPTER_NAME")):
+            adapters = self.enumerate_adapters_sync()
+            adapters_llvm = [a for a in adapters if adapter_name in a.summary]
+            if not adapters_llvm:
+                raise ValueError(f"Adapter with name '{adapter_name}' not found.")
+            return adapters_llvm[0]
+
         awaitable = self._request_adapter(
             power_preference=power_preference,
             force_fallback_adapter=force_fallback_adapter,
@@ -394,6 +409,23 @@ async def request_adapter_async(
             canvas : The canvas that the adapter should be able to render to. This can typically
                  be left to None. If given, the object must implement ``WgpuCanvasInterface``.
         """
+        # Similar to https://github.com/gfx-rs/wgpu?tab=readme-ov-file#environment-variables
+        # It seems that the environment variables are only respected in their
+        # testing environments maybe????
+        # In Dec 2024 we couldn't get the use of their environment variables to work
+        # This should only be used in testing environments and API users
+        # should beware
+        # We chose the variable name WGPUPY_WGPU_ADAPTER_NAME instead WGPU_ADAPTER_NAME
+        # to avoid a clash
+        if adapter_name := os.getenv(("WGPUPY_WGPU_ADAPTER_NAME")):
+            # Is this correct for async??? I know nothing of async...
+            awaitable = self.enumerate_adapters_async()
+            adapters = await awaitable
+            adapters_llvm = [a for a in adapters if adapter_name in a.summary]
+            if not adapters_llvm:
+                raise ValueError(f"Adapter with name '{adapter_name}' not found.")
+            return adapters_llvm[0]
+
         awaitable = self._request_adapter(
             power_preference=power_preference,
             force_fallback_adapter=force_fallback_adapter,