feat: custom env variables capabilities

Author: y-schwab

lib/commands/powershell.ts

@@ -12,7 +12,16 @@ const NULL_ROOT_ELEMENT = /* ps1 */ `$rootElement = $null`;
 const INIT_ELEMENT_TABLE = /* ps1 */ `$elementTable = New-Object System.Collections.Generic.Dictionary[[string]\`,[AutomationElement]]`;
 
 export async function startPowerShellSession(this: NovaWindowsDriver): Promise<void> {
-    const powerShell = spawn('powershell.exe', ['-NoExit', '-Command', '-']);
+    const spawnEnv = this.caps.appEnvironment
+        ? { ...process.env, ...(this.caps.appEnvironment as Record<string, string>) }
+        : process.env;
+
+    if (this.caps.appEnvironment) {
+        const keys = Object.keys(this.caps.appEnvironment as Record<string, string>);
+        this.log.info(`Applying appEnvironment variables to PowerShell session: ${keys.join(', ')}`);
+    }
+
+    const powerShell = spawn('powershell.exe', ['-NoExit', '-Command', '-'], { env: spawnEnv });
     powerShell.stdout.setEncoding('utf8');
     powerShell.stderr.setEncoding('utf8');
 
@@ -93,7 +102,10 @@ export async function startPowerShellSession(this: NovaWindowsDriver): Promise<v
 export async function sendIsolatedPowerShellCommand(this: NovaWindowsDriver, command: string): Promise<string> {
     const magicNumber = 0xF2EE;
 
-    const powerShell = spawn('powershell.exe', ['-NoExit', '-Command', '-']);
+    const spawnEnv = this.caps.appEnvironment
+        ? { ...process.env, ...(this.caps.appEnvironment as Record<string, string>) }
+        : process.env;
+    const powerShell = spawn('powershell.exe', ['-NoExit', '-Command', '-'], { env: spawnEnv });
     try {
         powerShell.stdout.setEncoding('utf8');
         powerShell.stdout.setEncoding('utf8');

lib/constraints.ts

@@ -36,6 +36,9 @@ export const UI_AUTOMATION_DRIVER_CONSTRAINTS = {
     isolatedScriptExecution: {
         isBoolean: true,
     },
+    appEnvironment: {
+        isObject: true,
+    },
     'ms:waitForAppLaunch': {
         isNumber: true,
     },

test/e2e/session.e2e.ts

@@ -1,4 +1,4 @@
-import { existsSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { beforeEach, describe, expect, it } from 'vitest';
@@ -136,6 +136,22 @@ describe('Session creation and capabilities', () => {
         if (existsSync(markerPath)) { unlinkSync(markerPath); }
     });
 
+    it('passes appEnvironment variables into the PowerShell session', async () => {
+        const markerPath = join(tmpdir(), `novawindows-session-env-${Date.now()}.txt`);
+        const driver = await createRootSession({
+            'appium:appEnvironment': { NOVA_TEST_VAR: 'hello_from_env' },
+            'appium:prerun': {
+                script: `[System.IO.File]::WriteAllText('${markerPath}', $env:NOVA_TEST_VAR)`,
+            },
+        });
+        try {
+            expect(readFileSync(markerPath, 'utf8')).toBe('hello_from_env');
+        } finally {
+            await quitSession(driver);
+            if (existsSync(markerPath)) { unlinkSync(markerPath); }
+        }
+    });
+
     it('throws when an unknown automationName is specified', async () => {
         const { remote } = await import('webdriverio');
         await expect(