@globisnv/cypress-core
Core building blocks for Globis Cypress E2E tests.
This package holds everything that is not customer-specific: the shared Cypress config factory, the custom command library for the Servoy-based Globis solutions, the WebSocket-aware loading detector, the reusable data-entry blueprints, and the lint plugins. Customer repos install it, call defineGlobisConfig() in their cypress.config.ts, import @globisnv/cypress-core/register in their support file, and only keep their own specs and customer-specific commands locally.
Installation
npm install @globisnv/cypress-core
Peer dependencies (must be installed in the consumer repo) — see peerDependencies in package.json for the exact supported ranges.
Compatibility with Globis Online
Core's own version is plain semver, deliberately not tied to globis-online's version numbers — the two release on independent schedules, and forcing them to share digits would mean bumping core every time globis-online ships a release that doesn't touch anything core depends on.
Instead, each core release declares the minimum globis-online version it requires — a floor, not a pin. Blueprints and commands are written against a given release's Servoy DOM/behavior; they keep working on every later globis-online release until one of them actually changes something a blueprint depends on, at which point core needs a new version anyway, with its floor bumped to that release. There's no meaningful upper bound to declare in advance — you only find out a version broke something by running against it.
What each part of the version bump means:
| Bump | When |
|---|---|
| major | A globis-online release broke this package's support floor — bump globisOnline.minVersion (and this table) too |
| minor | A new command / blueprint / API surface, backwards compatible |
| patch | Bugfixes only |
See Cutting a release for how a bump actually gets published.
| Core version | Minimum globis-online version |
|---|---|
2.0.0 | 11.0.3 |
0.0.1 | 11.0.2 |
The floor is recorded in package.json under globisOnline.minVersion (machine-readable, in case tooling wants to check it later) and here in this table (human-readable, updated on every release alongside CHANGELOG.md). globis-cypress stays pinned to the latest core version — since it's Globis's own suite, it's the first thing to catch a globis-online release breaking something, before any customer repo would.
Cutting a release
A release is two phases, because the develop ruleset requires a reviewed PR — so the version bump takes the same route as every other change instead of CI trying to push past the ruleset.
- Actions → Prepare Release → Run workflow, pick
patch/minor/major. It bumpspackage.json, renames the## Unreleasedheading inCHANGELOG.mdto## X.Y.Zand opens a fresh empty## Unreleasedabove it, and opens achore(release): vX.Y.ZPR. Nothing is published yet. - Check the changelog section on that PR (it becomes the GitHub Release notes) and merge it yourself. Publish then builds, lints, publishes to npm, and creates the tag and GitHub Release.
Release PRs are deliberately left out of the auto-merge that every other PR gets. A merge performed by GITHUB_TOKEN creates no workflow run, so an auto-merged release PR would land the version in git and never publish it. If that ever happens anyway, run Actions → Publish → Run workflow and give it the release PR's number to finish the release. It publishes that PR's merge commit — not whatever the run was started from — so a recovery still ships exactly the tree that was reviewed, and it refuses a PR that is not a merged release/* into develop.
Write changelog entries under the ## Unreleased heading as you merge work, rather than at release time — the release just renames that heading and opens a new one, so there is always a section at the top to write into and the file never needs reorganising by hand. If there is no ## Unreleased section when you cut a release, the workflow adds an empty ## X.Y.Z stub and warns, and you fill it in on the PR.
Publishing uses npm trusted publishing over OIDC, so there is no NPM_TOKEN and no PAT anywhere in the release path — the publish job's only write scope is the tag and release it creates. The trusted publisher on npm must name publish.yml as the workflow. npm provenance stays off: it isn't supported from a private repository.
Because the bump lands in git before anything reaches npm, a failed publish never leaves the registry ahead of the repository — re-running the workflow after a fix picks up where it left off, and a version already on npm is skipped rather than retried.
Setting up a new customer repo
Starting a brand-new customer test repo from a blank slate — no manual copy-pasting from an existing one:
npx -p @globisnv/cypress-core create-globis-customer-repo
It asks two questions — a target folder (e.g. acme-cypress) and the customer's 3-letter abbreviation (e.g. ACM) — then:
- Copies a minimal template into that folder:
package.json,tsconfig.json,biome.json,cypress.config.ts,cypress.env.json.example,CODEOWNERS,.gitignore,cypress/support/{e2e.ts,record.ts}, and a startercypress/e2e/<abbrev>/template.cy.ts.example. - Runs
git initandnpm install.
The generated repo has fresh history (nothing cloned or filtered from any other repo) and depends on @globisnv/cypress-core like any other consumer — no local customer commands or blueprints are pre-populated, so it can never leak another customer's code. From there:
cd acme-cypress
cp cypress.env.json.example cypress.env.json # fill in your credentials
npx cypress open --e2e --browser chrome
Usage
1. cypress.config.ts
import { defineGlobisConfig } from '@globisnv/cypress-core/config';
export default defineGlobisConfig({
// Scalar e2e overrides — merged over the core defaults
e2e: {
specPattern: 'cypress/e2e/**/*.cy.ts',
defaultCommandTimeout: 20000,
// Optional: runs *after* the core wiring, on the same `on`/`config`
setupNodeEvents(on, config) {
// customer-specific node events
}
},
// Optional: extra cy.task() handlers alongside the core ones
extraTasks: {
myTask(arg) {
return null;
}
}
});
defineGlobisConfig() (src/config.ts) sets the shared defaults — 1920×1080 viewport, video on without compression, a 120s response timeout, experimentalMemoryManagement, scrollBehavior: 'center' — and wires:
- Env exposure — every
config.envkey is copied toconfig.exposeexcept the sensitive ones (password,password2,api_key,QLIKURLS,S3_KEY,S3_SECRET), which stay node-side. - Core tasks —
log,set,get(a process-scoped key/value store shared across specs),bufferWsMetricsandflushWsMetrics. - Browser sizing — a
before:browser:launchhook forcing 1920×1080 and--force-device-scale-factor=1for headless Chrome, plus Firefox/Electron equivalents.
2. cypress/support/e2e.ts
import '@globisnv/cypress-core/register';
// Customer-specific commands stay local:
import './commands/ACME_commands';
src/register.ts imports all generic command files, the WebSocket detector, and cypress-real-events. It also registers a beforeEach + Cypress.on('fail') pair that flags a failed test through the set/get task, so cleanup commands like GLO_closeDashboard can bail out instead of masking the real error with a secondary failure in the cloud report.
3. Blueprints, commands and helpers
Blueprints and generic command files are not re-exported from the package root — import them via their subpath:
import { GLO_enterEquipment, type objEquipment } from '@globisnv/cypress-core/blueprints/GLO_equipment';
import { getUUID, getDate, open, close, check } from '@globisnv/cypress-core/tsHelper';
import { createRequestVariables } from '@globisnv/cypress-core/apiMethods/IGS_request';
Available subpaths:
| Subpath | Contents |
|---|---|
. | defineGlobisConfig only — safe to import from cypress.config.ts |
./register | Side-effect import that registers all commands |
./config | The config factory on its own |
./tsHelper | Constants, branded flags and helper functions |
./types | Ambient/global type declarations |
./blueprints/* | Per-program data-entry blueprints |
./commands/* | Individual command files |
./apiMethods/* | REST request/response helpers |
Do not try to reach these through custom tsconfig path aliases pointing into
node_modules.tsconfig-paths-webpack-plugin(which Cypress's default preprocessor uses) silently ignores mappings that resolve insidenode_modules— they typecheck but fail to bundle. Real package subpath exports resolve correctly in bothtscand webpack.
tsHelperis deliberately not re-exported from the package root. Its top-levelCypress.expose(...)call only works in a browser-context (spec/support) process —cypress.config.tsruns in Node, so the root import (.) has to stay safe to use there. Always importtsHelpervia@globisnv/cypress-core/tsHelperexplicitly.
What's in the box
src/
├── config.ts # defineGlobisConfig() — the shared cypress.config factory
├── register.ts # side-effect entrypoint: loads all generic commands
├── index.ts # public API (config factory + tsHelper re-export)
├── tsHelper.ts # constants, branded boolean flags, date/UUID/number helpers, cleanup formulas
├── types.ts # global ambient types (selectors, dialogs, WebSocket protocol, extended filters)
├── websocketDetector.ts # WebSocket spy + WS_loadingCheck state machine
├── blueprints/ # 132 per-program data-entry blueprints
├── commands/ # 6 generic command files (~128 custom commands)
├── apiMethods/ # IGS REST request/response helpers
└── plugins/ # prometheusWriter — SigV4-signed remote write to AWS AMP
biome-plugins/ # GritQL lint rules (shipped to consumers)
Command families
Each command file targets one Globis solution. All are loaded by register.ts.
| Prefix | Solution | Commands |
|---|---|---|
GLO_ | Globis Online (the main Servoy client) | 79 |
FOB_ | Form Builder | 17 |
GLT_ | GlobTake (/solution/globtake) | 11 |
POR_ | Portal | 10 |
GLS_ | GlobScan (/solution/globscan) | 8 |
GLJ_ | GlobJob (/solution/globjob) | 3 |
WS_ | WebSocket helpers (from websocketDetector.ts) | 3 |
GLO_commands.ts is the backbone: login/logout and company/user switching, element lookup (GLO_getElement), input/date/checkbox/radio entry, grid interaction (select, sort, filter, row lookup, custom views), dialog handling, datacontrol buttons, extended filters, file upload/read, and value storage between steps. Every command carries a JSDoc block with its parameters — that is the reference documentation.
Blueprints
A blueprint is a typed object plus a function that fills in one program's detail form. For example GLO_equipment.ts exports objEquipment and GLO_enterEquipment(obj, tabName?), which walks the fields with cy.GLO_addInput, cy.GLO_checkbox, cy.GLO_popupWindow, and delegates nested blocks to other blueprints (GLO_enterAddressPopup). Specs then read as data, not as clicks:
GLO_enterEquipment({
equipmentCode: `CYP-${getUUID(4)}`,
equipmentCategory: 'Trailer',
flagIsActive: check
});
131 blueprints cover Globis Online programs (articles, contracts, transport orders, invoices, consignments, warehouse, customs, …) and 1 covers GlobTake.
WebSocket detector
Servoy's frontend talks to its backend over a single persistent WebSocket, which cy.intercept() cannot observe — historically that meant cy.wait(N). websocketDetector.ts replaces those with a semantics-aware idle check:
WS_visitWithSpy(url)— visits a URL withwindow.WebSocketpatched so every frame is mirrored intowin.wsMessages.WS_loadingCheck(options?)— resolves only once pending requests, the Sablo loading indicator, pendingsvyPushdata syncs, and the DOM loading indicator are all idle for a quiet period. Handles dialogs, popup forms,closeNode/cellClickbursts, window destroy and navigation.WS_toggleDialogHandler('enable' | 'disable')— controls whether plainInfodialogs are auto-dismissed or left to the test.
It is opt-in per run: cypressWebsocketLoader / cypressWebsocketDebug are read from the extraParams env object (see below).
Metrics
WS_loadingCheck can emit per-action timing metrics. They are buffered in-memory through the bufferWsMetrics task and pushed by flushWsMetrics, which SigV4-signs a Snappy-compressed Prometheus remote-write payload with container IMDS credentials (src/plugins/prometheusWriter.ts). The flush is a no-op unless AMP_REMOTE_WRITE_URL is set, so consumer repos without an AMP endpoint simply never push.
Environment variables
Set via Cypress env (config.env, CYPRESS_*, or --env) unless noted.
| Key | Purpose |
|---|---|
globisUrl | Base solution URL. GLJ/GLS/GLT_login rewrite the /solution/<name> segment off this. |
portalUrl, formBuilderUrl, ssoUrl | Entry URLs for the portal, form builder and Okta login flows (ssoUrl was oktaUrl). With loginType: sso the provider follows from it: Okta when it contains okta, otherwise Keycloak (default https://auth.globis.cloud). |
username, username2 | Default and alternate login users. |
password, password2, api_key, otpSecret | Secrets — kept node-side, never exposed to the browser. otpSecret is the base32 TOTP secret for Keycloak users with OTP. |
loginType (default/servoy/sso), ownerName, formBuilderStandalone, saveData | Login/flow switches read by the commands. |
BUILD_NUMBER | Used by getOrCreateUuid() to build a stable CYP<build> test-data prefix. |
extraParams | Object of Jenkins-passed extras; cypressWebsocketLoader and cypressWebsocketDebug ('true') live here. |
AMP_REMOTE_WRITE_URL, AMP_REGION | Node process.env — Prometheus remote-write target and region. |
numTestsKeptInMemory | Node process.env — overrides Cypress's default of 0. |
Development
npm run build # tsc -p tsconfig.build.json → dist/
npm run build:watch # incremental build for local linking
npm run typescript # tsc --noEmit --skipLibCheck
npm run lint # biome check .
npm run lint:fix # biome check . --write
Formatting is Biome (biome.json): 4-space indent, single quotes, semicolons, no trailing commas, 180-column lines, LF endings. src/biome.json extends it for src/ only: it enables noUnnecessaryWaiting there and disables noUnusedVariables for types.ts, which is declaration-only. It lives in src/ because consumers extends the root biome.json, and a plugin path in there would resolve against their repo.
Shipped lint plugins
biome-plugins/ is published with the package so consumer repos run the same rules over their specs as Biome GritQL plugins. Their diagnostics show up in biome check, the editor and the CI linter like any built-in rule.
| Plugin | What it does |
|---|---|
| noUnnecessaryWaiting.grit | Fails on cy.wait(<number>), including numeric constants/default params declared in an enclosing scope. Exempt a call with // biome-ignore lint/plugin/noUnnecessaryWaiting: <reason> on the line above. |
Wire it into the consumer repo's biome.json (the template already does). Biome resolves plugin paths from the consumer's root, not from an extends-ed config, so the path can't live in this package's biome.json:
{
"extends": ["./node_modules/@globisnv/cypress-core/biome.json"],
"plugins": ["./node_modules/@globisnv/cypress-core/biome-plugins/noUnnecessaryWaiting.grit"]
}
check-deprecated-get-commands.mjs (the old-positional-API-to-tuple-form codemod) is not shipped here — it lives in globis-cypress's own scripts/. It only matters for that repo's older version branches (11.0.1, 11.0.0, 10.5.19), which never adopted the tuple-based API and never will; no customer repo has ever had the old API, so there's nothing for it to do there.
Conventions
- ESM only (
"type": "module") — internal imports carry the.jsextension. - Commands are declared on
Cypress.Chainableinside adeclare globalblock in the file that implements them, with JSDoc on every parameter. - Boolean arguments use the branded flag constants from
tsHelper.ts(open/close,check/unCheck,skipCheck/noSkipCheck, …) so a call site reads as intent rather thantrue/false. - New generic commands, blueprints and helpers belong here; anything customer-specific stays in the consumer repo.
Review ownership
CODEOWNERS protects the shared surface — package.json, tsconfig*.json, biome.json, src/config.ts, src/register.ts, src/commands/, src/plugins/ and .github/. Changes there need a review from the listed owners.