Skip to content

Commit 4adf7bf

Browse files
asirvadAbrahamVargheseasirvadAbrahamVarghese
authored
Merge pull request #9955 from jrafanie/improve-cypress-usage
Add common Cypress usage patterns to README
2 parents a69c527 + b12d721 commit 4adf7bf

2 files changed

Lines changed: 111 additions & 19 deletions

File tree

‎cypress/README.md‎

Lines changed: 107 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,126 @@
11
### cypress in manageiq-ui-classic
22

3-
#### Run
3+
#### Setup
44

5-
**Prerequisites:**
5+
##### Initial Setup (One-Time)
66

7-
Before running Cypress tests, ensure the following:
7+
```bash
8+
cd manageiq-ui-classic
9+
yarn # Install Cypress and dependencies (run once initially, then again when packages are updated)
10+
```
811

9-
1. **Build webpack with CYPRESS flag** - This disables debug notifications that would block Cypress from accessing UI elements:
12+
**Database Requirements:**
1013

11-
CYPRESS=true bin/webpack
14+
Cypress uses the development database from `config/database.yml` and expects a clean, seeded database. If you need a populated development database for regular development, consider using a separate database for Cypress tests as pre-populated data may cause test failures. We are exploring ways to simplify this workflow.
1215

13-
If you skip this step, Cypress will show an error and refuse to start.
16+
The following command sets up the database as Cypress expects:
1417

15-
2. **Start the Rails server**:
18+
```bash
19+
dropdb vmdb_development; createdb vmdb_development; bundle exec rake db:migrate db:seed # from manageiq directory
20+
```
1621

17-
bin/rails s
22+
##### Before Running Tests
1823

24+
Build webpack with the CYPRESS flag (required before running tests, and whenever UI files change):
1925

20-
Run without interaction:
26+
```bash
27+
cd manageiq-ui-classic
28+
CYPRESS=true bin/webpack
29+
```
2130

22-
yarn cypress:run:chrome
23-
yarn cypress:run:firefox
31+
**Webpack Options:**
32+
- Use `CYPRESS=true bin/webpack` for a one-time build
33+
- Use `CYPRESS=true bin/webpack --watch` for automatic rebuilds when editing UI files
2434

25-
Will run the tests in console, and output a screengrab and screenshot in `cypress/screenshots` and `cypress/videos`.
35+
**Note:** If you skip this step, Cypress will show an error and refuse to start.
2636

27-
Run interactively:
37+
### Usage
2838

29-
yarn cypress:open
39+
##### Environment Variables
3040

31-
Opens a chrome instance for debugging.
41+
**Required**
3242

43+
- `CYPRESS=true` - disables debug notifications that would prevent Cypress from accessing UI elements and development mode code reloading
44+
45+
**Optional**
46+
47+
- `HEADED=true` - Run with visible browser (default: headless)
48+
- `SPEC="**/reports.cy.js"` - Run specific test file (default: all tests)
49+
- `CYPRESS_BROWSER=chromium|edge|firefox` - Run with alternative browser (default: chrome)
50+
51+
##### Method 1: Automated (Self-Contained)
52+
53+
Fully automated - no other processes needed. The rake task automatically handles starting the Rails server and simulating the queue worker.
54+
55+
```bash
56+
[HEADED=true] [SPEC="**/reports.cy.js"] [CYPRESS_BROWSER=chromium|edge|firefox] CYPRESS=true bundle exec rake spec:cypress
57+
```
58+
59+
##### Method 2: Automated (Manual Server)
60+
61+
Non-interactive but requires separate Rails server (and optionally Rails console with simulated queue worker for some tests).
62+
63+
Start Rails server in separate terminal:
64+
65+
```bash
66+
CYPRESS=true bin/rails s
67+
```
68+
69+
Optional: Start queue worker simulation in another terminal (needed for some tests):
70+
71+
```bash
72+
bundle exec rake app:evm:simulate_queue_worker # from manageiq-ui-classic directory
73+
# OR
74+
bundle exec rake evm:simulate_queue_worker # from manageiq directory
75+
```
76+
77+
Run tests with optional HEADED and SPEC parameters using Chrome (default):
78+
79+
```bash
80+
[HEADED=true] [SPEC="**/reports.cy.js"] CYPRESS=true yarn cypress:run:chrome
81+
```
82+
83+
Or use alternative browsers (chromium, edge, firefox):
84+
85+
```bash
86+
[HEADED=true] [SPEC="**/reports.cy.js"] CYPRESS=true yarn cypress:run:chromium
87+
[HEADED=true] [SPEC="**/reports.cy.js"] CYPRESS=true yarn cypress:run:edge
88+
[HEADED=true] [SPEC="**/reports.cy.js"] CYPRESS=true yarn cypress:run:firefox
89+
```
90+
91+
##### Method 3: Interactive
92+
93+
Run tests interactively with the Cypress UI (useful for debugging).
94+
95+
Terminal 1 - Start webpack with --watch for live UI updates:
96+
97+
```bash
98+
CYPRESS=true bin/webpack --watch
99+
```
100+
101+
Terminal 2 - Start Rails server:
102+
103+
```bash
104+
CYPRESS=true bin/rails s
105+
```
106+
107+
Terminal 3 - Simulate queue worker (needed for some tests):
108+
109+
```bash
110+
bundle exec rake app:evm:simulate_queue_worker # from manageiq-ui-classic directory
111+
# OR
112+
bundle exec rake evm:simulate_queue_worker # from manageiq directory
113+
```
114+
115+
Terminal 4 - Open Cypress interactive UI:
116+
117+
```bash
118+
CYPRESS=true yarn cypress:open
119+
```
120+
121+
This opens the Cypress UI where you can select and watch individual tests run.
122+
123+
Note: Without `--watch`, you can run webpack and Cypress UI in the same terminal.
33124

34125
#### Write
35126

@@ -43,7 +134,7 @@ ManageIQ implements the following cypress extensions:
43134

44135
* `cy.accordion(title)` - open an accordion panel. `title`: String for the accordion title for the accordion panel to open.
45136
* `cy.accordionItem(name)` - click on a record in the accordion panel. `name`: String for the record to click in the accordion panel.
46-
* `cy.selectAccordionItem(accordionPath)` - navigates the expanded accordion panel(use cy.accordion to expand an accordion panel) and then expand the nodes along the given path and click the final target item. `accordionPath`: A mixed array of strings and/or regex patterns that represent the path to the intended target node. e.g. Simple string path: `cy.selectAccordionItem(['Datastore', 'My-Domain', 'My-Namespace']);`, Path with regular expressions: `cy.selectAccordionItem([/^ManageIQ Region:/, /^Zone:/, /^Server:/]);`, Mixed path with strings and regular expressions: `cy.selectAccordionItem([/^ManageIQ Region:/, 'Zones', /^Zone:/]);`
137+
* `cy.selectAccordionItem(accordionPath)` - navigates the expanded accordion panel(use cy.accordion to expand an accordion panel) and then expand the nodes along the given path and click the final target item. `accordionPath`: A mixed array of strings and/or regex patterns that represent the path to the intended target node. e.g. Simple string path: `cy.selectAccordionItem(['Datastore', 'My-Domain', 'My-Namespace']);`, Path with regular expressions: `cy.selectAccordionItem([/^ManageIQ Region:/, /^Zone:/, /^Server:/]);`, Mixed path with strings and regular expressions: `cy.selectAccordionItem([/^ManageIQ Region:/, 'Zones', /^Zone:/]);`
47138

48139
##### gtl
49140

‎package.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@
1212
],
1313
"scripts": {
1414
"cypress:open": "cypress open",
15-
"cypress:run:chrome": "cypress run --headless --browser chrome ${SPEC:+--spec \"$SPEC\"}",
16-
"cypress:run:edge": "cypress run --headless --browser edge ${SPEC:+--spec \"$SPEC\"}",
17-
"cypress:run:firefox": "cypress run --headless --browser firefox ${SPEC:+--spec \"$SPEC\"}",
15+
"cypress:run:chrome": "cypress run ${HEADED:+--headed} ${HEADED:---headless} --browser chrome ${SPEC:+--spec \"$SPEC\"}",
16+
"cypress:run:chromium": "cypress run ${HEADED:+--headed} ${HEADED:---headless} --browser chromium ${SPEC:+--spec \"$SPEC\"}",
17+
"cypress:run:edge": "cypress run ${HEADED:+--headed} ${HEADED:---headless} --browser edge ${SPEC:+--spec \"$SPEC\"}",
18+
"cypress:run:firefox": "cypress run ${HEADED:+--headed} ${HEADED:---headless} --browser firefox ${SPEC:+--spec \"$SPEC\"}",
1819
"test": "jest",
1920
"test:watch": "jest --watchAll",
2021
"test:current": "jest --watch",

0 commit comments

Comments
 (0)