@trackunit/iris-app-e2e

@trackunit/iris-app-e2e

[!WARNING] Deprecated — Cypress E2E is being replaced by Playwright.

@trackunit/iris-app-e2e (Cypress) is deprecated in favour of @trackunit/iris-app-playwright (Playwright). All Trackunit-internal suites have been migrated. The package remains fully functional during a grace period so external IrisX-app developers can migrate on their own schedule — nothing has been removed.

• New projects: use @trackunit/iris-app-playwright and the @trackunit/iris-app-playwright:playwright-configuration generator.
• Existing Cypress suites: see the migration guide.
• Removal: the shared Cypress plumbing will only be removed in a separate, future issue after the grace period ends. Watch this README and the external developer channels for the grace-period end date.

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.

To browse all available components visit the Design System.

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Installation

npm install @trackunit/iris-app-e2e --save-dev

Peer Dependencies

This package requires the following peer dependencies:

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:

// Import browser-only utilities from /support (NOT the base path)
import { setupDefaultCommands, setupE2E } from '@trackunit/iris-app-e2e/support';

// Set up E2E environment
setupE2E();

// Register custom commands
setupDefaultCommands();

Cypress Configuration

Create a cypress.config.ts file:

Simple Configuration (Backward Compatible)

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)

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

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

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:

• Fetches environment configuration from /env endpoint
• Authenticates with Okta using session tokens
• Redirects to Manager

User Fixtures

Supported user fixture files:

• auth (default)

Example fixture file (cypress/fixtures/auth.json):

{
  "username": "[e-mail]",
  "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.

See also

@trackunit/iris-app-playwright provides the same fixtures and helpers for Playwright-based E2E tests. Both libraries are supported; teams opt in to Playwright on their own schedule and both e2e (Cypress) and e2e-pw (Playwright) targets can coexist in the same project.

Development

At this point this library is only developed by Trackunit Employees. For development related information see the development readme.

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.