refactor: example projects [tra-1519]

examples/advanced-project-js/README.md

@@ -1,21 +1,52 @@
 # Checkly Monitoring-as-code: Advanced Project
 
-This example project shows how you can use the Checkly CLI in a monitoring as code (MaC) workflow. We are using the
-https://checklyhq.com website as a monitoring target.
+This example project shows how you can use the Checkly CLI in a monitoring as code (MaC) workflow.
 
-1. Write API Checks and Playwright-powered Browser Checks.
+1. Write API Checks and Playwright-powered Browser Checks or fully native Playwright Check Suites.
 2. Add Alert Channels, and dry-run your Checks on 20+ global locations.
 3. Test -> Deploy: now you have your app monitored around the clock. All from your code base.
 
 ```
-npm create checkly@latest -- --template advanced-project
+npm create checkly@latest -- --template advanced-project-js
 ```
 
 ## Project Structure
 
 This project has examples of all Checkly check types and showcases some advanced features. It also adds a GitHub Actions workflow.
 
-- Running `npx checkly pw-test` will use the `playwright.config.ts` file and run the test suite in Checkly.
+```
+.
+├── README.md
+├── .github
+│   └── workflow.yml
+├── src
+│   ├── __checks__
+│   │   ├── synthetics
+│   │   │   ├── 01-api.check.js
+│   │   │   ├── 02-business-critical.check.js
+│   │   │   ├── 03-browse-and-search.spec.js
+│   │   │   ├── 04-add-to-cart.spec.js
+│   │   │   ├── 05-multi-step-api.spec.js
+│   │   │   └── 06-multi-step-api.check.js
+│   │   ├── uptime
+│   │   │   ├── heartbeat.check.js
+│   │   │   ├── tcp.check.js
+│   │   │   └── url.check.js
+│   │   └── utils
+│   │       ├── alert-channels.js
+│   │       ├── auth-client.js
+│   │       ├── setup.js
+│   │       └── website-groups.check.js
+│   └── tests
+│       ├── login.setup.js
+│       └── webshop-interactions.spec.js
+├── checkly.config.js
+├── playwright.config.js
+├── package.json
+└── package-lock.json
+```
+
+- Running `npx checkly pw-test` will use the `playwright.config.js` file and run the test suite in Checkly.
 
 - Running `npx checkly test` will look for `.check.js` files and `.spec.js` in `__checks__` directories and execute them in a dry run.
 
@@ -53,5 +84,5 @@ npm install --save-dev @playwright/[email protected]
 
 ## Questions?
 
-Check [our CLI docs](https://www.checklyhq.com/docs/cli/), the [main Checkly docs](https://checklyhq.com/docs) or 
+Check [the Checkly CLI docs](https://www.checklyhq.com/docs/cli/), the [main Checkly docs](https://checklyhq.com/docs) or 
 join our [Slack community](https://checklyhq.com/slack).

examples/advanced-project-js/checkly.config.js

@@ -1,5 +1,5 @@
-const { defineConfig } = require('checkly');
-const { RetryStrategyBuilder } = require('checkly/constructs');
+const { defineConfig } = require('checkly')
+const { AlertEscalationBuilder, RetryStrategyBuilder } = require('checkly/constructs')
 
 /**
  * See https://www.checklyhq.com/docs/cli/project-structure/
@@ -27,9 +27,10 @@ const config = defineConfig({
     runtimeId: '2025.04',
     /* Failed check runs will be retried before triggering alerts */
     retryStrategy: RetryStrategyBuilder.fixedStrategy({ baseBackoffSeconds: 60, maxRetries: 4, sameRegion: true }),
+    alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1),
     /* A glob pattern that matches the Checks inside your repo, see https://www.checklyhq.com/docs/cli/using-check-test-match/ */
     checkMatch: '**/__checks__/**/*.check.js',
-    /* Global configuration option for Playwright-powered checks. See https://www.checklyhq.com/docs/browser-checks/playwright-test/#global-configuration */
+    /* Global configuration option for Browser and Multistep checks. See https://www.checklyhq.com/docs/browser-checks/playwright-test/#global-configuration */
     playwrightConfig: {
       timeout: 30000,
       use: {
@@ -39,10 +40,11 @@ const config = defineConfig({
     },
     browserChecks: {
       /* A glob pattern matches any Playwright .spec.js files and automagically creates a Browser Check. This way, you
-       * can just write native Playwright code. See https://www.checklyhq.com/docs/cli/using-check-test-match/
+       * can just write Playwright code. See https://www.checklyhq.com/docs/constructs/including-checks/#browserchecks-testmatch
        * */
       testMatch: '**/__checks__/**/*.spec.js',
     },
+    // Playwright Check Suites definition, run the whole Playwright Test Suite in a Check
     playwrightConfigPath: './playwright.config.js',
     playwrightChecks: [
       {
@@ -60,6 +62,6 @@ const config = defineConfig({
     /* How many times to retry a failing test run when running `npx checkly test` or `npx checkly trigger` (max. 3) */
     retries: 0,
   },
-});
+})
 
-module.exports = config;
+module.exports = config

examples/advanced-project-js/package.json

@@ -12,6 +12,7 @@
   "devDependencies": {
     "@playwright/test": "^1",
     "checkly": "latest",
-    "jiti": "^1"
+    "jiti": "^2",
+    "dotenv": "^16.0.0"
   }
 }

examples/advanced-project-js/playwright.config.js

@@ -1,18 +1,30 @@
-const { defineConfig, devices } = require('@playwright/test');
-const path = require('path');
+const { defineConfig, devices } = require('@playwright/test')
 
-const AUTH_FILE = '.auth/user.json';
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+const dotenv = require('dotenv')
+const path = require('path')
+dotenv.config({ path: path.resolve(__dirname, '.env') })
 
-const config = defineConfig({
+const AUTH_FILE = '.auth/user.json'
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+
+module.exports = defineConfig({
   timeout: 30000,
   use: {
     baseURL: 'https://www.danube-web.shop',
     viewport: { width: 1280, height: 720 },
+    trace: 'on',
   },
   projects: [
     {
       name: 'login-setup',
-      testMatch: /.*\.setup.ts/,
+      testMatch: /.*\.setup.js/,
       use: {
         ...devices['Desktop Chrome'],
       },
@@ -24,7 +36,7 @@ const config = defineConfig({
         ...devices['Desktop Firefox'],
         storageState: path.resolve(__dirname, AUTH_FILE),
       },
-      dependencies: ["login-setup"],
+      dependencies: ['login-setup'],
     },
     {
       name: 'Chromium',
@@ -38,6 +50,4 @@ const config = defineConfig({
       dependencies: ['login-setup'],
     },
   ]
-});
-
-module.exports = config;
+})

examples/advanced-project-js/src/__checks__/synthetics/01-api.check.js

@@ -0,0 +1,30 @@
+const path = require('path')
+const { ApiCheck, AssertionBuilder } = require('checkly/constructs')
+const { syntheticGroup } = require('../utils/website-groups.check')
+
+// API checks send an HTTP request to a URL endpoint and validate the response. Read more at:
+// https://www.checklyhq.com/docs/api-checks/
+
+new ApiCheck('books-api-check-1', {
+  name: 'Books API',
+  degradedResponseTime: 10000, // milliseconds
+  maxResponseTime: 20000,
+  setupScript: {
+    // API checks can run arbitrary JS/TS code before or after a check. 
+    entrypoint: path.join(__dirname, '../utils/setup.js')
+  },
+  group: syntheticGroup,
+  request: {
+    url: 'https://danube-web.shop/api/books',
+    method: 'GET',
+    followRedirects: true,
+    skipSSL: false,
+    assertions: [   
+      AssertionBuilder.statusCode().equals(200),
+      AssertionBuilder.headers('content-type').equals('application/json; charset=utf-8'),      
+      AssertionBuilder.jsonBody('$[0].id').isNotNull(),
+      AssertionBuilder.jsonBody('$[0].author').equals('Fric Eromm'),
+    ],
+  },
+  runParallel: true,
+})

examples/advanced-project-js/src/__checks__/synthetics/02-business-critical.check.js

@@ -0,0 +1,25 @@
+const path = require('path')
+const { BrowserCheck } = require('checkly/constructs')
+const { syntheticGroup } = require('../utils/website-groups.check')
+
+// Configures two checks for our homepage in a single configuration file.
+// Most settings for these checks are defined in the check group,
+// in /utils/website-groups.check.ts
+
+new BrowserCheck('browse-and-search-check', {
+  name: 'Browse and search',
+  group: syntheticGroup,
+  code: {
+    entrypoint: path.join(__dirname, '03-browse-and-search.spec.js')
+  },
+  runParallel: true,
+})
+
+new BrowserCheck('login-browser-check', {
+  name: 'Add to cart flow',
+  group: syntheticGroup,
+  code: {
+    entrypoint: path.join(__dirname, '04-add-to-cart.spec.js')
+  },
+  runParallel: true,
+})

examples/advanced-project-js/src/__checks__/synthetics/03-browse-and-search.spec.js

@@ -0,0 +1,22 @@
+const { test, expect } = require('@playwright/test')
+
+// Source code for a browser check using Playwright Test. Find more Playwright information at 
+// https://www.checklyhq.com/learn/playwright/ 
+
+// This environment variable is set in the group configuration in /utils/website-groups.check.ts
+const searchString = process.env.AUTHOR_NAME || "Herman Moulson"
+
+test('Browse and search for a book', async ({ page }) => {
+  // The baseURL can be set in the playwrightConfig of your Checkly config
+  await page.goto('/')
+  await expect(page.getByRole('heading', { name: 'SPECIAL OFFER: 20% OFF BOOKS' })).toBeVisible()
+
+  // Navigate to Fantasy category and verify a book is visible
+  await page.locator('a', { hasText: 'Fantasy' }).click()
+  await expect(page.getByText('The Pickled Lynx')).toBeVisible()
+
+  // Use the search bar to search for an author and verify a book is visible
+  await page.getByRole('textbox').fill(searchString)
+  await page.getByRole('button', { name: 'Search' }).click()
+  await expect(page.getByText('Haben oder haben')).toBeVisible()
+})