@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.

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 { 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)

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:

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):

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

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.