API Check Set Up and Tear Down

Setup and teardown scrips have a maximum execution time of 10 seconds.

​

Setup scripts

// request.headers is a standard Javascript object

// Set a custom header
request.headers['X-Custom-Header'] = 'my value'

// Append a value to the request url
request.url = request.url + '/extra'

// Define a cookie
request.headers['Cookie'] = tokenString

​

Authentication using setup scripts

1. Create an API check an reference the setup script (setup.ts) using the entrypoint property.
2. Encapsulate the actual authentication logic (fetching, signing etc.) in a separate auth-client.ts file.
3. In the setup.ts file, import common/auth-client.ts and update the necessary fields in the request object.

.
|-- api-1.check.ts
|-- setup.ts
`-- common
    `-- auth-client.ts

import { ApiCheck } from '@checkly/cli/constructs'
import * as path from 'path'

new ApiCheck('api-check-1', {
    name: 'Fetch Product Data',
    setupScript: {
        entrypoint: path.join(__dirname, 'setup.ts'),
    },
    request: {
        method: 'GET',
        url: 'https://api.acme.com/v1/products'
    }
})

• The request object is a global variable, injected at runtime. See the request reference below for more details
• You need to use a top-level await statement as the getToken() function returns a Promise.

import { getToken } from './common/auth-client'
const token = await getToken()
request.headers['Authorization'] = `Bearer ${token}`

import axios from 'axios'

export async function getToken () {
    console.log('Fetching session token from auth server')
    const { data } = await axios.get('https://api.checklyhq.com/v1/runtimes', {
        headers: {
            authorization: process.env.AUTH_SERVER_TOKEN
        }
    })
    return data.token
}

1. You can reuse the authentication logic across as many API checks as you want.
2. You can test the core authentication logic separately from any Checkly specific code.

​

Teardown scripts

​

Built-in variables

1. Environment variables for reading tokens and other secrets you have stored.
2. The request object.
3. The response object, only in teardown scripts as there is no response till after the API check runs.
4. Built-in runtime variables injected automatically, like process.env.CHECK_NAME

​

Environment

// read values and use them for further processing
const myValue = process.env.MY_KEY

// write values
process.env.MY_KEY = myValue + 10

// add a new key/value pair
process.env.NEW_KEY = 'new value'

// remove a key
delete process.env.SOME_OTHER_KEY

​

Request

​

Response

​

Built-in runtime variables

​

Setup & teardown specific variables

​

Generic runtime variables

​

Included libraries

​

Technical limitations

• Setup and teardown scripts are implicitly wrapped in async function. This means you can always use await statements.
• You cannot use nested callbacks as there is no way to determine the callback function. Always use await statements.
• You need to include modules and libraries explicitly, e.g. const moment = require('moment') before you can use them.
• You can pass a maximum of 256KB of data to and from the check’s main request (e.g. using request.body = data).

​

Using setup and teardown scripts via the UI

1. Using a inline piece of JS/TS code as shown below. This is great for quick, adhoc pieces of code you only use once.

2. Using snippets to DRY (Don’t Repeat Yourself) up your code, and referencing those snippets by name. This method approaches the way of working with the CLI, but is less flexible in general as you don’t have direct access to a full JS/TS environment.

​

Using environment variables via Handlebars

// define a variable that should be accessible in the API Check response body
process.env.MY_VALUE = 'my value'