test(device): load BrowserStack config from the root .env file

Running the device suite meant exporting BROWSERSTACK_* by hand each time.
The config now loads the repo root's `.env` (gitignored; the entries are
documented in `.env.sample`, the repo's one sample file) — dotenv parsing
accepts its shell-style `export KEY=value` lines, so the same file keeps
working for `source`. Real environment variables take precedence, so CI is
unaffected, and the missing-credentials error points at the file.

Author: YousefED

.env.sample

@@ -1,2 +1,13 @@
 export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://cache.nickthesick.com
-export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=g8@ucL8em4*Z9TKXDY9OEX@!upf^Nz9
+export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=g8@ucL8em4*Z9TKXDY9OEX@!upf^Nz9
+
+# BrowserStack credentials for the real-device suite (`pnpm run test:device`).
+# From browserstack.com/accounts/profile. Without them the suite skips itself.
+export BROWSERSTACK_USERNAME=
+export BROWSERSTACK_ACCESS_KEY=
+
+# Optional, also for the device suite: where the devices load the app from
+# (default: the local dev server started with `pnpm run dev`), and a device
+# subset — substring of an id in tests/device/devices.ts.
+# export DEVICE_TEST_TARGET=http://127.0.0.1:5173
+# export DEVICE_FILTER=android

tests/device/README.md

@@ -21,6 +21,10 @@ pnpm run dev
 BROWSERSTACK_USERNAME=... BROWSERSTACK_ACCESS_KEY=... pnpm run test:device
 ```
 
+Instead of exporting the variables each time, copy the repo root's
+`.env.sample` to `.env` (gitignored) and fill in the BrowserStack entries —
+the config loads it, with real environment variables taking precedence.
+
 Environment knobs:
 
 | Variable                                            | Purpose                                                                                  |

tests/device/lib/webdriver.ts

@@ -36,7 +36,8 @@ export class DeviceSession {
     const auth = browserStackCredentials();
     if (!auth) {
       throw new Error(
-        "BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY must be set",
+        "BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY must be set " +
+          "(exported, or in the repo root .env — see .env.sample)",
       );
     }
     // Device allocation occasionally hiccups; one retry absorbs it.

tests/device/vitest.config.mts

@@ -1,4 +1,22 @@
-import { defineConfig } from "vite-plus";
+import path from "node:path";
+import { defineConfig, loadEnv } from "vite-plus";
+
+// The suite reads its configuration from the environment; the repo root's
+// `.env` (copied from `.env.sample`) works too. Loaded here because vitest
+// does not load env files into `process.env` on its own — dotenv parsing
+// accepts the sample's shell-style `export KEY=value` lines. Real environment
+// variables win over the file.
+const fileEnv = loadEnv("", path.resolve(import.meta.dirname, "../.."), "");
+for (const key of [
+  "BROWSERSTACK_USERNAME",
+  "BROWSERSTACK_ACCESS_KEY",
+  "DEVICE_TEST_TARGET",
+  "DEVICE_FILTER",
+]) {
+  if (process.env[key] === undefined && fileEnv[key] !== undefined) {
+    process.env[key] = fileEnv[key];
+  }
+}
 
 /**
  * Real-device suite (BrowserStack). Not part of the workspace projects on