Samples for synthetic monitors

Preconfigured templates and sample code let you build synthetic monitors in Node.js and TypeScript using frameworks such as Puppeteer, Selenium WebDriver, and Mocha. You can use these samples—available in the synthetics-sdk-nodejs GitHub repository—to query URLs, run browser-based user journeys, test API endpoints, or check for broken links.

Guidelines for using samples and writing custom tests

Before you deploy a sample or write a custom test, review the following requirements:

Update the target URL: Before you deploy any sample code, update the url field to point to your target endpoint. Don't set this field to https://www.google.com.
Throw an Error on test failure: If you write custom tests instead of using a template, ensure that your test passes unless an Error is thrown. We recommend that you use the Assert library so that any failures are attributed to the correct line of code.

Generic templates

The generic templates are configured to collect trace and log data for outbound HTTP requests. The solution leverages the OpenTelemetry auto-instrumentation-node module and the winston logger. Due to the dependency on open source products, you should expect changes in the structure of trace and log data. Therefore, the collected trace and log data should be used only for debugging purposes.

You can implement your own approach to collect trace and log data for outbound HTTP requests. For an example of a custom approach, see the class SyntheticAutoInstrumentation.

Generic Node.js sample

The generic-synthetic-nodejs sample illustrates how to query a URL. This sample contains the same code as the default function displayed by the Google Cloud console. To view the full sample, in the sample's toolbar, select the GitHub logo.

const { instantiateAutoInstrumentation, runSyntheticHandler } = require('@google-cloud/synthetics-sdk-api');
// Run instantiateAutoInstrumentation before any other code runs, to get automatic logs and traces
instantiateAutoInstrumentation();
const functions = require('@google-cloud/functions-framework');
const axios = require('axios');
const assert = require('node:assert');

functions.http('SyntheticFunction', runSyntheticHandler(async ({logger, executionId}) => {
  /*
   * This function executes the synthetic code for testing purposes.
   * If the code runs without errors, the synthetic test is considered successful.
   * If an error is thrown during execution, the synthetic test is considered failed.
   */
  logger.info('Making an http request using synthetics, with execution id: ' + executionId);
  const url = 'https://www.google.com/'; // URL to send the request to
  return await assert.doesNotReject(axios.get(url));
}));

TypeScript sample

The generic-synthetic-typescript sample illustrates how to query a URL. To view the full sample, in the sample's toolbar, select the GitHub logo.

import {runSyntheticHandler, instantiateAutoInstrumentation} from '@google-cloud/synthetics-sdk-api'
// Run instantiateAutoInstrumentation before any other code runs, to get automatic logs and traces
instantiateAutoInstrumentation();
import * as ff from '@google-cloud/functions-framework';
import axios from 'axios';
import assert from 'node:assert';
import {Logger} from 'winston';

ff.http('SyntheticFunction', runSyntheticHandler(async ({logger, executionId}: {logger: Logger, executionId: string|undefined}) => {
  /*
   * This function executes the synthetic code for testing purposes.
   * If the code runs without errors, the synthetic test is considered successful.
   * If an error is thrown during execution, the synthetic test is considered failed.
   */
  logger.info('Making an http request using synthetics, with execution id: ' + executionId);
  const url = 'https://www.google.com/'; // URL to send the request to
  return await assert.doesNotReject(axios.get(url));
}));

Puppeteer template

If you use Puppeteer, then consider starting with the generic-puppeteer-nodejs sample.

Required Puppeteer setup

To use Puppeteer, ensure that you complete the following steps:

Include .puppeteerrc.cjs in the source directory of your Cloud Run function:

const { join } = require('path');

/**
 * @type {import("puppeteer").Configuration}
 */
module.exports = {
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};

Add the following script to the package.json file of your Cloud Run function:

"scripts": {
     "gcp-build": "node node_modules/puppeteer/install.mjs"
},

Puppeteer sample

The generic-puppeteer-nodejs sample illustrates how to use Puppeteer with your Cloud Run function. To view the full sample, in the sample's toolbar, select the GitHub logo.

const { instantiateAutoInstrumentation, runSyntheticHandler } = require('@google-cloud/synthetics-sdk-api');
// Run instantiateAutoInstrumentation before any other code runs, to get automatic logs and traces
instantiateAutoInstrumentation();
const functions = require('@google-cloud/functions-framework');
const axios = require('axios');
const assert = require('node:assert');
const puppeteer = require('puppeteer');


functions.http('CustomPuppeteerSynthetic', runSyntheticHandler(async ({logger, executionId}) => {
 /*
  * This function executes the synthetic code for testing purposes.
  * If the code runs without errors, the synthetic test is considered successful.
  * If an error is thrown during execution, the synthetic test is considered failed.
  */

 // Launch a headless Chrome browser and open a new page
 const browser = await puppeteer.launch({ headless: 'new', timeout: 0});
 const page = await browser.newPage();

 // Navigate to the target URL
 const result = await page.goto('https://www.example.com', {waitUntil: 'load'});

 // Confirm successful navigation
 await assert.equal(result.status(), 200);

 // Print the page title to the console
 const title = await page.title();
 logger.info(`My Page title: ${title} ` + executionId);

 // Close the browser
 await browser.close();
}));

Selenium WebDriver template

If you use Selenium WebDriver, then consider starting with the generic-selenium-nodejs sample. The sample, which is available on GitHub, includes index.js and package.json files.

To view the full sample, in the sample's toolbar, select the GitHub logo.

const {
  instantiateAutoInstrumentation,
  runSyntheticHandler,
} = require('@google-cloud/synthetics-sdk-api');
// Run instantiateAutoInstrumentation before any other code runs, to get automatic logs and traces
instantiateAutoInstrumentation();
const functions = require('@google-cloud/functions-framework');
const assert = require('node:assert');

const { Builder, Browser, By } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');

/*
 * This function executes the synthetic code for testing purposes.
 * If the code runs without errors, the synthetic test is considered successful.
 * If an error is thrown during execution, the synthetic test is considered failed.
 */
functions.http(
  'CustomSeleniumSynthetic',
  runSyntheticHandler(async ({ logger, executionId }) => {
    /*
     * Construct chrome options
     * Note: `setChromeBinaryPath` must be set to '/srv/bin/chromium' when running in
     *   GCF (but will need to be changed if running on local machine).
     */
    const options = new chrome.Options();
    options.setChromeBinaryPath('/srv/bin/chromium');
    options.addArguments('--headless', '--disable-gpu', '--no-sandbox');

    // Launch headless chrome webdriver with options
    const driver = await new Builder()
      .forBrowser(Browser.CHROME)
      .setChromeOptions(options)
      .build();

    // Navigate to the target URL
    await driver.get('https://example.com');

    // Retrieve title and `a` tag of page
    const title = await driver.getTitle();
    const aTag = await driver.findElement(By.css('a')).getText();

    // assert title is as expected and print to console
    await assert.equal(title, 'Example Domain');
    logger.info(`My URL title is: ${title} ` + executionId);

    await driver.quit();
  })
);

Mocha template

If you write tests that rely on the Mocha template, then consider whether a sequence of tests should continue or stop when a failure occurs. To stop a sequence of tests after a failure, you must set the bail flag.

For an end-to-end example that includes deploying an API, writing a sample Mocha test suite for the API endpoints, and configuring the synthetic monitor, see the blog Google Cloud Synthetic Monitoring Tutorial.

The mocha-url-ok sample illustrates how a Cloud Run function can invoke a Mocha test suite, and it provides a sample test suite. To view the full sample, in the sample's toolbar, select the GitHub logo.


const functions = require('@google-cloud/functions-framework');
const GcmSynthetics = require('@google-cloud/synthetics-sdk-mocha');

/*
 * This is the server template that is required to run a synthetic monitor in
 * Google Cloud Functions.
 */

functions.http('SyntheticMochaSuite', GcmSynthetics.runMochaHandler({
  spec: `${__dirname}/mocha_tests.spec.js`
}));


/*
 * This is the file may be interacted with to author mocha tests. To interact
 * with other GCP products or services, users should add dependencies to the
 * package.json file, and require those dependencies here A few examples:
 *  - @google-cloud/secret-manager:
 *        https://www.npmjs.com/package/@google-cloud/secret-manager
 *  - @google-cloud/spanner: https://www.npmjs.com/package/@google-cloud/spanner
 *  - Supertest: https://www.npmjs.com/package/supertest
 */

const {expect} = require('chai');
const fetch = require('node-fetch');

it('pings my website', async () => {
  const url = 'https://google.com/'; // URL to send the request to
  const externalRes = await fetch(url);
  expect(externalRes.ok).to.be.true;
});

Broken-link template

The broken-links-ok sample illustrates how to configure a broken-link checker. For this template, you only specify the values of the options object. This object specifies the URI to be tested and the parameters of the test.

If you use Puppeteer, then ensure that you complete the Required Puppeteer setup steps.