@globisnv/cypress-core

中文文档
2.8.0发布于 2026/11/16UNLICENSEDTypeScriptES Module近 30 天下载 5128

Core building blocks for Globis Cypress E2E tests

原始使用文档
文档目录18 节
  1. Installation
  2. Compatibility with Globis Online
  3. Cutting a release
  4. Setting up a new customer repo
  5. Usage
  6. 1. cypress.config.ts
  7. 2. cypress/support/e2e.ts
  8. 3. Blueprints, commands and helpers
  9. What's in the box
  10. Command families
  11. Blueprints
  12. WebSocket detector
  13. Metrics
  14. Environment variables
  15. Development
  16. Shipped lint plugins
  17. Conventions
  18. Review ownership

@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:

BumpWhen
majorA globis-online release broke this package's support floor — bump globisOnline.minVersion (and this table) too
minorA new command / blueprint / API surface, backwards compatible
patchBugfixes only

See Cutting a release for how a bump actually gets published.

Core versionMinimum globis-online version
2.0.011.0.3
0.0.111.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.

  1. Actions → Prepare Release → Run workflow, pick patch / minor / major. It bumps package.json, renames the ## Unreleased heading in CHANGELOG.md to ## X.Y.Z and opens a fresh empty ## Unreleased above it, and opens a chore(release): vX.Y.Z PR. Nothing is published yet.
  2. 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 starter cypress/e2e/<abbrev>/template.cy.ts.example.
  • Runs git init and npm 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.env key is copied to config.expose except 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), bufferWsMetrics and flushWsMetrics.
  • Browser sizing — a before:browser:launch hook forcing 1920×1080 and --force-device-scale-factor=1 for 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:

SubpathContents
.defineGlobisConfig only — safe to import from cypress.config.ts
./registerSide-effect import that registers all commands
./configThe config factory on its own
./tsHelperConstants, branded flags and helper functions
./typesAmbient/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 inside node_modules — they typecheck but fail to bundle. Real package subpath exports resolve correctly in both tsc and webpack.

tsHelper is deliberately not re-exported from the package root. Its top-level Cypress.expose(...) call only works in a browser-context (spec/support) process — cypress.config.ts runs in Node, so the root import (.) has to stay safe to use there. Always import tsHelper via @globisnv/cypress-core/tsHelper explicitly.


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.

PrefixSolutionCommands
GLO_Globis Online (the main Servoy client)79
FOB_Form Builder17
GLT_GlobTake (/solution/globtake)11
POR_Portal10
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 with window.WebSocket patched so every frame is mirrored into win.wsMessages.
  • WS_loadingCheck(options?) — resolves only once pending requests, the Sablo loading indicator, pending svyPush data syncs, and the DOM loading indicator are all idle for a quiet period. Handles dialogs, popup forms, closeNode/cellClick bursts, window destroy and navigation.
  • WS_toggleDialogHandler('enable' | 'disable') — controls whether plain Info dialogs 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.

KeyPurpose
globisUrlBase solution URL. GLJ/GLS/GLT_login rewrite the /solution/<name> segment off this.
portalUrl, formBuilderUrl, ssoUrlEntry 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, username2Default and alternate login users.
password, password2, api_key, otpSecretSecrets — 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, saveDataLogin/flow switches read by the commands.
BUILD_NUMBERUsed by getOrCreateUuid() to build a stable CYP<build> test-data prefix.
extraParamsObject of Jenkins-passed extras; cypressWebsocketLoader and cypressWebsocketDebug ('true') live here.
AMP_REMOTE_WRITE_URL, AMP_REGIONNode process.env — Prometheus remote-write target and region.
numTestsKeptInMemoryNode 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.

PluginWhat it does
noUnnecessaryWaiting.gritFails 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 .js extension.
  • Commands are declared on Cypress.Chainable inside a declare global block 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 than true/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.

版本与发布记录

@globisnv/cypress-core 共发布 37 个版本,首次发布于 2026/08/14;过去 12 个月发布了 37 个版本。

版本发布日期距今
2.8.0latest2026/11/16今天
1.2.1release-1.x2026/11/16今天
2.7.22026/11/133 天前
2.7.12026/11/133 天前
2.7.02026/11/133 天前
2.6.02026/11/124 天前

关于 @globisnv/cypress-core 的常见问题

@globisnv/cypress-core 是什么?

Core building blocks for Globis Cypress E2E tests

如何安装 @globisnv/cypress-core?

在项目目录运行 npm install @globisnv/cypress-core,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:cypress(^16.0.0)、cypress-real-events(^1.15.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 create-globis-customer-repo,可以用 npx create-globis-customer-repo 直接运行。

@globisnv/cypress-core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@globisnv/cypress-core 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@globisnv/cypress-core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^22.0.0 || ^24.0.0 || >=26.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@globisnv/cypress-core 可以商用吗?

@globisnv/cypress-core 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@globisnv/cypress-core 的下载量有多少?

根据 npm 官方下载统计,@globisnv/cypress-core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,128 次,日均约 171 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@globisnv/cypress-core 还在维护吗?

最新版本 2.8.0 发布于 2026/11/16(今天);至今共发布 37 个版本,其中过去 12 个月发布了 37 个;首次发布于 2026/08/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。