Implement Automated Test

FOLIO Stripes — Cypress E2E Test Generation

Overview

FOLIO Stripes Testing is a Cypress-based E2E framework for the FOLIO library management system. Tests follow the page object / fragment pattern, use @interactors/html component abstractions, and combine API-driven test data setup with UI validation.

Quick Reference

Project Structure

cypress/
  e2e/                          # Test specs by FOLIO module
  support/
    fragments/                  # Page objects / UI helpers
    dictionary/
      permissions.js            # Centralized permission definitions
    constants.js                # Shared constants and data structures
interactors/                    # Component-level DOM abstractions

Test File Creation — Required Checklist

1. One spec file per test case — never bundle unrelated tests in a single file.
2. File naming: descriptive-test-name.cy.js — lowercase, hyphenated.
3. File location: mirror the FOLIO module hierarchy, e.g. cypress/e2e/inventory/settings/.
4. Test ID in it name: include C###### identifier in the test description string.
5. Tags attribute — every it block must have exactly 3 tag components:

it('C627455 Verify something works', { tags: ['extendedPath', 'spitfire', 'C627455'] }, () => { ... });

6. Unique test data prefix: AT_C######_Description_${getRandomPostfix()}.

Describe Block Hierarchy

Map the provided test case hierarchy directly to nested describe blocks:

"Inventory › Settings › Call number browse"

becomes:

describe('Inventory', () => {
  describe('Settings', () => {
    describe('Call number browse', () => {
      it('C##### Test name', { tags: [...] }, () => { ... });
    });
  });
});

If no hierarchy is specified, mirror the structure of the most similar existing test.

Standard Test Template

import permissions from '../../../support/dictionary/permissions';
import TopMenu from '../../../support/fragments/topMenu';
import ModulePage from '../../../support/fragments/moduleName/modulePage';
import { getRandomPostfix } from '../../../support/utils/stringTools';

describe('Module', () => {
  describe('Feature Area', () => {
    describe('Specific Function', () => {
      const randomPostfix = getRandomPostfix();
      const testData = {
        name: `AT_C######_Description_${randomPostfix}`,
      };
      let user;

      before('Create test data', () => {
        cy.getAdminToken().then(() => {
          // Create entities via API
        });

        cy.createTempUser([
          permissions.somePermission.gui,
        ]).then((userProperties) => {
          user = userProperties;
          cy.login(user.username, user.password, {
            path: TopMenu.someModulePath,
            waiter: ModulePage.waitContentLoading,
          });
        });
      });

      after('Delete test data', () => {
        cy.getAdminToken().then(() => {
          // Delete entities via API
        });
      });

      it('C###### Test description', { tags: ['extendedPath', 'teamName', 'C######'] }, () => {
        // UI interactions and assertions
      });
    });
  });
});

Interactors — Preferred Over Raw Selectors

Always prefer interactors. Only fall back to raw Cypress selectors when no interactor exists.

// ✅ Preferred
cy.do(Button('Save').click());
cy.expect(TextField('Name').has({ value: 'test' }));
cy.do(Select('Status').choose('Active'));

// ❌ Avoid unless necessary
cy.get('[data-testid="save-button"]').click();

Before writing a new selector, search existing fragments:

• grep_search("functionName", { includePattern: "support/fragments/**" })
• semantic_search("description of the UI action you need")

Fragment Architecture

Fragments are the page object layer. They expose named methods for navigation, interaction, and assertion — never raw selectors.

// support/fragments/moduleName/subModule.js
const SubModule = {
  waitLoading: () => cy.expect(/* loading indicator gone */),
  openForm: () => cy.do(Button('New').click()),
  fillName: (value) => cy.do(TextField('Name').fillIn(value)),
  save: () => cy.do(Button('Save').click()),
  verifyRecordExists: (name) => cy.expect(MultiColumnListCell(name).exists()),
};

export default SubModule;

Always reuse existing fragment methods before creating new ones.

Permissions

• Import from support/dictionary/permissions.js
• Always use .gui suffix for UI-level permissions

import permissions from '../../../support/dictionary/permissions';

cy.createTempUser([
  permissions.inventoryAll.gui,
  permissions.uiOrdersView.gui,
]);

For consortia (ECS) tests, permissions may need to be assigned per tenant.

Environment Variants

ECS / Consortia

• Multi-tenant tests with affiliation switching
• Tags use the ECS suffix: criticalPathECS
• Permissions assigned per tenant

Eureka

• Uses authorization roles instead of permission sets
• Uses capability sets / capabilities instead of permissions
• Detect with Cypress.env('eureka')

if (Cypress.env('eureka')) {
  // Eureka-specific setup
}

Common Patterns

Search Before Writing

Before implementing anything:

1. semantic_search("description of scenario") — find similar tests
2. grep_search("FragmentName", { includePattern: "support/fragments/**" }) — find page objects
3. Check support/dictionary/permissions.js — verify permissions exist
4. Check support/constants.js — find reusable data structures

Timing

• Never use bare cy.wait(ms) for UI stability — use fragment waitLoading() methods
• Default interactor timeout is 50 s globally; adjust only if a specific step genuinely requires it

Unique Data

import { getRandomPostfix } from '../../../support/utils/stringTools';
const randomPostfix = getRandomPostfix();
const itemName = `AT_C123456_Item_${randomPostfix}`;

Cleanup

Always delete test data in after() to prevent test pollution across runs.

Critical Rules

• One spec file per test case — no exceptions unless explicitly instructed
• Never skip after() cleanup — always delete created entities via API
• Never use raw selectors when a fragment or interactor exists — search first
• Always include all 3 tag components — group, team, test ID
• Always prefix test data with AT_C######_ + postfix for uniqueness
• ECS tests need permissions assigned per tenant, not globally
• Eureka tests use capability sets, not permission sets — check Cypress.env('eureka')