|
| 1 | +# Cypress E2E Testing |
| 2 | + |
| 3 | +This directory contains Cypress E2E tests for the StackRox Infra UI. |
| 4 | + |
| 5 | +## Quick Start - Running E2E Tests Against Local Backend |
| 6 | + |
| 7 | +### Prerequisites |
| 8 | + |
| 9 | +1. **Deploy the local backend** (with authentication disabled): |
| 10 | + |
| 11 | + ```bash |
| 12 | + # From the repository root |
| 13 | + make deploy-local |
| 14 | + ``` |
| 15 | + |
| 16 | + This deploys the infra-server to your local Kubernetes cluster with |
| 17 | + `LOCAL_DEPLOY=true`, which disables authentication for local development. |
| 18 | + |
| 19 | +2. **Start port-forwarding** to access the backend: |
| 20 | + |
| 21 | + ```bash |
| 22 | + kubectl port-forward -n infra svc/infra-server-service 8443:8443 |
| 23 | + ``` |
| 24 | + |
| 25 | + Keep this running in a separate terminal. |
| 26 | + |
| 27 | +3. **Configure the UI to connect to local backend**: |
| 28 | + |
| 29 | + ```bash |
| 30 | + cd ui |
| 31 | + cp .env.example .env.local |
| 32 | + ``` |
| 33 | + |
| 34 | + This creates a `.env.local` file. Note: The file contains |
| 35 | + `INFRA_API_ENDPOINT` but the environment variable must also be set when |
| 36 | + starting the dev server (see next step). |
| 37 | + |
| 38 | +4. **Start the UI dev server** (in a separate terminal): |
| 39 | + |
| 40 | + ```bash |
| 41 | + cd ui |
| 42 | + BROWSER=none PORT=3001 INFRA_API_ENDPOINT=http://localhost:8443 npm start |
| 43 | + ``` |
| 44 | + |
| 45 | + **Important:** The `INFRA_API_ENDPOINT` environment variable must be set when |
| 46 | + starting the dev server (not just in `.env.local`) because the proxy |
| 47 | + middleware reads it at startup. |
| 48 | + |
| 49 | + Keep this running. The dev server will: |
| 50 | + |
| 51 | + - Run on http://localhost:3001 |
| 52 | + - Proxy API requests to http://localhost:8443 (your local backend) |
| 53 | + - Hot-reload when you make changes to the UI code |
| 54 | + |
| 55 | +5. **Run the E2E tests** (in another terminal): |
| 56 | + |
| 57 | + ```bash |
| 58 | + cd ui |
| 59 | + npm run cypress:run:e2e |
| 60 | + ``` |
| 61 | + |
| 62 | +That's it! The tests will run against the UI dev server at |
| 63 | +http://localhost:3001, which proxies API requests to your local backend at |
| 64 | +`https://localhost:8443`. |
| 65 | + |
| 66 | +### Test Results |
| 67 | + |
| 68 | +After the tests complete: |
| 69 | + |
| 70 | +- **Videos** are saved to `ui/cypress/videos/` (one per test file) |
| 71 | +- **Screenshots** (on failures only) are saved to `ui/cypress/screenshots/` |
| 72 | + |
| 73 | +Review the videos to verify the tests are properly accessing the backend. |
| 74 | + |
| 75 | +## Interactive Mode |
| 76 | + |
| 77 | +To run tests interactively with the Cypress UI (useful for debugging): |
| 78 | + |
| 79 | +**Prerequisites:** Make sure the UI dev server is running (step 4 above). |
| 80 | + |
| 81 | +```bash |
| 82 | +cd ui |
| 83 | +npm run cypress:open |
| 84 | +``` |
| 85 | + |
| 86 | +Then: |
| 87 | + |
| 88 | +1. Select "E2E Testing" |
| 89 | +2. Choose a browser |
| 90 | +3. Click on any test file to run it |
| 91 | + |
| 92 | +Interactive mode lets you see the tests run in real-time, inspect the DOM, and |
| 93 | +debug failures. |
| 94 | + |
| 95 | +## Test Structure |
| 96 | + |
| 97 | +- `cypress/e2e/home.cy.ts` - Basic home page tests |
| 98 | +- `cypress/e2e/flavor-selection.cy.ts` - Tests for flavor API integration |
| 99 | + |
| 100 | +## Configuration |
| 101 | + |
| 102 | +Tests are configured in `cypress.config.ts` to: |
| 103 | + |
| 104 | +- Run against the UI dev server at `http://localhost:3001` (which proxies to the |
| 105 | + backend) |
| 106 | +- Accept self-signed certificates (`chromeWebSecurity: false`) |
| 107 | +- Capture videos of all test runs |
| 108 | +- Capture screenshots on failures only |
| 109 | +- Retry failed tests 2 times in CI mode (run mode), 0 times in interactive mode |
| 110 | + |
| 111 | +The UI dev server (configured via `ui/.env.local`) proxies API requests to your |
| 112 | +local backend at `https://localhost:8443`. |
| 113 | + |
| 114 | +## Adding More Tests |
| 115 | + |
| 116 | +To add new E2E tests: |
| 117 | + |
| 118 | +1. Create a new file in `cypress/e2e/` with the pattern `*.cy.ts` |
| 119 | +2. Follow the existing test patterns for consistency |
| 120 | +3. Run the tests locally before committing |
| 121 | + |
| 122 | +## Troubleshooting |
| 123 | + |
| 124 | +### Tests fail with "Cypress failed to verify that your server is running" |
| 125 | + |
| 126 | +**Solution:** Make sure the UI dev server is running on port 3001 before running |
| 127 | +tests: |
| 128 | + |
| 129 | +```bash |
| 130 | +cd ui |
| 131 | +BROWSER=none PORT=3001 npm start |
| 132 | +``` |
| 133 | + |
| 134 | +### Tests show "access denied" or authentication errors |
| 135 | + |
| 136 | +**Solution:** Verify that: |
| 137 | + |
| 138 | +1. The backend was deployed with `LOCAL_DEPLOY=true` (via `make deploy-local`) |
| 139 | +2. Port-forwarding is active: |
| 140 | + `kubectl port-forward -n infra svc/infra-server-service 8443:8443` |
| 141 | +3. The `.env.local` file points to the correct backend: |
| 142 | + `INFRA_API_ENDPOINT=https://localhost:8443` |
| 143 | + |
| 144 | +You can check if LOCAL_DEPLOY is enabled: |
| 145 | + |
| 146 | +```bash |
| 147 | +kubectl get deployment -n infra infra-server-deployment -o jsonpath='{.spec.template.spec.containers[0].env}' | grep LOCAL_DEPLOY |
| 148 | +``` |
| 149 | + |
| 150 | +### Port 3001 or 8443 already in use |
| 151 | + |
| 152 | +**Solution:** |
| 153 | + |
| 154 | +- Find and kill the process using the port: `lsof -i :3001` or `lsof -i :8443` |
| 155 | +- Or use different ports by modifying `cypress.config.ts` and `.env.local` |
| 156 | + |
| 157 | +## Documentation |
| 158 | + |
| 159 | +- Full Cypress documentation: https://docs.cypress.io/ |
| 160 | +- Cypress Best Practices: |
| 161 | + https://docs.cypress.io/guides/references/best-practices |
0 commit comments