refactor(testutils): extract macOS device-cache warm-up into shared helper

The PreviewSignTests static ctor's polling block defeats a YubiKeyDeviceListener
startup race specific to macOS (the IOKit run loop arms on a background thread
and Update() can return before the first arrival callback fires). The same
race will affect any other Fido2/Hid integration test class whose base
constructor enumerates devices, so promote the workaround into
DeviceListenerCacheWarmup.WaitForFirstDevice() in TestUtilities.

PreviewSignTests now calls the helper from its static ctor; behavior is
unchanged. Other test classes can adopt the helper as needed.

Underlying SDK race remains unfixed and tracked separately — a real fix
needs to drive synchronous initial enumeration through MacOSHidDeviceListener
or have YubiKeyDeviceListener.Update() wait for the first callback pass,
both of which are larger than this PR's scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DennisDyallo

Yubico.YubiKey/tests/integration/Yubico/YubiKey/Fido2/PreviewSignTests.cs

@@ -29,36 +29,10 @@ namespace Yubico.YubiKey.Fido2
     /// </remarks>
     public class PreviewSignTests : FidoSessionIntegrationTestBase
     {
-        // Wait for the YubiKeyDeviceListener's internal cache to populate
-        // before any instance constructor runs. On macOS the listener's
-        // _internalCache (read by FindByTransport(All).GetAll()) is
-        // populated asynchronously by background USB notifications; without
-        // this poll the base class ctor's GetSession() call races the
-        // listener and throws DeviceNotFoundException even when a supported
-        // YubiKey is plugged in.
-        //
-        // Polls every 100ms for up to 5 seconds. Returns as soon as at least
-        // one device is visible, OR after the timeout (in which case the
-        // tests SKIP cleanly via [SkippableFact(typeof(DeviceNotFoundException))]).
-        static PreviewSignTests()
-        {
-            try
-            {
-                for (int i = 0; i < 50; i++)
-                {
-                    if (YubiKeyDevice.FindAll().Any())
-                    {
-                        return;
-                    }
-                    System.Threading.Thread.Sleep(100);
-                }
-            }
-            catch
-            {
-                // Swallow — if enumeration throws, tests SKIP via
-                // DeviceNotFoundException anyway.
-            }
-        }
+        // Defeat the macOS YubiKeyDeviceListener startup race before the
+        // base class's instance ctor runs. See DeviceListenerCacheWarmup
+        // for the full rationale.
+        static PreviewSignTests() => DeviceListenerCacheWarmup.WaitForFirstDevice();
 
         [SkippableFact(typeof(DeviceNotFoundException))]
         public void MakeCredentialWithPreviewSign_ReturnsGeneratedKey()

Yubico.YubiKey/tests/utilities/Yubico/YubiKey/TestUtilities/DeviceListenerCacheWarmup.cs

@@ -0,0 +1,72 @@
+// Copyright 2025 Yubico AB
+//
+// Licensed under the Apache License, Version 2.0 (the "License").
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Linq;
+using System.Threading;
+
+namespace Yubico.YubiKey.TestUtilities
+{
+    /// <summary>
+    /// Workaround for a YubiKeyDeviceListener startup race observed on macOS:
+    /// MacOSHidDeviceListener arms its IOKit run loop on a background thread,
+    /// so the first call to YubiKeyDeviceListener.Update() (which runs
+    /// synchronously in the listener's constructor) can complete before the
+    /// HID layer has fired its initial arrival callbacks. The result is a
+    /// transient empty cache for ~hundreds of milliseconds after the listener
+    /// is created, which makes test base classes that enumerate in their
+    /// instance constructor see DeviceNotFoundException even when a device is
+    /// plugged in.
+    ///
+    /// Intended use: invoke from a test class's static constructor (runs once,
+    /// before any [Fact] body) so the listener has time to populate before
+    /// instance construction kicks off.
+    ///
+    /// SDK fix tracked separately. Until then, every Fido2/Hid integration
+    /// test class that doesn't already do its own warm-up should call this.
+    /// </summary>
+    public static class DeviceListenerCacheWarmup
+    {
+        /// <summary>
+        /// Poll YubiKeyDevice.FindAll() until it returns at least one device,
+        /// or until the timeout elapses. Returns silently in either case;
+        /// downstream tests are expected to SKIP cleanly via
+        /// DeviceNotFoundException if no device materialises.
+        /// </summary>
+        /// <param name="timeoutMilliseconds">Total wall-clock budget. Default 5s.</param>
+        /// <param name="pollIntervalMilliseconds">Poll interval. Default 100ms.</param>
+        public static void WaitForFirstDevice(
+            int timeoutMilliseconds = 5000,
+            int pollIntervalMilliseconds = 100)
+        {
+            try
+            {
+                int iterations = timeoutMilliseconds / pollIntervalMilliseconds;
+                for (int i = 0; i < iterations; i++)
+                {
+                    if (YubiKeyDevice.FindAll().Any())
+                    {
+                        return;
+                    }
+
+                    Thread.Sleep(pollIntervalMilliseconds);
+                }
+            }
+            catch
+            {
+                // Swallow — if enumeration throws, downstream test skip path
+                // (DeviceNotFoundException) handles user feedback.
+            }
+        }
+    }
+}