dc/.agents/skills/dc-cypress/SKILL.md

name, description

name

description

dc-cypress

Use this skill when writing or debugging Cypress E2E specs in the dc repo, or when working on the JS mock backend they run against. Covers the SASjs Server mock environment (deploy, seed, ports), the spec conventions the CI harness expects, the viewer/editor DOM selectors that the existing specs get wrong, the fixed 1280x720 video capture, and the rule that a mock service must mirror the real SAS service it stands in for.

Cypress E2E and the JS mock backend

The specs under client/cypress/e2e/ run against a mock backend: JS stored programs under sas/mocks/sasjs/services/ executed by SASjs Server in JS-only mode. No SAS licence, no SAS server. CI (.gitea/workflows/build.yaml) builds the same environment - SASjs Server on :5000, sasjs cbd -t server-ci, makedata, then ng serve on :4200 - and runs a fixed list of specs against it.

This skill covers the parts that are not obvious from reading a spec file: how to stand the environment up, the selectors that actually work, and the traps in the mock services. It does not cover the SAS-side tests (see .agents/docs/testing.md and the dc-sas skill).

When to Use

• Adding or changing a spec under client/cypress/e2e/.
• A mock service needs a new behaviour, or a spec "does nothing" because the mock ignores an input.
• Recording a demo video from a spec run.
• Debugging a spec that passes locally but fails in CI (usually a viewport or timing assumption).

Don't use for: SAS backend tests (sasjs test -t 4gl), Angular unit tests (npm run test:headless), or general SAS development (use the dc-sas skill).

Stand up the mock environment

1. SASjs Server, JS mode. Download the linux build from the sasjs/server releases, then create a .env next to the binary:

   RUN_TIMES=js
   NODE_PATH=node
   CORS=enable
   WHITELIST=http://localhost:4200
   

   Start it (./api-linux). It runs in desktop mode on :5000 with no authentication.

2. Deploy the mocks.

   cd sas/mocks/sasjs && sasjs cbd -t server-ci
   

   To start from a clean appLoc, delete it first:

   curl -sS -X DELETE "http://localhost:5000/SASjsApi/drive/folder/?_folderPath=/Public/app/dc"
   

3. Seed the mock database.

   cd sas/mocks && sasjs request services/admin/makedata -t server-ci \
       -d deploy/makedata.json -o ./makedata_out.json
   

   makedata replies with HTML (it is normally called as a URL redirect), so the CLI reports invalid Json string. That is expected - check the drive instead.

4. Frontend. Point the sasjs tag in client/src/index.html at the mock backend (serverUrl="http://localhost:5000", appLoc="/Public/app/dc", serverType="SASJS" - a local-only edit, the repo default is serverUrl=""), then npx ng serve --host 0.0.0.0 --port 4200. client/cypress.env.json needs username/password entries; any values work, loginAndUpdateValidKey() no-ops when there is no login form.

5. Run.

   cd client && npx cypress run --browser electron --spec cypress/e2e/<spec>.cy.ts
   

   Only Electron is installed here (no system Chrome), so always pass --browser electron.

Spec conventions

• Start the file with export {} so its top-level consts do not collide with other spec files under the TS type-checker.
• beforeAll: cy.visit(\${hostUrl}/SASLogon/logout`)thency.loginAndUpdateValidKey(true). The true` forces a licence key instead of relying on an earlier spec in the same run having applied one.
• beforeEach: cy.visit(hostUrl + appLocation), visitPage('home'), visitPage('view/data'). The home visit is what triggers the startup-data fetch; going straight to view/data leaves the nav tree empty in slower environments.
• Declare helpers at the bottom of each spec file (that is the house pattern) - do not introduce a shared helper module.
• Use Cypress.env('longerCommandTimeout') for waits and gate on .app-loading disappearing.
• No artificial delays. These specs are the CI regression suite, so cy.wait(n) to "let a result land" is not acceptable - assert on the resulting state instead (Cypress retries assertions). Replace a sleep with a state assertion: e.g. after picking an option from a soft-select, wait for #datalist_<inputId> to have class hidden rather than sleeping.
• Lint: cd client && npm run lint:check (prettier covers cypress/e2e/*.cy.ts).

Selectors that work

• Viewer search box: input[name="search-input"] (Enter or the magnifier icon submits); the numeric toggle is input[name="numeric_check"].
• Row/column count in the header: .title-col p renders (1,000 rows, 9 cols) - and (1 row, 9 cols) when the result is a single row, so an assertion on the count has to pluralise.
• Filter info bar: .infoBar b - only rendered when the backend's sasparams.FILTER_TEXT is neither blank, ' ', nor '1=1'.
• Empty result: .noData h3 with No data found with given conditions.
• Grid: #hotTable .ht_master.handsontable .htCore tbody tr (body rows), #hotTable .ht_clone_top .htCore thead (headers, and button.changeType confirms Handsontable has finished rendering them).
• Nav tree: .nav-tree clr-tree > clr-tree-node -> .clr-tree-node-content-container .clr-treenode-content p (expands a library) -> .clr-treenode-link (table links).
• Viewer filter modal - .filterSide (the options button) -> .dropdown-menu contains Filter -> #vals_var_id0_0 (variable, pick from #datalist_vals_var_id0_0 option) and #vals_0_0 (value) -> .filter-modal button[aria-label="Ok"].
  • filtering.cy.ts opens the filter with .btnCtrl .btnView, which is an editor control and does not exist in the viewer. Do not copy that helper into a viewer spec.
  • The soft-select inputs drop a transparent click-catcher over the modal while their suggestion list is open, so Cypress reports the Ok button (and the next input) as covered by .overlay. Send the Escape keyup a user would send (trigger('keyup', { key: 'Escape', force: true })) and wait for the list to close before clicking on.

Recording a demo video

video: true in cypress.config.ts is all that is needed. Run the spec and the MP4 lands in client/cypress/videos/<spec>.mp4.

The capture is the browser window's content area, and it contains the Cypress runner - the command log takes the left ~450px and the app is rendered in the remaining pane, so the pane is (capture width - 450) x (capture height - 96) and the app is zoomed to fit it.

That makes the window size the only lever that matters:

• Electron is stuck at 1280x720 (it ignores --window-size), i.e. an 830x624 pane, and the repo's 1600x900 viewport renders at 50% - the app only occupies ~806x452 of it.
• A real Chromium browser honours --window-size, so the capture can be sized to whatever the pane needs. cypress.config.ts passes it through from RECORD_WINDOW_SIZE (inert in CI, which sets no env).

For a 16:9 pane, solve (W - 450) / (H - 96) = 16/9: W = 1920 gives H = 923 of window content, and Chrome adds ~87px of window chrome above that, so pass 1920x1010:

RECORD_WINDOW_SIZE=1920,1010 npx cypress run \
  --browser /opt/data/profiles/dc/tools/chrome-linux64/chrome \
  --spec cypress/e2e/full-table-search.cy.ts \
  --env skipNegative=true,demoPause=1500

That yields a 1920x922 capture with a 1470x826 pane (16:9) and, at the repo's 1600x900 viewport, an app at ~0.90 zoom occupying 1441x812 - about 1.9x the linear size of the 16:9 crop Electron can give. Crop the app out:

ffmpeg -ss <start> -i cypress/videos/<spec>.mp4 -vf "crop=1440:812:464:80" \
  -an -c:v libx264 -preset slow -crf 18 -pix_fmt yuv420p \
  -movflags +faststart <spec>-cut.mp4

Measure the crop rect from the frames rather than guessing: the pane's flat background is rgb(225,227,236), so a row/column scan for pixels that differ from it gives the app's bounding box (for the 1920x922 capture: runner pane ends x=449, app x=463-1903, app y=80-893; for the 1280x720 Electron capture: app x=468-1259, y=80-675). The app's own background is nearly the same grey, so verify the result on the first, middle and last frames rather than trusting a pixel test alone.

To find where to cut, scan the mean and standard deviation of the content area: the app boots mid-run (a dark screen, mean ~65, sd ~2.5), the "Loading Table Viewer" spinner is flat and light (mean ~252, sd ~0), and the rendered table is mean ~245, sd ~31. Cut on the first table frame - cutting a fraction early shows the boot screen or the spinner.

Cypress starts its own Xvfb for the run (a second display appears in /tmp/.X11-unix), so an external DISPLAY is ignored; --force-device-scale-factor and a CSS zoom also do not change the capture.

Grid columns that are clipped

Handsontable sizes columns to content, so a narrow result can be wider than the grid viewport: the horizontal scrollbar appears and the rightmost column (NOTES on MPE_X_SEARCH) is cut off. The cell text is still in the DOM, so an assertion passes either way - the column only has to be scrolled into view for the video to show why the rows matched.

const scrollGridTo = (position: 'left' | 'right') => {
  cy.get('#hotTable .wtHolder').first().then(($holder: any) => {
    const el = $holder[0]
    el.scrollLeft = position === 'right' ? el.scrollWidth : 0
    expect(el.scrollLeft).to.equal(position === 'right' ? el.scrollWidth - el.clientWidth : 0)
  })
}

Setting scrollLeft is enough - Handsontable keeps the header clone in step - and the browser clamps it to scrollWidth - clientWidth, so that is what scrolling right has to land on. This is a legitimate spec step (it runs in CI), not a recording flag.

A longer, more readable demo

A spec that doubles as a walkthrough should be a single it(): open the table once and make each variation a search in place. The recording then reads as a demo rather than a sequence of page loads, and it is far faster - every extra it() pays for the beforeEach navigation again.

Two recording-only env flags, both inert in CI because CI passes no env:

const skipNegative = `${Cypress.env('skipNegative')}` === 'true'
const negativeStep = (step: () => void) => {
  if (!skipNegative) step()
}
const demoPauseMs = Number(Cypress.env('demoPause')) || 0

negativeStep(() => {
  searchFor('trench')
  assertNoData()
})

• skipNegative=true drops the steps that legitimately match nothing (wrong case, partial number, value not present), so the recording never shows an empty screen.
• demoPause=1500 pauses 1.5s at each row-count assertion, so each result can be read. Apply it in one place (the row-count assertion, which every beat makes exactly once) rather than sprinkling cy.wait() through the test - CI still runs the file with no waits at all.

More beats, not a slower take, is what makes a demo longer: a walkthrough of 12 row-count beats takes 52s against 30s for 7.

Mock services

• One JS file per service under sas/mocks/sasjs/services/**, deployed as SASjs stored programs. Shared helpers live in sas/mocks/sasjs/services/dcMockUtils.js (fetchTable/parseCsv for %webout(FETCH), webOutOpen/webOutObj/webOutClose for %webout, mpeFilterMaster, mpFilterGenerate, mpFilterStore, getDdType, formatSasValue, sasVarsEntry).
• Mock data is one JSON file per table at <drive>/files/<appLoc>/data/<LIBREF>/<table>.json, written by services/admin/makedata.js (which also writes services/settings.js). The drive lives under the SASjs Server directory (sasjs_root/drive).
• makedata.js self-destructs after a successful run (it deletes itself from the drive so the frontend can detect completion), so re-deploy before re-seeding.
• A mock must mirror the real service. viewdata.js once ignored FILTER_RK and hard-coded FILTER_TEXT to blank, so the viewer's filter silently filtered nothing and its info bar never showed a clause, while the real viewdata.sas applies %mpe_filtermaster and then %mp_searchdata. If a mock is a deliberate stub, say so in a comment and make the divergence explicit - a mock that quietly drops an input turns an E2E spec into a test of nothing.

Pitfalls

• sasjs cbd -t server-ci rebuilds the mock services and re-deploys the streamed web app from client/dist; it does not rebuild the Angular app.
• Deleting the drive folder before deploying avoids stale services and stale data.
• Captured _webout JSON, request logs and iteration snapshots belong in tmp/ (gitignored), never in sas/mocks/ - see the dc-sas skill.
• The mock server has no auth, so cy.visit on /SASLogon/logout returns 404 - that is fine, Cypress does not fail on the status code.

Verification

• npx cypress run --browser electron --spec <specs> - all green, and run it more than once when you have just removed a wait.

• cd client && npm run lint:check passes.

• For a mock change, hit the service directly before writing UI assertions:

  curl -sS -H "Content-Type: application/json" -X POST \
    --data '{"_program":"/Public/app/dc/services/public/viewdata","SASControlTable":"LIBDS:$41. FILTER_RK:best. SEARCHTYPE:$4 SEARCHVAL:$1000\nDC_JSLIB.MPE_X_SEARCH,0,CHAR,Trench"}' \
    http://localhost:5000/SASjsApi/stp/execute
  

  then check sasparams[0].NOBS, the row count and FILTER_TEXT. Pin those exact numbers in the spec.