diff --git a/cli/dependencies.mdx b/cli/dependencies.mdx index 4a9ac2ab..8f57a44e 100644 --- a/cli/dependencies.mdx +++ b/cli/dependencies.mdx @@ -1,43 +1,54 @@ --- -title: Using NPM packages and local dependencies -sidebarTitle: NPM & Local Dependencies +title: Using npm packages and local dependencies +sidebarTitle: npm & Local Dependencies --- -Checkly lets you use JavaScript / TypeScript in your [Browser](/detect/synthetic-monitoring/browser-checks/overview) and [Multistep](/detect/synthetic-monitoring/multistep-checks/overview) checks, [API check setup & teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown), and [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview). Checks are able to use NPM packages, as well as import local JavaScript and TypeScript files. +Checkly lets you use JavaScript and TypeScript in your [Browser](/detect/synthetic-monitoring/browser-checks/overview) and [Multistep](/detect/synthetic-monitoring/multistep-checks/overview) checks, [API check setup and teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown), and [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview). Checks can use npm packages and import local JavaScript and TypeScript files. -## NPM packages +How dependencies work depends on the check type: + +| Check type | Dependency model | Environment field | +|------------|------------------|-------------------| +| Browser Checks and Multistep Checks | Run in a Checkly runtime with fixed Checkly-provided dependencies | `runtimeId` | +| Playwright Check Suites | Install dependencies from your project files, including `package.json` and your lock file | `engine` | + +Use `runtimeId` to choose a custom Checkly runtime for Browser Checks and Multistep Checks. Use `engine` only for Playwright Check Suites, where it overrides the JavaScript engine version that runs your own Playwright project. + +## npm packages ### Browser, Multistep, and API Checks -Not all NPM packages from NPM are available inside the context of a Check. +Not all npm packages are available in a Checkly runtime. The JavaScript code for these check types executes in a runtime environment managed by Checkly. Runtime versions can be selected by setting a `runtimeId`. -This can be configured at the check and group level using constructs, and a default value for the project can be set in the [project configuration file](/constructs/project#param-checks-runtime-id). +You can configure `runtimeId` at the check and group level using constructs, and set a project default in the [project configuration file](/constructs/project#param-checks-runtime-id). -A runtime contains among others: +A runtime includes fixed dependencies such as: -- Nodejs v22+ +- Node.js 22+ - `@playwright/test 1.51.1` - `axios 0.28.0` - `lodash 4.17.21` - `moment 2.30.1` -...and a range of other popular NPM package to help you write and assert checks. +Runtimes also include other popular npm packages to help you write and assert checks. - [Browse the latest runtime specs](/platform/runtimes/runtime-specification) - [Learn more about runtimes](/platform/runtimes/overview) -- [Why can't I import any NPM package or other 3rd party dependencies?](/platform/runtimes/overview#why-can’t-i-import-any-npm-package-or-other-3rd-party-dependencies%3F) +- [Why can't I import any npm package or other third-party dependencies?](/platform/runtimes/overview) ### Playwright Check Suites -Playwright Check Suites don't use our predefined runtimes. Instead, you can install [custom dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies/), including private packages or packages from a custom registry. +Playwright Check Suites do not use Checkly runtimes. Instead, Checkly installs your project's dependencies from your `package.json` and lock file. This lets you use [custom dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies/), including private packages or packages from a custom registry. + +Use the `engine` field to override the JavaScript engine version for a Playwright Check Suite. `engine` does not select a Checkly runtime or a fixed package set. ## Local Dependencies -Your checks are also able to import other JavaScript and TypeScript files as dependencies. +Your checks can also import other JavaScript and TypeScript files as dependencies. This is useful for defining helper functions to be reused across multiple checks. -The Checkly CLI will automatically detect these dependencies and make sure that they're bundled as part of the check. +The Checkly CLI automatically detects these dependencies and bundles them with the check. No additional configuration is needed. Here is a [Browser Check](/detect/synthetic-monitoring/browser-checks/overview) example of how this works in practice. @@ -86,8 +97,7 @@ import { BrowserCheck } from 'checkly/constructs' new BrowserCheck('login-check', { name: 'Login Check', - code: { entrypoint: './login.spec.ts' } - }) + code: { entrypoint: './login.spec.ts' } }) ``` diff --git a/constructs/browser-check.mdx b/constructs/browser-check.mdx index 41e0319a..f42f47e4 100644 --- a/constructs/browser-check.mdx +++ b/constructs/browser-check.mdx @@ -243,6 +243,26 @@ new BrowserCheck("standard-check", { **Available frequencies**: `EVERY_1M`, `EVERY_2M`, `EVERY_5M`, `EVERY_10M`, `EVERY_15M`, `EVERY_30M`, `EVERY_1H`, `EVERY_2H`, `EVERY_6H`, `EVERY_12H`, `EVERY_24H` + + +The Checkly runtime version used to execute the Browser Check. Runtimes are managed execution environments for Browser and Multistep Checks. They include fixed Checkly-provided dependencies, such as Playwright, browser binaries, and runtime libraries. + +Use `runtimeId` for Browser Checks and Multistep Checks. For Playwright Check Suites, use [`engine`](/constructs/playwright-check#engine) instead to select the JavaScript engine version that runs your own Playwright project. + +**Usage:** + +```ts highlight={3} +new BrowserCheck("my-check", { + name: "My Browser Check", + runtimeId: "2025.04", + /* More options... */ +}) +``` + +Learn more about [Checkly runtimes in the general documentation](/platform/runtimes/overview). + + + Array of public location codes where the Browser Check should run. Multiple locations provide geographic coverage and redundancy. diff --git a/constructs/multistep-check.mdx b/constructs/multistep-check.mdx index ce8b40c0..cb49fe30 100644 --- a/constructs/multistep-check.mdx +++ b/constructs/multistep-check.mdx @@ -272,7 +272,9 @@ new MultiStepCheck("my-multistep", { -The ID of the runtime to use for executing the multistep check. Required to be `2023.09` or later for multistep check support. +The Checkly runtime version used to execute the Multistep Check. Runtimes are managed execution environments for Browser and Multistep Checks. They include fixed Checkly-provided dependencies, such as Playwright, browser binaries, and runtime libraries. + +Multistep checks require runtime `2023.09` or later. Usage: ```ts highlight={3} diff --git a/constructs/playwright-check.mdx b/constructs/playwright-check.mdx index f8c189e9..cc139269 100644 --- a/constructs/playwright-check.mdx +++ b/constructs/playwright-check.mdx @@ -36,18 +36,18 @@ new PlaywrightCheck("critical-e2e-monitor", { ``` ```ts Advanced Example -import { PlaywrightCheck } from "checkly/constructs" +import { Engine, PlaywrightCheck } from "checkly/constructs" new PlaywrightCheck("critical-e2e-monitor", { name: "Critical E2E Monitor", description: "Runs the **critical path** e2e suite against production.", - include: ['.npmrc','test-files/**'], + include: [".npmrc", "test-files/**"], playwrightConfigPath: "./playwright.config.ts", + engine: Engine.node("24"), // Optional: override the auto-detected engine. installCommand: "npm ci", testCommand: "npx playwright test --retries=2", pwProjects: ["chromium"], pwTags: ["e2e"], - }) ``` @@ -68,6 +68,7 @@ The Playwright Check Suite configuration consists of specific Playwright Check S | `pwProjects` | `string` `string[]` | ❌ | - | Specific Playwright projects to run from your configuration | | `pwTags` | `string` `string[]` | ❌ | - | Tags to filter which tests to run using Playwright's grep functionality | | `include` | `string` `string[]` | ❌ | - | File patterns to include when bundling the test project | +| `engine` | `Engine` | ❌ | Auto-detected, then Node.js 22 | JavaScript engine and version used to run the Playwright Check Suite | @@ -218,7 +219,7 @@ Defines the glob patterns for files and directories that should be included when new PlaywrightCheck("critical-e2e-monitor", { name: "Critical E2E Monitor", playwrightConfigPath: "../playwright.config.ts", - include: ['.npmrc','test-files/**'], + include: [".npmrc", "test-files/**"], }) ``` @@ -230,6 +231,55 @@ Use `include` to bundle files that are not directly imported/required. + + +The JavaScript engine and version used to run the Playwright Check Suite. Use the `Engine` helpers to select Node.js or Bun explicitly. + +**Usage:** + + + +```ts Node.js highlight={1,5} +import { Engine, PlaywrightCheck } from "checkly/constructs" + +new PlaywrightCheck("critical-e2e-monitor", { + name: "Critical E2E Monitor", + playwrightConfigPath: "../playwright.config.ts", + engine: Engine.node("24"), +}) +``` + +```ts Bun highlight={1,5} +import { Engine, PlaywrightCheck } from "checkly/constructs" + +new PlaywrightCheck("critical-e2e-monitor", { + name: "Critical E2E Monitor", + playwrightConfigPath: "../playwright.config.ts", + engine: Engine.bun("1.3"), +}) +``` + + + +If you omit `engine`, the Checkly CLI tries to detect it from project version files. It checks `.node-version`, `.nvmrc`, `.tool-versions` (`nodejs` or `bun`), `.bun-version`, and `package.json` `engines.node` or `engines.bun`. + +When both Node.js and Bun candidates are found, Node.js takes precedence. `.nvmrc` aliases such as `lts`, `lts/*`, `node`, `stable`, and `latest` are skipped. + +For `package.json` engine ranges, the CLI uses the minimum version from the semver range. For example, `>=22` resolves to Node.js `22`, and `>=1.3` resolves to Bun `1.3`. + +Detected and explicit versions are checked against Checkly's engine rules: + +| Engine | Supported versions | Resolution behavior | +|--------|--------------------|---------------------| +| Node.js | `22`, `24`, `26` | Older, EOL, non-LTS, or future major versions are remapped to the nearest supported LTS version with a warning | +| Bun | `1.3` | Older or future `1.x` versions are remapped to `1.3` with a warning; `2.x` and newer are rejected | + + +If no engine is set and the CLI cannot auto-detect one, Checkly uses the default Node.js 22 engine. + + + + ### General Check Options diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index 2eff2a76..a6533361 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -7,14 +7,14 @@ sidebarTitle: 'Custom Dependencies' Use the [Checkly CLI](/cli/) to turn your Playwright tests into globally distributed monitors. Checkly uses your existing `package.json` dependencies and Playwright configuration. -**Runtime Environment**: Playwright Check Suites run in a Node.js runtime containing your custom dependencies. See the [runtime specification](/platform/runtimes/runtime-specification) for further details. +Playwright Check Suites do not use Checkly runtimes. Browser Checks and Multistep Checks use `runtimeId` to select a managed runtime with fixed Checkly-provided dependencies. Playwright Check Suites install your project dependencies and use `engine` to select the JavaScript engine version. ## Using JavaScript/Node.js dependencies Checkly installs dependencies from your `package.json` and lock files. It works with [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/), and [pnpm](https://pnpm.io/). -By default, Checkly installs all dependencies (both `dependencies` and `devDependencies`). +By default, Checkly installs all dependencies (both `dependencies` and `devDependencies`). ```json package.json { @@ -33,15 +33,15 @@ Checkly detects your package manager from your lock file: | Lock file | Package manager | |---------------------|-----------------| | `package-lock.json` | npm | -| `pnpm-lock.yaml` | pnpm | -| `yarn.lock` | yarn | +| `pnpm-lock.yaml` | pnpm | +| `yarn.lock` | yarn | ### Workspace support Starting from [Checkly CLI 7.1.](https://github.com/checkly/checkly-cli/releases/tag/7.1.0), Checkly supports `npm` and `pnpm` workspaces in Playwright Check Suites, while Yarn workspaces remain unsupported. -If your Playwright tests are stored in a monorepo, Checkly automatically recognizes and manages dependencies based on your workspace configuration. -When using workspaces, packages in your workspace can depend on other packages in the same workspace, including those from the root package. Check out [pnpm workspaces docs](https://pnpm.io/workspaces)(https://pnpm.io/workspaces) or [npm workspaces docs](https://docs.npmjs.com/cli/v8/using-npm/workspaces) to get an overview on workspaces. +If your Playwright tests are stored in a monorepo, Checkly automatically recognizes and manages dependencies based on your workspace configuration. +When using workspaces, packages in your workspace can depend on other packages in the same workspace, including those from the root package. See the [pnpm workspaces docs](https://pnpm.io/workspaces) or [npm workspaces docs](https://docs.npmjs.com/cli/v8/using-npm/workspaces) to learn how workspaces work. **Requirements:** - Place your lock file (`package-lock.json` or `pnpm-lock.yaml`) at the workspace root @@ -251,4 +251,4 @@ If you encounter general installation errors: - Review the full error logs for specific issues - Ensure all dependencies are compatible with the Node.js version used by Checkly -- Consider using a custom `installCommand` to handle complex installations \ No newline at end of file +- Consider using a custom `installCommand` to handle complex installations diff --git a/platform/runtimes/overview.mdx b/platform/runtimes/overview.mdx index a89046a5..49bb885f 100644 --- a/platform/runtimes/overview.mdx +++ b/platform/runtimes/overview.mdx @@ -4,22 +4,24 @@ description: 'How Checkly runtimes work.' sidebarTitle: 'Overview' --- -Checkly allows you to use JavaScript code in your [Browser checks](/detect/synthetic-monitoring/browser-checks/overview), [MultiStep Checks](/detect/synthetic-monitoring/multistep-checks/overview) and in the optional [setup & teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown) you can add to your API checks. +Checkly lets you use JavaScript code in your [Browser checks](/detect/synthetic-monitoring/browser-checks/overview), [MultiStep Checks](/detect/synthetic-monitoring/multistep-checks/overview), and optional [setup and teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown) for API checks. -This JavaScript code executes in a runtime environment that is managed by Checkly. This environment has access to specific Node.js versions and NPM packages, like the "latest Playwright version on Node 14". We call these environments **runtimes**. +This JavaScript code executes in a runtime environment that is managed by Checkly. This environment includes a specific Node.js version, Playwright version, browser binaries, and selected npm packages. We call these managed environments **runtimes**. + +Playwright Check Suites use a different model. They do not use Checkly runtimes. They install your project dependencies from your `package.json` and lock file, and use `engine` to select the JavaScript engine version. ## Using runtimes -It's pretty easy. You don't have to do anything most of the time. +You do not have to configure runtimes for most checks. 1. View all the available runtimes on the [runtimes tab in the account section](https://app.checklyhq.com/settings/account/runtimes/). See the screenshot below. 2. There is always one runtime marked as **active**. This is the runtime all checks use, unless you decide to override this at the check or group level. -4. Runtimes have a simple `YYYY.MM` name, e.g. `2025.04` Newer dates hold newer dependencies. -3. Pick the runtime you want and click "Save settings". This runtime now applies to all of your checks and any new checks you create. +3. Runtimes have a simple `YYYY.MM` name, e.g. `2026.04`. Newer dates include newer dependencies. +4. Pick the runtime you want and click "Save settings". This runtime now applies to all of your checks and any new checks you create. ![runtimes](/images/docs/images/cli/account_runtimes.png) -Note that one runtime version, e.g. `2025.04` holds all dependencies for all check types. There is no separate runtime for different types of checks. +Note that one runtime version, e.g. `2026.04`, holds all runtime dependencies for all check types that use Checkly runtimes. There is no separate runtime for different types of checks. ## Overriding runtimes for specific checks @@ -31,7 +33,9 @@ You can: - Select a specific runtime in the "Setup & teardown" tab for each **API check**. - Select a specific runtime on the "Runtimes" tab for each **check group**. -> Overriding the global, account level runtime for a handful of checks is **the recommended way to check for any compatibility issues** before committing to a new, global runtime. Note the hierarchy: **check** runtime trumps **group** runtime trumps **global account** runtime. +Playwright Check Suites do not appear in this hierarchy because they use `engine`, not `runtimeId`. + +> Overriding the global, account-level runtime for a few checks is **the recommended way to check for compatibility issues** before committing to a new global runtime. Note the hierarchy: the **check** runtime takes precedence over the **group** runtime, which takes precedence over the **global account** runtime. ## How we update and release new runtimes @@ -61,4 +65,3 @@ NPM dependencies living in `node_modules`. 4. Our provided Runtime packages are tested with our sandboxing for extra runtime security. If you want to see a package included in the Checkly Runtime, [please add a post on our feedback board](https://feedback.checklyhq.com/) with a package name, and your use case. -