Rooms Management System - E2E Testing Documentation¶

Overview¶

The app/frontend/cypress folder provides comprehensive end-to-end (E2E) testing coverage for the Rooms Management System, a web-based application for managing rooms, users, displays, roles, events, and tasks. The test suite uses Cypress to automate UI testing, form validation, CRUD operations, permissions, and user workflows across the entire application.

Project Purpose¶

The Rooms Management System is a multi-user application designed to manage smart room resources. This testing suite validates:

User authentication and authorization
Complete CRUD operations on all entities (Rooms, Users, Displays, Roles, Events, Tasks)
Role-based access control and permissions
UI navigation and interaction
Form input validation
Event triggers and task management
Backend API read and write access

Core Functionality¶

Tested Entities¶

Rooms - Manage physical room spaces with attributes (location, capacity, event schedule)
Users - User management with email authentication and role assignment
Displays - Hardware display registration and management (MAC address-based)
Roles - Custom role creation with permission management
Events - Event scheduling tied to rooms
Tasks - Task creation and assignment for users and rooms
Event Types & Task Types - Configurable entity classifications for distinguishing different Event and Task purposes

Test Coverage¶

The test suite includes:

Env.cy.js - Core helper functions and API spies
TestClick.cy.js - UI navigation and interaction testing
TestFill.cy.js - Form input and validation testing
TestCreate.cy.js - Complete CRUD operations and entity creation
TestCreateDelete.cy.js - Create and delete workflows
TestCreateEdit.cy.js - Create and edit workflows
TestCRUD.cy.js - Full CRUD cycle testing
TestPermissions.cy.js - Role-based access control validation
TestUserLogin.cy.js - Authentication workflows
Tables.cy.js - Table interaction utilities

Quick Start Guide¶

Prerequisites¶

Node.js (v14 or higher)
Docker with backend service running on port 8081
Backend service container named backend_devcontainer and database service named backend_devcontainer-postgres-1
PostgreSQL database accessible to the backend service

Setup Instructions¶

1. Configure Environment¶

Create a .env file in the backend directory. Use .env copy as a reference template:

# Copy the template
cp ".env copy" ../../backend/.env

# Edit with your configuration
nano ../../backend/.env

2. Start Backend Server¶

Ensure the backend API is running:

# In the backend directory
docker-compose up
# or for the specific container
docker start backend_devcontainer-postgres-1
# or using the dev container of vscode in backend directory
code .
# press open folder in docker container, make sure docker plugin is installed

Verify backend is accessible at http://localhost:8081/v1/health/

3. Build and Serve Frontend¶

# In the parent frontend directory
npm install
npm run build
npm run preview

The frontend will be served at http://localhost:4173 (used by Cypress tests). Make sure to use the production build so the server is run realistically.

4. Initialize Database Dump¶

Create an initial database snapshot for test isolation: (this is optional if cypress is used)

1	`./resetdb.sh`

This creates dump.sql - the baseline database state for all tests.

Running Tests¶

Interactive Mode (Recommended for Development)¶

Open the Cypress Test Runner:

1	`npx cypress open`

This launches an interactive browser where you can:

Select individual tests to run
View test execution in real-time
Debug with browser DevTools
Re-run tests with code changes

Using Firefox¶

npx cypress open --browser firefox

Headless Mode (CI/CD)¶

Run all tests without opening the browser:

1	`npx cypress run`

Run specific test file:

npx cypress run --spec "cypress/e2e/TestCreate.cy.js"

Run tests with Firefox:

npx cypress run --browser firefox

Run with custom viewport:

npx cypress run --config viewportWidth=1920,viewportHeight=1080

Available Test Suites¶

Tests UI element interactions and sidebar navigation.

Tests:

Login functionality with valid/invalid credentials
Logout workflow
Sidebar navigation to all main sections (Rooms, Users, Displays, Roles, Events, Tasks)
Combobox and list interactions
Button clicks across all pages
Responsive menu toggle

Use Case: Validates that all UI elements are functional and navigation works correctly.

2. TestFill.cy.js - Form Validation & Input¶

Tests form input handling and field population.

Tests:

Fill room creation forms with various input types
Populate user registration fields
Display registration form completion
Role, event, and task form population
Input validation and error handling

Use Case: Ensures all form fields accept input correctly and validation rules are enforced.

3. TestCreate.cy.js - Full CRUD Creation Workflows¶

Tests the complete entity creation process.

Tests:

Create rooms with full specifications
Create users with authentication credentials
Register new displays with hardware details
Create roles with permissions
Create events and event types
Create tasks and task types

Use Case: Validates that new entities can be created with all required fields and persist in the database.

4. TestCreateDelete.cy.js - Create & Delete Workflows¶

Tests creation followed by deletion of entities.

Tests:

Create and delete rooms
Create and delete users
Create and delete displays
Create and delete roles, events, tasks

Use Case: Ensures cleanup operations work and database consistency is maintained.

5. TestCreateEdit.cy.js - Create & Edit Workflows¶

Tests entity modification after creation.

Tests:

Create entities with initial data
Edit room properties
Update user information
Modify display settings
Edit roles, events, and tasks

Use Case: Validates that entity updates persist correctly.

6. TestCRUD.cy.js - Complete CRUD Cycle¶

Full create-read-update-delete testing for all entities.

Tests:

Complete lifecycle of each entity type
Verify data persistence
Confirm deletions

Use Case: Comprehensive testing of all data operations.

7. TestPermissions.cy.js - Role-Based Access Control¶

Tests permission enforcement for different user roles. According to the roles.md file

Tests:

Admin user access
Regular user restrictions
Role-specific visibility
Permission enforcement on operations

Use Case: Validates that role-based access control works correctly.

8. TestUserLogin.cy.js - Authentication¶

Tests user authentication flows with different credentials.

Tests:

Login with admin account
Login with different user roles
Login failure scenarios
Session management

Use Case: Ensures authentication is secure and role-based access is enforced.

Architecture & Components¶

Test File Organization¶

cypress/
├── e2e/
│   ├── Env.cy.js              # Shared utilities and helper functions
│   ├── Fill.cy.js             # Form-filling functions
│   ├── Tables.cy.js           # Table interaction utilities
│   ├── TestClick.cy.js        # Navigation & UI testing
│   ├── TestCreate.cy.js       # Create operations
│   ├── TestCreateDelete.cy.js # Create-delete workflows
│   ├── TestCreateEdit.cy.js   # Create-edit workflows
│   ├── TestCRUD.cy.js         # Full CRUD testing
│   ├── TestPermissions.cy.js  # Permission testing
│   ├── TestUserLogin.cy.js    # Authentication testing
│   └── 0-rooms/               # Room-specific tests
├── support/
│   ├── commands.js            # Cypress custom commands
│   └── e2e.js                 # E2E-specific configuration
├── fixtures/                  # Test data (if needed)
└── screenshots/               # Auto-captured test failures

Helper Functions¶

Env.cy.js - Core Utilities¶

UI Interaction:

login(username, password) - Authenticate user
logout() - Sign out
getInputAndType(label, text) - Fill form inputs
getButtonAndClick(text, index) - Click buttons
getComboboxAndClick(text) - Interact with dropdown menus
getCheckboxAndClick(label) - Toggle checkboxes
getSwitchAndClick(label) - Toggle switches

API & Network:

spyOnApi() - Intercept and spy on all API calls
waitForApi(alias) - Wait for specific API request
interceptAndWait(method, url, alias) - Custom API interception

Navigation:

getSidebarAndClick(item) - Navigate via sidebar menu
clickMenuIcon() - Toggle responsive menu
clickOutside() - Close modals/dropdowns

Database:

resetDatabase() - Reset database to initial state using dump file

Fill.cy.js - Form Population¶

Entity-specific form-filling functions:

fillRoom(action, name, location, capacity, ...)
fillUser(action, email, username, name, role, password)
fillDisplay(action, mac, type, resolution, room)
fillRole(action, name, ...)
fillEvent(action, ...)
fillTask(action, ...)
fillEventType(action, ...)
fillTaskType(action, ...)

Table search and manipulation utilities:

roomsTableContains(name) - Find room in table
usersTableContains(username) - Find user in table
displayTableContains(mac) - Find display in table
editEntryFromTable(callback, name) - Click edit action
deleteEntryFromTable(callback, name) - Click delete action

Configuration¶

cypress.config.js settings:

{
  baseUrl: "http://localhost:4173",        // Frontend URL
  viewportHeight: 900,
  viewportWidth: 1280,
  selectorPriority: [                      // Element selection strategy
    "data-cy",    // Most preferred
    "data-test",
    "data-testid",
    "data-qa",
    "label",
    "name",
    "id",
    "class",
    "tag",
    "attributes",
    "nth-child"   // Least preferred
  ]
}

Test Execution Workflow¶

1. Database Initialization¶

Each test run starts with a clean database:

1 2	`# Create or restore from dump ./resetdb.sh`

The resetdb.sh script:

Creates dump.sql (PostgreSQL dump) if missing
Drops existing database
Recreates database from dump file
Ensures test isolation and consistency

Every test:

Calls login() to authenticate
Calls spyOnApi() to monitor API traffic
Navigates to required page
Performs test actions

beforeEach(() => {
  login();           // Authenticate as admin
  spyOnApi();        // Monitor API calls
});

3. Action & Verification¶

Tests perform actions using helper functions:

// Fill and submit form
fillRoom('create', 'Test Room', 'Building A', '20', 'Conference');
getButtonAndClick('Create Room');

// Wait for API response
waitForApi('postRooms');

// Verify result in table
roomsTableContains('Test Room');

4. Assertion & Cleanup¶

Tests verify outcomes:

Check HTTP response status
Verify data in UI tables
Confirm error messages appear/disappear
Database state before/after operations

API Integration¶

Intercepted Endpoints¶

Cypress intercepts all backend API calls for testing:

Rooms API:

GET /v1/rooms/ - List all rooms
POST /v1/rooms/ - Create room
GET /v1/rooms/{id} - Get specific room
PUT /v1/rooms/{id} - Update room
DELETE /v1/rooms/{id} - Delete room

Similar patterns for: Users, Displays, Roles, Events, Tasks, Event Types, Task Types

Monitoring API Calls¶

// Spy on all APIs
spyOnApi();

// Wait for specific request to complete
waitForApi('postRooms');

// Access intercepted request data
cy.wait('@postRooms').then(interception => {
  const requestBody = interception.request.body;
  const responseStatus = interception.response.statusCode;
});

Test Database Management¶

Database Reset Workflow¶

Problem: Tests need isolation; running multiple tests on same database causes state conflicts.

Solution: resetdb.sh automatically resets database before each test run.

How It Works¶

1. Initial Setup:¶

1	`./resetdb.sh`

Creates dump.sql containing clean database snapshot

2. Before Each Test:¶

beforeEach(() => {
  resetDatabase();  // Programmatically reset via dump
});

3. Reset Process:¶

Reads resetdb.sh script
Executes via cy.exec() in Docker container
Drops current database
Restores from dump.sql

4. Result: Each test starts with identical clean state¶

Create Fresh Dump¶

If database needs reset:

# Remove old dump
rm dump.sql

# Create new dump (regenerates when script runs)
./resetdb.sh

Troubleshooting¶

Issue: Backend Connection Failed¶

Problem: connect ECONNREFUSED 127.0.0.1:8081

Solution:

# Verify backend is running
docker ps | grep backend

# Start backend container
docker start backend_devcontainer-postgres-1

# Check backend logs
docker logs backend_devcontainer-postgres-1

Issue: Frontend Not Loading¶

Problem: Tests fail to reach localhost:4173

Solution:

# In parent frontend directory
npm run build
npm run preview

# Verify frontend is running
curl http://localhost:4173

Issue: Database Reset Fails¶

Problem: resetdb.sh: command not found or permission denied

Solution:

# Make script executable
chmod +x resetdb.sh

# Verify PostgreSQL is running
docker ps | grep postgres

Issue: Test Timeouts¶

Problem: Tests timeout waiting for API or elements

Solution:

Increase Cypress timeout in cypress.config.js
Verify backend API is responding
Check network latency with browser DevTools
Run tests individually to isolate issue

Issue: Created Users are not verified¶

Problem: Newly created users must be verified by their email

Solution:

Check the given email and click the link to verifiy
Use verfifydb.sh to verify the users directly with a database command
Currently the usernames cypressuser1@example.com to cypressuser6@example.com are supported in this bash file

Issue: Flaky Tests¶

Problem: Tests pass sometimes, fail others

Solution:

Add explicit waits: waitForLoadingOverlay(), waitForApi()
Avoid hardcoded cy.wait() - use proper waits
Ensure database is clean before running
Check for race conditions in async operations

Issue: Cypress Tests Won’t Work after new patches¶

Problem: Cypress files are designed to describe the expected behaviour not if the code works fine

Solution:

Identify which test case fails
Open a cypress development browser with this test case, see section below
Optionally: Mark this test with describe.only(...) or it.only()
Run the test again and analyze which behaviour was described but not seen in the UI or API

Skipping Tests¶

To temporarily disable tests during development:

// Skip single test
it.skip('should create a room', () => {
  // test code
});

// Skip entire suite
describe.skip('Room Management', () => {
  // test code
});

Development Workflows¶

Running Tests During Development¶

Run all tests:

1	`npx cypress run`

Run specific test file:

npx cypress run --spec "cypress/e2e/TestCreate.cy.js"

Run in interactive mode:

1	`npx cypress open`

Run with Firefox:

npx cypress run --browser firefox

Adding New Tests¶

Create new test file in cypress/e2e/TestName.cy.js
Import helpers from Env.cy.js and Fill.cy.js:

import { login, waitForApi, spyOnApi } from './Env.cy';
import { fillRoom } from './Fill.cy';

Write test following existing patterns:

describe('New Feature', () => {
  beforeEach(() => {
    login();
    spyOnApi();
  });

  it('should perform action', () => {
    fillRoom('create', 'Test', 'Location', '20', 'Type');
    getButtonAndClick('Create Room');
    waitForApi('postRooms');
    roomsTableContains('Test');
  });
});

Adding New Helper Functions¶

Add function to Env.cy.js or Fill.cy.js
Export function for use in tests:

export function myNewHelper(param) {
  // implementation
}

Import in test files as needed

CI/CD Integration¶

GitLab CI/CD Pipeline Job¶

The cypress:test job in .gitlab-ci.yml runs Cypress end-to-end tests in the GitLab CI/CD pipeline:

Configuration: - Image: cypress/browsers:25.0.0 - Pre-built Docker image with Cypress and Firefox/Chrome browsers - Stage: test - Trigger: Manual trigger only (when: manual) - Branches: Runs only on branches named 01-cypress, 02-cypress, or 03-cypress - Failure Handling: allow_failure: true - test failures won’t block the pipeline - Runner Tags: Requires runners with the cypress-test tag

Job Steps: 1. Verifies internet connectivity to Google 2. Navigates to app/frontend directory 3. Installs dependencies with npm ci 4. Runs Cypress tests using Firefox: npx cypress run --browser firefox

Running Tests in Pipeline¶

#!/bin/bash
# Docker containers must be running
docker-compose up -d

# Install dependencies
npm install

# Run all tests
npx cypress run

# Run with JUnit report for CI systems
npx cypress run --reporter junit --reporter-options mochaFile=cypress/results/junit.xml

Test Results¶

Screenshots auto-saved to cypress/screenshots/ on failure
Videos can be enabled in cypress.config.js
JSON reports available with appropriate reporters

Best Practices¶

Isolation: Each test should be independent and work with clean database state
Reusability: Use helper functions from Env.cy.js instead of writing inline commands
Waits: Use explicit waits (waitForApi(), waitForLoadingOverlay()) instead of hardcoded delays
Selectors: Prefer data attributes (data-cy, data-test) over brittle selectors, otherwise use custom seletor wrappers
Cleanup: Database resets automatically at the beginning of a test file; no manual cleanup needed
Debugging: Use Cypress browser DevTools for inspection during test failure

User Testing (NUTZERTESTS)¶

In addition to automated E2E testing, comprehensive user testing has been performed on the Rooms Management System. The user testing results and findings are documented in the app/frontend/cypress/ folder:

NUTZERTEST_AUSWERTUNG - Detailed analysis and evaluation of the user testing results
NUTZERTEST_NOTIZEN - Notes and observations from user testing sessions

These files contain valuable insights into user experience, usability findings, and feedback that complement the automated test suite.

Most feedback is already implemented but additional user test might give up-to-date insights.

Support & Documentation¶

Cypress Official Docs: [https://docs.cypress.io/]
Environment Variables: See .env copy for configuration template
Database Schema: See roles.md for permission documentation ROLES.md
Backend API: Available at http://localhost:8081/v1/health/ when running

Summary¶

This E2E testing suite provides comprehensive coverage of the Rooms Management System, ensuring reliability across all user workflows and entity operations. Tests are well-organized, maintainable, and follow industry best practices for automated testing. 3. Open Cypress with npx cypress open 4. Select Firefox browser (optional, default is Chromium) 5. Choose and run your e2e tests 6. Tests will automatically use the database dump to reset between runs

Rooms Management System - E2E Testing Documentation¶

Overview¶

Project Purpose¶

Core Functionality¶

Tested Entities¶

Test Coverage¶

Quick Start Guide¶

Prerequisites¶

Setup Instructions¶

1. Configure Environment¶

2. Start Backend Server¶

3. Build and Serve Frontend¶

4. Initialize Database Dump¶

Running Tests¶

Interactive Mode (Recommended for Development)¶

Using Firefox¶

Headless Mode (CI/CD)¶

Available Test Suites¶

1. TestClick.cy.js - UI Navigation & Interaction¶

2. TestFill.cy.js - Form Validation & Input¶

3. TestCreate.cy.js - Full CRUD Creation Workflows¶

4. TestCreateDelete.cy.js - Create & Delete Workflows¶

5. TestCreateEdit.cy.js - Create & Edit Workflows¶

6. TestCRUD.cy.js - Complete CRUD Cycle¶

7. TestPermissions.cy.js - Role-Based Access Control¶

8. TestUserLogin.cy.js - Authentication¶

Architecture & Components¶

Test File Organization¶

Helper Functions¶

Env.cy.js - Core Utilities¶

Fill.cy.js - Form Population¶

Tables.cy.js - Table Navigation¶

Configuration¶

Test Execution Workflow¶

1. Database Initialization¶

2. Login & Setup¶

3. Action & Verification¶

4. Assertion & Cleanup¶

API Integration¶

Intercepted Endpoints¶

Monitoring API Calls¶

Test Database Management¶

Database Reset Workflow¶

How It Works¶

1. Initial Setup:¶

2. Before Each Test:¶

3. Reset Process:¶

4. Result: Each test starts with identical clean state¶

Create Fresh Dump¶

Troubleshooting¶

Issue: Backend Connection Failed¶

Issue: Frontend Not Loading¶

Issue: Database Reset Fails¶

Issue: Test Timeouts¶

Issue: Created Users are not verified¶

Issue: Flaky Tests¶

Issue: Cypress Tests Won’t Work after new patches¶

Skipping Tests¶

Development Workflows¶

Running Tests During Development¶

Adding New Tests¶

Adding New Helper Functions¶

CI/CD Integration¶

GitLab CI/CD Pipeline Job¶

Running Tests in Pipeline¶

Test Results¶

Best Practices¶

User Testing (NUTZERTESTS)¶

Support & Documentation¶

Summary¶