@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

``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

$3

- 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

$3

- setupE2E - Complete E2E test environment setup
- setupHarRecording - HAR file recording for failed tests
- Terminal logging - Comprehensive test logging and error capture

$3

- defaultCypressConfig - Configurable Cypress configuration
- setupPlugins - Plugin setup with logging and HAR generation
- File utilities - Log file creation and formatting tools

Usage

$3

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();
`

$3

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
);
}
}
});
`

$3

`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

$3

`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
}
`

$3

- 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

$3

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.

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