@trackunit/iris-app-e2e 0.0.2-alpha-49e9177e1b3.0

package/README.md

@@ -0,0 +1,227 @@
+# @trackunit/iris-app-e2e
+
+A comprehensive E2E testing utilities library for Trackunit's Iris platform. This package provides reusable Cypress commands, setup utilities, and configuration helpers to streamline E2E testing for both internal and external developers.
+
+This library is exposed publicly for use in the Trackunit [Iris App SDK](https://www.npmjs.com/package/@trackunit/iris-app).
+
+To browse all available components visit our [Public Storybook](https://apps.iris.trackunit.com/storybook/).
+
+For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
+
+## Installation
+
+```bash
+npm install @trackunit/iris-app-e2e --save-dev
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm install cypress @testing-library/cypress --save-dev
+```
+
+## Features
+
+### 🔧 Cypress Commands
+
+- **`getByTestId`** - Enhanced data-testid selector with timeout options
+- **`login`** - Automated login with support for multiple user fixtures
+- **`switchToLocalDevMode`** - Switch to local development mode in Iris SDK portal
+- **`enterIrisApp`** - Navigate into Iris app iframes for testing
+- **`enterStorybookPreview`** - Access Storybook preview iframes
+- **`getValidateFeatureFlags`** - Set up feature flag validation intercepts
+- **`configCat`** - Retrieve ConfigCat feature flag states
+
+### 🚀 E2E Setup Utilities
+
+- **`setupE2E`** - Complete E2E test environment setup
+- **`setupHarRecording`** - HAR file recording for failed tests
+- **Terminal logging** - Comprehensive test logging and error capture
+
+### ⚙️ Plugin Configuration
+
+- **`defaultCypressConfig`** - Configurable Cypress configuration
+- **`setupPlugins`** - Plugin setup with logging and HAR generation
+- **File utilities** - Log file creation and formatting tools
+
+## Usage
+
+### Basic Setup
+
+Create a `cypress/support/e2e.ts` file:
+
+```typescript
+import { setupDefaultCommands, setupE2E } from '@trackunit/iris-app-e2e';
+
+// Set up E2E environment
+setupE2E();
+
+// Register custom commands
+setupDefaultCommands();
+```
+
+### Cypress Configuration
+
+Create a `cypress.config.ts` file:
+
+#### Simple Configuration (Backward Compatible)
+```typescript
+import { defineConfig } from 'cypress';
+import { defaultCypressConfig, setupPlugins } from '@trackunit/iris-app-e2e';
+import { install } from '@neuralegion/cypress-har-generator';
+import { format, resolveConfig } from 'prettier';
+
+export default defineConfig({
+  e2e: {
+    ...defaultCypressConfig(__dirname),
+    setupNodeEvents(on, config) {
+      setupPlugins(
+        on,
+        config,
+        { format, resolveConfig }, // Prettier formatter
+        install                     // HAR generator installer
+      );
+    }
+  }
+});
+```
+
+#### Advanced Configuration (New API)
+```typescript
+import { defineConfig } from 'cypress';
+import { defaultCypressConfig, setupPlugins } from '@trackunit/iris-app-e2e';
+import { install } from '@neuralegion/cypress-har-generator';
+import { format, resolveConfig } from 'prettier';
+
+export default defineConfig({
+  e2e: {
+    ...defaultCypressConfig({
+      // Optional: Custom configuration
+      behaviorConfig: {
+        defaultCommandTimeout: 30000,
+        retries: { runMode: 2, openMode: 0 }
+      }
+    }),
+    setupNodeEvents(on, config) {
+      setupPlugins(
+        on,
+        config,
+        { format, resolveConfig }, // Prettier formatter
+        install                     // HAR generator installer
+      );
+    }
+  }
+});
+```
+
+### Using Commands in Tests
+
+```typescript
+describe('Iris App E2E Tests', () => {
+  it('should login and navigate to app', () => {
+    // Login with default user
+    cy.login();
+
+    // Or login with specific fixture
+    cy.login('managere2e-admin');
+
+    // Find elements by test ID
+    cy.getByTestId('navigation-menu').should('be.visible');
+
+    // Switch to local development mode
+    cy.switchToLocalDevMode();
+
+    // Enter an Iris app iframe
+    cy.enterIrisApp().then(app => {
+      app().getByTestId('app-content').should('exist');
+    });
+  });
+
+  it('should check feature flags', () => {
+    cy.getValidateFeatureFlags();
+    cy.configCat('my-feature-flag').then(isEnabled => {
+      if (isEnabled) {
+        cy.getByTestId('feature-content').should('be.visible');
+      }
+    });
+  });
+});
+```
+
+## Configuration Options
+
+### E2EConfigOptions
+
+```typescript
+interface E2EConfigOptions {
+  nxRoot?: string;                   // NX workspace root (auto-detected)
+  outputDirOverride?: string;        // Custom output directory
+  projectConfig?: E2EProjectConfig;  // Project-specific settings
+  behaviorConfig?: E2EBehaviorConfig; // Timeout and retry settings
+  pluginConfig?: E2EPluginConfig;    // Output path configuration
+}
+```
+
+### Environment Variables
+
+- **`NX_FEATURE_BRANCH_BASE_URL`** - Override base URL for testing
+- **`NX_E2E_OUTPUT_DIR`** - Custom E2E output directory
+
+## Authentication
+
+The library uses Trackunit's standard authentication flow:
+
+1. Fetches environment configuration from `/env` endpoint
+2. Authenticates with Okta using session tokens
+3. Redirects to Manager
+
+### User Fixtures
+
+Supported user fixture files:
+
+- `auth` (default)
+
+Example fixture file (`cypress/fixtures/auth.json`):
+
+```json
+{
+  "username": "test@example.com",
+  "password": "your-password"
+}
+```
+
+## Host Configuration
+
+Tests run against the same Trackunit infrastructure:
+
+- Dynamic environment discovery via `/env` endpoint
+- Consistent authentication endpoints
+- Same Manager routes and functionality
+
+Set the base URL via Cypress configuration or environment variables to target different environments (staging, production, etc.).
+
+## HAR Recording
+
+Failed tests automatically generate HAR files for debugging:
+
+- Stored in configured output directory
+- Named with test name and attempt number
+- Includes full network traffic for analysis
+
+## TypeScript Support
+
+The package includes comprehensive TypeScript definitions for all Cypress commands and configuration options. Your IDE will provide full autocomplete and type checking.
+
+## Development
+
+At this point this library is only developed by Trackunit Employees.
+For development related information see the [development readme](https://github.com/Trackunit/manager/blob/master/libs/react/components/DEVELOPMENT.md).
+
+## Trackunit
+
+This package was developed by Trackunit ApS.
+Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.
+
+![The Trackunit logo](https://trackunit.com/wp-content/uploads/2022/03/top-logo.svg)

package/index.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/index.cjs.js

@@ -0,0 +1,395 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+var nodeXlsx = require('node-xlsx');
+
+function _interopNamespaceDefault(e) {
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+
+/**
+ * Sets up default Cypress commands for E2E testing.
+ * Adds custom commands like getByTestId, login, enterIrisApp, etc.
+ */
+function setupDefaultCommands() {
+    Cypress.Commands.add("getByTestId", {
+        prevSubject: ["optional"],
+    }, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (subject, testId, options = {}) => {
+        const selector = `[data-testid="${testId}"]`;
+        const timeout = options.timeout ?? 15000;
+        if (subject) {
+            if (Cypress.dom.isElement(subject) || Cypress.dom.isJquery(subject)) {
+                return cy.wrap(subject, { timeout }).find(selector, { timeout });
+            }
+            else if (Cypress.dom.isWindow(subject)) {
+                return cy.get(selector, { timeout });
+            }
+            else if (Array.isArray(subject)) {
+                const element = subject.map(el => cy.wrap(el, { timeout }).find(selector, { timeout }));
+                if (element[0]) {
+                    return element[0];
+                }
+                return cy.wrap(null);
+            }
+            return cy.get(selector, { timeout });
+        }
+        else {
+            return cy.get(selector, { timeout });
+        }
+    });
+    Cypress.Commands.add("login", fixture => {
+        const envUrl = `${Cypress.config().baseUrl}/env`;
+        cy.log(`Getting env from: ${envUrl}`);
+        cy.request({
+            method: "GET",
+            url: envUrl,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        }).then(envResponse => {
+            const env = envResponse.body;
+            const domain = env.auth?.url;
+            if (!domain) {
+                throw new Error(`No domain found from servers /env found env: ${JSON.stringify(env)}`);
+            }
+            cy.log(`Using: ${domain}`);
+            cy.clearCookies();
+            cy.fixture(fixture ?? "auth").then(({ username, password }) => {
+                const options = {
+                    warnBeforePasswordExpired: true,
+                    multiOptionalFactorEnroll: false,
+                };
+                cy.request({
+                    method: "POST",
+                    url: `${domain}/api/v1/authn`,
+                    headers: {
+                        "Content-Type": "application/json",
+                    },
+                    body: {
+                        username,
+                        password,
+                        options,
+                    },
+                })
+                    .then(response => {
+                    if (response.isOkStatusCode) {
+                        const sessionToken = response.body.sessionToken;
+                        return cy.visit(`/auth/manager-classic#session_token=${sessionToken}&fleetHome=true`);
+                    }
+                    else {
+                        throw new Error(`Could not get a session token for user: ${username}, ${JSON.stringify(response)}`);
+                    }
+                })
+                    .url()
+                    .should("contain", `${Cypress.config().baseUrl}`)
+                    .should("contain", `/map`)
+                    .getByTestId("map-page", { timeout: 30000 })
+                    .should("be.visible");
+            });
+        });
+    });
+    Cypress.Commands.add("switchToLocalDevMode", () => {
+        cy.getByTestId("developerPortalNav").click();
+        cy.url({ timeout: 15000, log: true }).should("contain", "/iris-sdk-portal");
+        //eslint-disable-next-line @typescript-eslint/no-explicit-any
+        cy.getByTestId("localDevModeSwitch-input").then(($ele) => {
+            if ($ele && !$ele.is(":checked")) {
+                cy.getByTestId("localDevModeSwitch-thumb").click();
+            }
+        });
+    });
+    Cypress.Commands.add("enterIrisApp", options => {
+        return cy
+            .get(`iframe[data-testid="${options?.testId ?? "app-iframe"}"]`, { timeout: 30000 })
+            .first()
+            .its("0.contentDocument.body", { timeout: 30000, log: true })
+            .should("not.be.empty")
+            .then($body => {
+            return () => cy.wrap($body);
+        });
+    });
+    Cypress.Commands.add("enterStorybookPreview", options => {
+        return cy
+            .get(`iframe[id="${options?.testId ?? "storybook-preview-iframe"}"]`, { timeout: 30000 })
+            .first()
+            .its("0.contentDocument.body", { timeout: 30000, log: true })
+            .should("not.be.empty")
+            .then($body => {
+            return () => cy.wrap($body);
+        });
+    });
+    Cypress.Commands.add("getValidateFeatureFlags", () => {
+        cy.intercept({ url: "**/ValidateFeatureFlags" }).as("ValidateFeatureFlags");
+        cy.intercept({ url: "**/UserPermissions" }).as("UserPermissions");
+        cy.intercept({ url: "**/ActiveSubscription" }).as("ActiveSubscription");
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let ccData = null;
+    Cypress.Commands.add("configCat", value => {
+        if (!ccData) {
+            cy.wait("@ValidateFeatureFlags").then(intercept => {
+                ccData = intercept.response?.body?.data?.featureFlags?.find((ff) => ff.key === value);
+                return ccData?.state;
+            });
+        }
+        else {
+            return ccData?.state;
+        }
+    });
+}
+
+/* eslint-disable no-console */
+/**
+ * Writes a file with Prettier formatting applied.
+ * Automatically detects parser based on file extension.
+ */
+const writeFileWithPrettier = async (nxRoot, filePath, content, writeOptions = { encoding: "utf-8" }, writer) => {
+    const prettierConfigPath = path__namespace.join(nxRoot, ".prettierrc");
+    const options = await writer
+        .resolveConfig(prettierConfigPath)
+        .catch(error => console.log("Prettier config error: ", error));
+    if (!options) {
+        throw new Error("Could not find prettier config");
+    }
+    if (filePath.endsWith("json")) {
+        options.parser = "json";
+    }
+    else {
+        options.parser = "typescript";
+    }
+    try {
+        const prettySrc = await writer.format(content, options);
+        fs.writeFileSync(filePath, prettySrc, writeOptions);
+    }
+    catch (error) {
+        console.error("Error in prettier.format:", error);
+    }
+};
+
+const isNetworkCall = (log) => {
+    return log.type === "cy:fetch" || log.type === "cy:request" || log.type === "cy:response" || log.type === "cy:xrh";
+};
+/**
+ * Creates log files for Cypress test runs.
+ * Generates separate files for all logs, errors, and network errors.
+ */
+function createLogFile(nxRoot, logsPath, fileNameWithoutExtension, logs, logWriter) {
+    if (!fs.existsSync(logsPath)) {
+        fs.mkdirSync(logsPath, { recursive: true });
+    }
+    const logFilePath = path.join(logsPath, fileNameWithoutExtension);
+    writeFileWithPrettier(nxRoot, logFilePath + "-all.json", JSON.stringify(logs), { flag: "a" }, logWriter);
+    const errorCmds = logs.filter(log => log.severity === "error" &&
+        // This seems to be when apollo has cancelled requests it marks it as failed to fetch only on cypress ?!??
+        // might be fixed by https://github.com/Trackunit/manager/pull/12917
+        !log.message.includes("TypeError: Failed to fetch"));
+    if (errorCmds.length > 0) {
+        writeFileWithPrettier(nxRoot, logFilePath + "-errors.json", JSON.stringify(errorCmds), {
+            flag: "a",
+        }, logWriter);
+    }
+    const networkErrorsCmds = logs.filter(log => isNetworkCall(log) &&
+        !log.message.includes("Status: 200") &&
+        log.severity !== "success" &&
+        !log.message.includes("sentry.io/api/") &&
+        // This seems to be when apollo has cancelled requests it marks it as failed to fetch only on cypress ?!??
+        !log.message.includes("TypeError: Failed to fetch"));
+    if (networkErrorsCmds.length > 0) {
+        writeFileWithPrettier(nxRoot, logFilePath + "-network-errors.json", JSON.stringify(networkErrorsCmds), {
+            flag: "a",
+        }, logWriter);
+    }
+}
+
+/**
+ * Utility function to find NX workspace root by looking for nx.json or workspace.json.
+ * This is more reliable than hardcoded relative paths and works from any directory.
+ *
+ * @param startDir Starting directory for the search (defaults to current working directory)
+ * @returns {string} Absolute path to the workspace root
+ * @throws Error if workspace root cannot be found
+ */
+function findWorkspaceRoot(startDir = process.cwd()) {
+    let currentDir = startDir;
+    while (currentDir !== path.dirname(currentDir)) {
+        if (fs.existsSync(path.join(currentDir, "nx.json")) || fs.existsSync(path.join(currentDir, "workspace.json"))) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    throw new Error("Could not find NX workspace root (nx.json or workspace.json not found)");
+}
+/**
+ * Creates default Cypress configuration for E2E testing.
+ * Supports both legacy string parameter (dirname) and new options object for backward compatibility.
+ */
+const defaultCypressConfig = optionsOrDirname => {
+    // Support both old API (string/undefined) and new API (object) for backward compatibility
+    const options = typeof optionsOrDirname === "object" ? optionsOrDirname : {};
+    const { nxRoot: providedNxRoot, outputDirOverride, projectConfig = {}, behaviorConfig = {}, pluginConfig = {}, } = options;
+    // Use NX workspace detection for reliable root finding
+    const nxRoot = providedNxRoot ?? findWorkspaceRoot();
+    // For output path calculation, determine the relative path from caller to workspace root
+    const callerDirname = typeof optionsOrDirname === "string" ? optionsOrDirname : process.cwd();
+    const relativePath = path.relative(nxRoot, callerDirname);
+    const dotsToNxRoot = relativePath
+        .split(path.sep)
+        .map(_ => "..")
+        .join("/");
+    const envOutputDirOverride = process.env.NX_E2E_OUTPUT_DIR || outputDirOverride;
+    // Function to build output paths that respects the override
+    const buildOutputPath = (subPath) => {
+        if (envOutputDirOverride) {
+            return path.join(dotsToNxRoot, envOutputDirOverride, subPath);
+        }
+        return `${dotsToNxRoot}/dist/cypress/${relativePath}/${subPath}`;
+    };
+    return {
+        projectId: projectConfig.projectId ?? process.env.CYPRESS_PROJECT_ID,
+        defaultCommandTimeout: behaviorConfig.defaultCommandTimeout ?? 20000,
+        execTimeout: behaviorConfig.execTimeout ?? 300000,
+        taskTimeout: behaviorConfig.taskTimeout ?? 35000,
+        pageLoadTimeout: behaviorConfig.pageLoadTimeout ?? 35000,
+        // setting to undefined makes no effect on the baseUrl so child projects can override it
+        baseUrl: process.env.NX_FEATURE_BRANCH_BASE_URL ?? undefined,
+        requestTimeout: behaviorConfig.requestTimeout ?? 25000,
+        responseTimeout: behaviorConfig.responseTimeout ?? 150000,
+        retries: behaviorConfig.retries ?? {
+            runMode: 3,
+            openMode: 0,
+        },
+        fixturesFolder: projectConfig.fixturesFolder ?? "./src/fixtures",
+        downloadsFolder: pluginConfig.outputPath ?? buildOutputPath("downloads"),
+        logsFolder: pluginConfig.logsFolder ?? buildOutputPath("logs"),
+        chromeWebSecurity: false,
+        reporter: "junit",
+        reporterOptions: {
+            mochaFile: buildOutputPath("results-[hash].xml"),
+        },
+        specPattern: projectConfig.specPattern ?? "src/e2e/**/*.e2e.{js,jsx,ts,tsx}",
+        supportFile: projectConfig.supportFile ?? "src/support/e2e.ts",
+        nxRoot,
+        fileServerFolder: ".",
+        video: true,
+        videosFolder: pluginConfig.videosFolder ?? buildOutputPath("videos"),
+        screenshotsFolder: pluginConfig.screenshotsFolder ?? buildOutputPath("screenshots"),
+        env: {
+            hars_folders: pluginConfig.harFolder ?? buildOutputPath("hars"),
+            CYPRESS_RUN_UNIQUE_ID: crypto.randomUUID(),
+        },
+    };
+};
+/**
+ * Sets up Cypress plugins for logging, tasks, and HAR generation.
+ * Configures terminal reporting, XLSX parsing, and HTTP archive recording.
+ */
+const setupPlugins = (on, config, logWriter, installHarGenerator) => {
+    /* ---- BEGIN: Logging setup ---- */
+    // Read options https://github.com/archfz/cypress-terminal-report
+    const options = {
+        printLogsToFile: "always", // Ensures logs are always printed to a file
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        collectTestLogs: (context, logs) => {
+            const testName = context.state.toUpperCase() +
+                "_" +
+                (config.currentRetry ? `( attempt ${config.currentRetry})_` : "") +
+                context.test;
+            createLogFile(config.nxRoot, config.logsFolder, testName, logs, logWriter);
+        },
+    };
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+    require("cypress-terminal-report/src/installLogsPrinter")(on, options);
+    /* ---- END: Logging setup ---- */
+    /* ---- BEGIN: Task setup ---- */
+    on("task", {
+        parseXlsx(filePath) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const jsonData = nodeXlsx.parse(fs.readFileSync(filePath));
+                    resolve(jsonData);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        },
+        fileExists(filename) {
+            return fs.existsSync(filename);
+        },
+    });
+    /* ---- END: Task setup ---- */
+    /* ---- BEGIN: HAR setup ---- */
+    // Installing the HAR geneartor should happen last according to the documentation
+    // https://github.com/NeuraLegion/cypress-har-generator?tab=readme-ov-file#setting-up-the-plugin
+    installHarGenerator(on);
+    /* ---- END: HAR setup ---- */
+};
+
+/* eslint-disable local-rules/no-typescript-assertion, @typescript-eslint/no-explicit-any */
+/**
+ * Sets up HAR (HTTP Archive) recording for E2E tests.
+ * Records network activity and saves HAR files for failed tests.
+ */
+function setupHarRecording() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require("@neuralegion/cypress-har-generator/commands");
+    beforeEach(() => {
+        const harDir = Cypress.env("hars_folders");
+        cy.recordHar({ rootDir: harDir });
+    });
+    afterEach(function () {
+        if (this.currentTest.state === "failed") {
+            const harDir = Cypress.env("hars_folders");
+            const testName = "FAILED_" + Cypress.currentTest.title + (Cypress.currentRetry ? `_( attempt ${Cypress.currentRetry})_` : "");
+            cy.saveHar({ outDir: harDir, fileName: testName });
+        }
+    });
+}
+
+/**
+ * Sets up the E2E testing environment with HAR recording and terminal logging.
+ */
+function setupE2E() {
+    setupHarRecording();
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+    require("cypress-terminal-report/src/installLogsCollector")({
+        xhr: {
+            printHeaderData: true,
+            printRequestData: true,
+        },
+    });
+    Cypress.on("uncaught:exception", (err) => {
+        // eslint-disable-next-line no-console
+        console.log("Caught Error: ", err);
+        // returning false here prevents Cypress from
+        // failing the test
+        return false;
+    });
+}
+
+exports.createLogFile = createLogFile;
+exports.defaultCypressConfig = defaultCypressConfig;
+exports.setupDefaultCommands = setupDefaultCommands;
+exports.setupE2E = setupE2E;
+exports.setupHarRecording = setupHarRecording;
+exports.setupPlugins = setupPlugins;
+exports.writeFileWithPrettier = writeFileWithPrettier;

package/index.esm.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/index.esm.js

@@ -0,0 +1,369 @@
+import fs, { writeFileSync, existsSync, readFileSync } from 'fs';
+import * as path from 'path';
+import path__default from 'path';
+import crypto from 'crypto';
+import { parse } from 'node-xlsx';
+
+/**
+ * Sets up default Cypress commands for E2E testing.
+ * Adds custom commands like getByTestId, login, enterIrisApp, etc.
+ */
+function setupDefaultCommands() {
+    Cypress.Commands.add("getByTestId", {
+        prevSubject: ["optional"],
+    }, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (subject, testId, options = {}) => {
+        const selector = `[data-testid="${testId}"]`;
+        const timeout = options.timeout ?? 15000;
+        if (subject) {
+            if (Cypress.dom.isElement(subject) || Cypress.dom.isJquery(subject)) {
+                return cy.wrap(subject, { timeout }).find(selector, { timeout });
+            }
+            else if (Cypress.dom.isWindow(subject)) {
+                return cy.get(selector, { timeout });
+            }
+            else if (Array.isArray(subject)) {
+                const element = subject.map(el => cy.wrap(el, { timeout }).find(selector, { timeout }));
+                if (element[0]) {
+                    return element[0];
+                }
+                return cy.wrap(null);
+            }
+            return cy.get(selector, { timeout });
+        }
+        else {
+            return cy.get(selector, { timeout });
+        }
+    });
+    Cypress.Commands.add("login", fixture => {
+        const envUrl = `${Cypress.config().baseUrl}/env`;
+        cy.log(`Getting env from: ${envUrl}`);
+        cy.request({
+            method: "GET",
+            url: envUrl,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        }).then(envResponse => {
+            const env = envResponse.body;
+            const domain = env.auth?.url;
+            if (!domain) {
+                throw new Error(`No domain found from servers /env found env: ${JSON.stringify(env)}`);
+            }
+            cy.log(`Using: ${domain}`);
+            cy.clearCookies();
+            cy.fixture(fixture ?? "auth").then(({ username, password }) => {
+                const options = {
+                    warnBeforePasswordExpired: true,
+                    multiOptionalFactorEnroll: false,
+                };
+                cy.request({
+                    method: "POST",
+                    url: `${domain}/api/v1/authn`,
+                    headers: {
+                        "Content-Type": "application/json",
+                    },
+                    body: {
+                        username,
+                        password,
+                        options,
+                    },
+                })
+                    .then(response => {
+                    if (response.isOkStatusCode) {
+                        const sessionToken = response.body.sessionToken;
+                        return cy.visit(`/auth/manager-classic#session_token=${sessionToken}&fleetHome=true`);
+                    }
+                    else {
+                        throw new Error(`Could not get a session token for user: ${username}, ${JSON.stringify(response)}`);
+                    }
+                })
+                    .url()
+                    .should("contain", `${Cypress.config().baseUrl}`)
+                    .should("contain", `/map`)
+                    .getByTestId("map-page", { timeout: 30000 })
+                    .should("be.visible");
+            });
+        });
+    });
+    Cypress.Commands.add("switchToLocalDevMode", () => {
+        cy.getByTestId("developerPortalNav").click();
+        cy.url({ timeout: 15000, log: true }).should("contain", "/iris-sdk-portal");
+        //eslint-disable-next-line @typescript-eslint/no-explicit-any
+        cy.getByTestId("localDevModeSwitch-input").then(($ele) => {
+            if ($ele && !$ele.is(":checked")) {
+                cy.getByTestId("localDevModeSwitch-thumb").click();
+            }
+        });
+    });
+    Cypress.Commands.add("enterIrisApp", options => {
+        return cy
+            .get(`iframe[data-testid="${options?.testId ?? "app-iframe"}"]`, { timeout: 30000 })
+            .first()
+            .its("0.contentDocument.body", { timeout: 30000, log: true })
+            .should("not.be.empty")
+            .then($body => {
+            return () => cy.wrap($body);
+        });
+    });
+    Cypress.Commands.add("enterStorybookPreview", options => {
+        return cy
+            .get(`iframe[id="${options?.testId ?? "storybook-preview-iframe"}"]`, { timeout: 30000 })
+            .first()
+            .its("0.contentDocument.body", { timeout: 30000, log: true })
+            .should("not.be.empty")
+            .then($body => {
+            return () => cy.wrap($body);
+        });
+    });
+    Cypress.Commands.add("getValidateFeatureFlags", () => {
+        cy.intercept({ url: "**/ValidateFeatureFlags" }).as("ValidateFeatureFlags");
+        cy.intercept({ url: "**/UserPermissions" }).as("UserPermissions");
+        cy.intercept({ url: "**/ActiveSubscription" }).as("ActiveSubscription");
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let ccData = null;
+    Cypress.Commands.add("configCat", value => {
+        if (!ccData) {
+            cy.wait("@ValidateFeatureFlags").then(intercept => {
+                ccData = intercept.response?.body?.data?.featureFlags?.find((ff) => ff.key === value);
+                return ccData?.state;
+            });
+        }
+        else {
+            return ccData?.state;
+        }
+    });
+}
+
+/* eslint-disable no-console */
+/**
+ * Writes a file with Prettier formatting applied.
+ * Automatically detects parser based on file extension.
+ */
+const writeFileWithPrettier = async (nxRoot, filePath, content, writeOptions = { encoding: "utf-8" }, writer) => {
+    const prettierConfigPath = path.join(nxRoot, ".prettierrc");
+    const options = await writer
+        .resolveConfig(prettierConfigPath)
+        .catch(error => console.log("Prettier config error: ", error));
+    if (!options) {
+        throw new Error("Could not find prettier config");
+    }
+    if (filePath.endsWith("json")) {
+        options.parser = "json";
+    }
+    else {
+        options.parser = "typescript";
+    }
+    try {
+        const prettySrc = await writer.format(content, options);
+        writeFileSync(filePath, prettySrc, writeOptions);
+    }
+    catch (error) {
+        console.error("Error in prettier.format:", error);
+    }
+};
+
+const isNetworkCall = (log) => {
+    return log.type === "cy:fetch" || log.type === "cy:request" || log.type === "cy:response" || log.type === "cy:xrh";
+};
+/**
+ * Creates log files for Cypress test runs.
+ * Generates separate files for all logs, errors, and network errors.
+ */
+function createLogFile(nxRoot, logsPath, fileNameWithoutExtension, logs, logWriter) {
+    if (!existsSync(logsPath)) {
+        fs.mkdirSync(logsPath, { recursive: true });
+    }
+    const logFilePath = path__default.join(logsPath, fileNameWithoutExtension);
+    writeFileWithPrettier(nxRoot, logFilePath + "-all.json", JSON.stringify(logs), { flag: "a" }, logWriter);
+    const errorCmds = logs.filter(log => log.severity === "error" &&
+        // This seems to be when apollo has cancelled requests it marks it as failed to fetch only on cypress ?!??
+        // might be fixed by https://github.com/Trackunit/manager/pull/12917
+        !log.message.includes("TypeError: Failed to fetch"));
+    if (errorCmds.length > 0) {
+        writeFileWithPrettier(nxRoot, logFilePath + "-errors.json", JSON.stringify(errorCmds), {
+            flag: "a",
+        }, logWriter);
+    }
+    const networkErrorsCmds = logs.filter(log => isNetworkCall(log) &&
+        !log.message.includes("Status: 200") &&
+        log.severity !== "success" &&
+        !log.message.includes("sentry.io/api/") &&
+        // This seems to be when apollo has cancelled requests it marks it as failed to fetch only on cypress ?!??
+        !log.message.includes("TypeError: Failed to fetch"));
+    if (networkErrorsCmds.length > 0) {
+        writeFileWithPrettier(nxRoot, logFilePath + "-network-errors.json", JSON.stringify(networkErrorsCmds), {
+            flag: "a",
+        }, logWriter);
+    }
+}
+
+/**
+ * Utility function to find NX workspace root by looking for nx.json or workspace.json.
+ * This is more reliable than hardcoded relative paths and works from any directory.
+ *
+ * @param startDir Starting directory for the search (defaults to current working directory)
+ * @returns {string} Absolute path to the workspace root
+ * @throws Error if workspace root cannot be found
+ */
+function findWorkspaceRoot(startDir = process.cwd()) {
+    let currentDir = startDir;
+    while (currentDir !== path__default.dirname(currentDir)) {
+        if (existsSync(path__default.join(currentDir, "nx.json")) || existsSync(path__default.join(currentDir, "workspace.json"))) {
+            return currentDir;
+        }
+        currentDir = path__default.dirname(currentDir);
+    }
+    throw new Error("Could not find NX workspace root (nx.json or workspace.json not found)");
+}
+/**
+ * Creates default Cypress configuration for E2E testing.
+ * Supports both legacy string parameter (dirname) and new options object for backward compatibility.
+ */
+const defaultCypressConfig = optionsOrDirname => {
+    // Support both old API (string/undefined) and new API (object) for backward compatibility
+    const options = typeof optionsOrDirname === "object" ? optionsOrDirname : {};
+    const { nxRoot: providedNxRoot, outputDirOverride, projectConfig = {}, behaviorConfig = {}, pluginConfig = {}, } = options;
+    // Use NX workspace detection for reliable root finding
+    const nxRoot = providedNxRoot ?? findWorkspaceRoot();
+    // For output path calculation, determine the relative path from caller to workspace root
+    const callerDirname = typeof optionsOrDirname === "string" ? optionsOrDirname : process.cwd();
+    const relativePath = path__default.relative(nxRoot, callerDirname);
+    const dotsToNxRoot = relativePath
+        .split(path__default.sep)
+        .map(_ => "..")
+        .join("/");
+    const envOutputDirOverride = process.env.NX_E2E_OUTPUT_DIR || outputDirOverride;
+    // Function to build output paths that respects the override
+    const buildOutputPath = (subPath) => {
+        if (envOutputDirOverride) {
+            return path__default.join(dotsToNxRoot, envOutputDirOverride, subPath);
+        }
+        return `${dotsToNxRoot}/dist/cypress/${relativePath}/${subPath}`;
+    };
+    return {
+        projectId: projectConfig.projectId ?? process.env.CYPRESS_PROJECT_ID,
+        defaultCommandTimeout: behaviorConfig.defaultCommandTimeout ?? 20000,
+        execTimeout: behaviorConfig.execTimeout ?? 300000,
+        taskTimeout: behaviorConfig.taskTimeout ?? 35000,
+        pageLoadTimeout: behaviorConfig.pageLoadTimeout ?? 35000,
+        // setting to undefined makes no effect on the baseUrl so child projects can override it
+        baseUrl: process.env.NX_FEATURE_BRANCH_BASE_URL ?? undefined,
+        requestTimeout: behaviorConfig.requestTimeout ?? 25000,
+        responseTimeout: behaviorConfig.responseTimeout ?? 150000,
+        retries: behaviorConfig.retries ?? {
+            runMode: 3,
+            openMode: 0,
+        },
+        fixturesFolder: projectConfig.fixturesFolder ?? "./src/fixtures",
+        downloadsFolder: pluginConfig.outputPath ?? buildOutputPath("downloads"),
+        logsFolder: pluginConfig.logsFolder ?? buildOutputPath("logs"),
+        chromeWebSecurity: false,
+        reporter: "junit",
+        reporterOptions: {
+            mochaFile: buildOutputPath("results-[hash].xml"),
+        },
+        specPattern: projectConfig.specPattern ?? "src/e2e/**/*.e2e.{js,jsx,ts,tsx}",
+        supportFile: projectConfig.supportFile ?? "src/support/e2e.ts",
+        nxRoot,
+        fileServerFolder: ".",
+        video: true,
+        videosFolder: pluginConfig.videosFolder ?? buildOutputPath("videos"),
+        screenshotsFolder: pluginConfig.screenshotsFolder ?? buildOutputPath("screenshots"),
+        env: {
+            hars_folders: pluginConfig.harFolder ?? buildOutputPath("hars"),
+            CYPRESS_RUN_UNIQUE_ID: crypto.randomUUID(),
+        },
+    };
+};
+/**
+ * Sets up Cypress plugins for logging, tasks, and HAR generation.
+ * Configures terminal reporting, XLSX parsing, and HTTP archive recording.
+ */
+const setupPlugins = (on, config, logWriter, installHarGenerator) => {
+    /* ---- BEGIN: Logging setup ---- */
+    // Read options https://github.com/archfz/cypress-terminal-report
+    const options = {
+        printLogsToFile: "always", // Ensures logs are always printed to a file
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        collectTestLogs: (context, logs) => {
+            const testName = context.state.toUpperCase() +
+                "_" +
+                (config.currentRetry ? `( attempt ${config.currentRetry})_` : "") +
+                context.test;
+            createLogFile(config.nxRoot, config.logsFolder, testName, logs, logWriter);
+        },
+    };
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+    require("cypress-terminal-report/src/installLogsPrinter")(on, options);
+    /* ---- END: Logging setup ---- */
+    /* ---- BEGIN: Task setup ---- */
+    on("task", {
+        parseXlsx(filePath) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const jsonData = parse(readFileSync(filePath));
+                    resolve(jsonData);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        },
+        fileExists(filename) {
+            return existsSync(filename);
+        },
+    });
+    /* ---- END: Task setup ---- */
+    /* ---- BEGIN: HAR setup ---- */
+    // Installing the HAR geneartor should happen last according to the documentation
+    // https://github.com/NeuraLegion/cypress-har-generator?tab=readme-ov-file#setting-up-the-plugin
+    installHarGenerator(on);
+    /* ---- END: HAR setup ---- */
+};
+
+/* eslint-disable local-rules/no-typescript-assertion, @typescript-eslint/no-explicit-any */
+/**
+ * Sets up HAR (HTTP Archive) recording for E2E tests.
+ * Records network activity and saves HAR files for failed tests.
+ */
+function setupHarRecording() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require("@neuralegion/cypress-har-generator/commands");
+    beforeEach(() => {
+        const harDir = Cypress.env("hars_folders");
+        cy.recordHar({ rootDir: harDir });
+    });
+    afterEach(function () {
+        if (this.currentTest.state === "failed") {
+            const harDir = Cypress.env("hars_folders");
+            const testName = "FAILED_" + Cypress.currentTest.title + (Cypress.currentRetry ? `_( attempt ${Cypress.currentRetry})_` : "");
+            cy.saveHar({ outDir: harDir, fileName: testName });
+        }
+    });
+}
+
+/**
+ * Sets up the E2E testing environment with HAR recording and terminal logging.
+ */
+function setupE2E() {
+    setupHarRecording();
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+    require("cypress-terminal-report/src/installLogsCollector")({
+        xhr: {
+            printHeaderData: true,
+            printRequestData: true,
+        },
+    });
+    Cypress.on("uncaught:exception", (err) => {
+        // eslint-disable-next-line no-console
+        console.log("Caught Error: ", err);
+        // returning false here prevents Cypress from
+        // failing the test
+        return false;
+    });
+}
+
+export { createLogFile, defaultCypressConfig, setupDefaultCommands, setupE2E, setupHarRecording, setupPlugins, writeFileWithPrettier };

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@trackunit/iris-app-e2e",
+  "version": "0.0.2-alpha-49e9177e1b3.0",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=22.x"
+  },
+  "dependencies": {
+    "@neuralegion/cypress-har-generator": "^5.17.0",
+    "cypress-terminal-report": "7.0.3",
+    "node-xlsx": "^0.23.0",
+    "prettier": "^3.4.2",
+    "@trackunit/react-test-setup": "1.0.33-alpha-49e9177e1b3.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.esm.d.ts"
+}

package/src/commands/defaultCommands.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sets up default Cypress commands for E2E testing.
+ * Adds custom commands like getByTestId, login, enterIrisApp, etc.
+ */
+export declare function setupDefaultCommands(): void;

package/src/commands/index.d.ts

@@ -0,0 +1 @@
+export * from "./defaultCommands";

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./commands";
+export * from "./plugins";
+export * from "./setup";

package/src/plugins/createLogFile.d.ts

@@ -0,0 +1,12 @@
+import { Formatter } from "./writeFileWithPrettier";
+type Log = {
+    type: string;
+    message: string;
+    severity: string;
+};
+/**
+ * Creates log files for Cypress test runs.
+ * Generates separate files for all logs, errors, and network errors.
+ */
+export declare function createLogFile(nxRoot: string, logsPath: string, fileNameWithoutExtension: string, logs: Array<Log>, logWriter: Formatter): void;
+export {};

package/src/plugins/defaultPlugins.d.ts

@@ -0,0 +1,48 @@
+import { Formatter } from "./writeFileWithPrettier";
+export interface CypressPluginConfig extends Cypress.PluginConfigOptions {
+    currentRetry: number;
+    nxRoot: string;
+    logsFolder: string;
+}
+export interface E2EPluginConfig {
+    outputPath?: string;
+    logsFolder?: string;
+    videosFolder?: string;
+    screenshotsFolder?: string;
+    harFolder?: string;
+}
+export interface E2EProjectConfig {
+    projectId?: string;
+    specPattern?: string;
+    fixturesFolder?: string;
+    supportFile?: string;
+}
+export interface E2EBehaviorConfig {
+    defaultCommandTimeout?: number;
+    retries?: {
+        runMode: number;
+        openMode: number;
+    };
+    requestTimeout?: number;
+    responseTimeout?: number;
+    execTimeout?: number;
+    taskTimeout?: number;
+    pageLoadTimeout?: number;
+}
+export interface E2EConfigOptions {
+    nxRoot?: string;
+    outputDirOverride?: string;
+    projectConfig?: E2EProjectConfig;
+    behaviorConfig?: E2EBehaviorConfig;
+    pluginConfig?: E2EPluginConfig;
+}
+/**
+ * Creates default Cypress configuration for E2E testing.
+ * Supports both legacy string parameter (dirname) and new options object for backward compatibility.
+ */
+export declare const defaultCypressConfig: (optionsOrDirname?: E2EConfigOptions | string) => Partial<CypressPluginConfig>;
+/**
+ * Sets up Cypress plugins for logging, tasks, and HAR generation.
+ * Configures terminal reporting, XLSX parsing, and HTTP archive recording.
+ */
+export declare const setupPlugins: (on: Cypress.PluginEvents, config: CypressPluginConfig, logWriter: Formatter, installHarGenerator: (on: Cypress.PluginEvents) => void) => void;

package/src/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./createLogFile";
+export * from "./defaultPlugins";
+export * from "./writeFileWithPrettier";

package/src/plugins/writeFileWithPrettier.d.ts

@@ -0,0 +1,11 @@
+import { WriteFileOptions } from "fs";
+import { format, resolveConfig } from "prettier";
+export type Formatter = {
+    resolveConfig: typeof resolveConfig;
+    format: typeof format;
+};
+/**
+ * Writes a file with Prettier formatting applied.
+ * Automatically detects parser based on file extension.
+ */
+export declare const writeFileWithPrettier: (nxRoot: string, filePath: string, content: string, writeOptions: WriteFileOptions | undefined, writer: Formatter) => Promise<void>;

package/src/setup/defaultE2ESetup.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sets up the E2E testing environment with HAR recording and terminal logging.
+ */
+export declare function setupE2E(): void;

package/src/setup/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./defaultE2ESetup";
+export * from "./setupHarRecording";

package/src/setup/setupHarRecording.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sets up HAR (HTTP Archive) recording for E2E tests.
+ * Records network activity and saves HAR files for failed tests.
+ */
+export declare function setupHarRecording(): void;