test: add electron contract tests (#1140)

This PR will:
- add contract test implementation to Electron
- add contract test runs into electron GHA workflow

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk due to new CI jobs and scheduled runs that spin up
Electron/Xvfb and execute the shared contract-test harness, which can
introduce flakiness and longer runtimes. Changes are mostly test-only
but add new dependencies and AWS-secret retrieval for e2e example runs.
> 
> **Overview**
> Adds **Electron SDK contract testing** by introducing a new
`packages/sdk/electron/contract-tests/entity` Electron app that exposes
the SDK test-harness REST protocol (create client, run commands, delete
client, shutdown) and maps harness config into `LDOptions` (endpoints,
events, TLS, hooks, etc.).
> 
> Updates the Electron GitHub Actions workflow to run nightly, build and
launch the contract-test entity headlessly via Xvfb/Playwright, wait for
port `8000`, and then run the `launchdarkly/gh-actions` contract tests
(with `suppressions.txt`). Also adds a new `run-example` CI job that
builds the Electron example and runs Playwright e2e using AWS-sourced
test keys.
> 
> Extends the Electron example with a Playwright-based smoke test, adds
`build`/`test` scripts and Playwright deps, and tweaks `.gitignore` to
capture `test-results/`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
814d2b5. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: semgrep-code-launchdarkly[bot] <167133144+semgrep-code-launchdarkly[bot]@users.noreply.github.com>

Author: joker23

.github/workflows/electron.yaml

@@ -9,15 +9,13 @@ on:
     branches: [main, 'feat/**']
     paths-ignore:
       - '**.md'
-  # TODO: re-enable this when we set up the example tests.
-  # schedule:
-  #   - cron: '0 0 * * *'
+  schedule:
+    - cron: '0 0 * * *'
 
 jobs:
   build-test-electron:
     # Skip this job on scheduled runs to avoid redundant runs.
-    # TODO: re-enable this when we set up the example tests.
-    # if: github.event_name != 'schedule'
+    if: github.event_name != 'schedule'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -36,29 +34,78 @@ jobs:
           workspace_name: '@launchdarkly/electron-client-sdk'
           workspace_path: packages/sdk/electron
 
-  # TODO: Add example tests - we will do this in tandem with the contract tests
-  # as they will need to have a similar kind of setup.
-  # run-example:
-  #   runs-on: ubuntu-latest
-  #   permissions:
-  #     id-token: write
-  #   steps:
-  #     - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-  #     - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
-  #       with:
-  #         node-version: 24
-  #     - name: Setup Yarn
-  #       run: yarn set version 3.4.1
-  #     - name: Install dependencies
-  #       run: yarn workspaces focus @internal/electron-example
-  #     - name: Build SDK dependencies
-  #       run: yarn workspaces foreach -pR --topological-dev --from '@internal/electron-example' run build
-  #     - name: Install Xvfb
-  #       run: sudo apt-get install -y xvfb
-  #     - uses: launchdarkly/gh-actions/actions/verify-hello-app@verify-hello-app-v1.0.0
-  #       with:
-  #         use_mobile_key: true
-  #         role_arn: ${{ vars.AWS_ROLE_ARN }}
-  #         command: xvfb-run -a yarn workspace @internal/electron-example start -- --no-sandbox
+      # Contract Tests
+      - name: Install contract test dependencies
+        env:
+          ELECTRON_DISABLE_SANDBOX: '1'
+        run: |
+          yarn workspaces focus @internal/electron-contract-tests-entity
+          yarn workspace @internal/electron-contract-tests-entity build
+          sudo apt-get install -y xvfb
+          Xvfb :99 -screen 0 1024x768x24 > /tmp/xvfb.log 2>&1 &
 
-# TODO: Add contract tests
+      - name: run contract test entity
+        env:
+          ELECTRON_DISABLE_SANDBOX: '1'
+          DISPLAY: ':99'
+        run: |
+          yarn workspace @internal/electron-contract-tests-entity open-electron &> /tmp/http-server.log &
+          echo "Waiting for contract test entity on port 8000..."
+          for i in {1..30}; do
+            if curl -s http://localhost:8000 > /dev/null; then
+              echo "Contract test entity ready"
+              break
+            fi
+            if [ $i -eq 30 ]; then
+              echo "Timeout waiting for contract test entity"
+              cat /tmp/http-server.log
+              exit 1
+            fi
+            sleep 1
+          done
+
+      - name: Run contract tests
+        uses: launchdarkly/gh-actions/actions/contract-tests@5adb11fd6953e1bc35d9cf1fc1b4374c464e3a8b
+        with:
+          test_service_port: 8000
+          token: ${{ secrets.GITHUB_TOKEN }}
+          extra_params: '--skip-from=${{ github.workspace }}/packages/sdk/electron/contract-tests/suppressions.txt --stop-service-at-end'
+
+  run-example:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: 24
+      - name: Install dependencies
+        run: yarn workspaces focus @internal/electron-example
+      - name: Build SDK dependencies
+        run: yarn workspaces foreach -pR --topological-dev --from '@internal/electron-example' run build
+      - name: Build example app
+        env:
+          ELECTRON_DISABLE_SANDBOX: '1'
+        run: yarn workspace @internal/electron-example build
+      - name: Setup Xvfb
+        run: |
+          sudo apt-get install -y xvfb
+          Xvfb :99 -screen 0 1024x768x24 > /tmp/xvfb.log 2>&1 &
+      - name: Install Playwright dependencies
+        run: yarn workspace @internal/electron-example playwright install --with-deps chromium
+      - uses: launchdarkly/gh-actions/actions/release-secrets@bbbbbda684f500766264e7fe327668094ba83d1c # release-secrets-v1.2.0
+        name: 'Get the mobile SDK key'
+        with:
+          aws_assume_role: ${{ vars.AWS_ROLE_ARN }}
+          ssm_parameter_pairs: '/sdk/common/hello-apps/mobile-key = LAUNCHDARKLY_MOBILE_KEY'
+      - uses: launchdarkly/gh-actions/actions/release-secrets@bbbbbda684f500766264e7fe327668094ba83d1c # release-secrets-v1.2.0
+        name: 'Get the test feature flag key'
+        with:
+          aws_assume_role: ${{ vars.AWS_ROLE_ARN  }}
+          ssm_parameter_pairs: '/sdk/common/hello-apps/boolean-flag-key = LAUNCHDARKLY_FLAG_KEY'
+      - name: Run e2e tests
+        env:
+          ELECTRON_DISABLE_SANDBOX: '1'
+          DISPLAY: ':99'
+        run: yarn workspace @internal/electron-example test

package.json

@@ -15,6 +15,7 @@
     "packages/sdk/cloudflare/example",
     "packages/sdk/electron",
     "packages/sdk/electron/example",
+    "packages/sdk/electron/contract-tests/entity",
     "packages/sdk/fastly",
     "packages/sdk/fastly/example",
     "packages/sdk/react",

packages/sdk/electron/contract-tests/README.md

@@ -0,0 +1,67 @@
+# Electron SDK Contract Tests
+
+This directory contains the contract test implementation for the LaunchDarkly Electron SDK using the [SDK Test Harness](https://github.com/launchdarkly/sdk-test-harness).
+
+## Architecture
+
+The Electron contract tests use a single component:
+
+**Entity** (`entity/`): An Electron application that:
+
+- Runs an Express server in the **main process** on port 8000
+- Exposes a REST API that the test harness calls directly (no separate adapter)
+- Creates and manages Electron SDK clients via `ClientFactory` in response to harness commands
+- Implements the contract test protocol: create client (POST /), run commands (POST /clients/:id), delete client (DELETE /clients/:id), shutdown (DELETE /)
+
+The test harness sends HTTP requests to the entity’s REST API. The entity runs the Electron SDK in the main process and responds with evaluation results and other command outputs.
+
+## Running Locally
+
+### Prerequisites
+
+- Node.js 18 or later
+- Yarn
+- Electron-supported platform (macOS, Windows, or Linux). For headless/CI, a virtual display (e.g. xvfb on Linux) may be required.
+
+### Quick start
+
+1. **Install dependencies** from the repository root:
+   ```bash
+   yarn
+   ```
+
+2. **Build the entity** so the Electron app has a built main process. From the repository root:
+   ```bash
+   yarn workspaces foreach -pR --topological-dev --from @internal/electron-contract-tests-entity run build
+   ```
+
+3. **Start the contract test entity** (the Electron app with the REST server on port 8000). From the repository root:
+   ```bash
+   yarn workspace @internal/electron-contract-tests-entity run start
+   ```
+   Or from `entity/`:
+   ```bash
+   yarn start
+   ```
+   The app window may open; the server runs in the main process. Keep it running while you run the harness.
+
+   For a headless run (e.g. CI), use the open-electron script instead:
+   ```bash
+   yarn workspace @internal/electron-contract-tests-entity run open-electron
+   ```
+   This launches the built app via Playwright’s Electron API and keeps it running until you press Ctrl+C.
+
+4. **Run the SDK test harness** against the entity. The entity’s REST API is at:
+   - **Base URL:** http://localhost:8000
+
+   Example with a local clone of the test harness:
+   ```bash
+   go run . --url http://localhost:8000
+   ```
+
+   If you have a suppressions file (e.g. for known differences), pass it with `-skip-from`:
+   ```bash
+   go run . --url http://localhost:8000 -skip-from path-to-js-core/packages/sdk/electron/contract-tests/suppressions.txt
+   ```
+
+More details on the harness: https://github.com/launchdarkly/sdk-test-harness

packages/sdk/electron/contract-tests/entity/.gitignore

@@ -0,0 +1,92 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+.DS_Store
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Webpack
+.webpack/
+
+# Vite
+.vite/
+
+# Electron-Forge
+out/

packages/sdk/electron/contract-tests/entity/forge.config.ts

@@ -0,0 +1,45 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { MakerDeb } from '@electron-forge/maker-deb';
+import { MakerRpm } from '@electron-forge/maker-rpm';
+import { MakerSquirrel } from '@electron-forge/maker-squirrel';
+import { MakerZIP } from '@electron-forge/maker-zip';
+import { FusesPlugin } from '@electron-forge/plugin-fuses';
+import { VitePlugin } from '@electron-forge/plugin-vite';
+import type { ForgeConfig } from '@electron-forge/shared-types';
+import { FuseV1Options, FuseVersion } from '@electron/fuses';
+
+const config: ForgeConfig = {
+  packagerConfig: {
+    asar: true,
+  },
+  rebuildConfig: {},
+  makers: [new MakerSquirrel({}), new MakerZIP({}, ['darwin']), new MakerRpm({}), new MakerDeb({})],
+  plugins: [
+    new VitePlugin({
+      // `build` can specify multiple entry builds, which can be Main process, Preload scripts, Worker process, etc.
+      // If you are familiar with Vite configuration, it will look really familiar.
+      build: [
+        {
+          // `entry` is just an alias for `build.lib.entry` in the corresponding file of `config`.
+          entry: 'src/main.ts',
+          config: 'vite.main.config.ts',
+          target: 'main',
+        },
+      ],
+      renderer: [],
+    }),
+    // Fuses are used to enable/disable various Electron functionality
+    // at package time, before code signing the application
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      [FuseV1Options.RunAsNode]: false,
+      [FuseV1Options.EnableCookieEncryption]: true,
+      [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
+      [FuseV1Options.EnableNodeCliInspectArguments]: false,
+      [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
+      [FuseV1Options.OnlyLoadAppFromAsar]: true,
+    }),
+  ],
+};
+
+export default config;

packages/sdk/electron/contract-tests/entity/forge.env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="@electron-forge/plugin-vite/forge-vite-env" />
+
+/** Injected at build time from LD_CLIENT_SIDE_ID (see vite.renderer.config.ts). */
+// eslint-disable-next-line no-underscore-dangle
+declare const __LD_CLIENT_SIDE_ID__: string;

packages/sdk/electron/contract-tests/entity/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>Hello World!</title>
+  </head>
+  <body>
+    <h1>💖 Hello World!</h1>
+    <p>Welcome to your Electron application.</p>
+    <script type="module" src="/src/renderer.ts"></script>
+  </body>
+</html>

packages/sdk/electron/contract-tests/entity/open-electron.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Opens the Electron app and keeps it running until the process is terminated.
+ * Run from the entity directory after building (e.g. after running start:debug once).
+ *
+ * Usage: node open-electron.mjs
+ */
+
+const { _electron: electron } = await import('playwright');
+
+console.log('Launching Electron app...');
+
+let close = null;
+
+const lifetimePromise = new Promise((resolve) => {
+  close = resolve;
+});
+
+const electronApp = await electron.launch({
+  args: ['.vite/build/main.js'],
+  cwd: process.cwd(),
+});
+
+console.log('Electron contract test entity is running. Press Ctrl+C to close.');
+
+electronApp.on('close', () => {
+  close();
+});
+
+await lifetimePromise;