Single Page Tests | Calibre Documentation

Single Page Tests (or SPTs for short) are synthetic speed tests for a URL of your choosing. The aim of SPTs is to provide fast feedback directly in your CLI or as part of a Continuous integration or deployment pipeline.

Each SPT is a totally independent report for a single page. There is no connection between SPTs and Sites within your account. You can use either concept independently.

Every SPT has a randomly generated public URL. You can create private tests (only viewable by logged-in members of your organisation) using the --private flag.

By default, SPTs expire after 1 year, you can specify expiry using the --expiresAt flag (Minimum 1 day, Maximum 2 years).

Create a page test#

Create Page Tests

tip

Tests can be run from different locations, using a range of device emulation and connection options. Experiment with the --location, --device and --connection flags.

# This command will block until the test has been completed
calibre test create "https://calibreapp.com" \
  --location=Sydney \
  --device=Desktop \
  --connection=cable \
  --private \
  --waitForTest

#!/usr/bin/env node

import { Test } from 'calibre'

const createTest = async () => {
  // Required parameters
  const url = 'https://calibreapp.com/docs/automation'
  const location = 'Sydney'
  const device = 'Desktop'
  const connection = 'cable'

  // Optional parameters
  const expiresAt = new Date(Date.now() + 31556952000).toISOString() // Optional, Default = 1 year
  const isPrivate = true // Default = false

  const cookies = [
    {
      name: 'app.uid',
      value: 'my-secret-tokens',
      domain: 'calibreapp.com',
      path: '/',
      secure: true,
      httpOnly: true
    }
  ]
  const headers = [
    {
      name: 'User-Agent',
      value: 'My Custom User Agent'
    }
  ]

  // Create the test
  const { uuid } = await Test.create({
    url,
    location,
    device,
    connection,
    cookies,
    headers,
    isPrivate
  })

  console.log(`Test created, ID: ${uuid}`)

  // Wait for the test to be run
  const results = await Test.waitForTest(uuid)

  // Output the formatted JSON response
  console.log(JSON.stringify(results, null, 2))
}

createTest()

You can read CLI documentation for calibre test create here.

Test statuses#

The test status field indicates the current state of the test:

Status	Description
`scheduled`	The test has been received and is awaiting execution
`running`	The test is currently being executed
`processing`	Results have been received and are being finalised
`completed`	The test completed successfully
`timeout`	The test did not complete within the 3 minute deadline
`errored`	The test did not succeed due to an error

Create a page test, send results to a webhook#

You can create page tests that automatically send JSON results to a webhook URL for processing and analysis. This is useful for integrating with other systems, such as CI/CD pipelines or custom integrations.

Webhooks fire when the test is completed, timeout or errored.

Webhooks can be verified using --webhookSecret flag or webhookSecret API parameter. The shared secret value will be signed using a HMAC cryptographic hash signature, which can be found on the Calibre-HMAC-SHA256-Signature HTTP header of the webhook request.

Create Page Tests

# Create a test then exit. Results will be sent to the webhook URL
calibre test create "https://example.com" \
  --location=Sydney \
  --device=PageSpeedDesktop \
  --private \
  --webhookUrl=https://my-webhook-url.com \
  --webhookSecret=my-secret

#!/usr/bin/env node
import { Test } from 'calibre'
const createTest = async () => {
  // Required parameters
  const url = 'https://example.com'
  const location = 'Sydney'
  const device = 'PageSpeedDesktop'

  // POST Single Page Test results to a Webhook URL for processing and analysis
  const webhookUrl = 'https://my-webhook-url.com' // Optional
  const webhookSecret = 'my-secret-webhook-token' // Optional

  const isPrivate = true // Default = false

  // Create the test
  const { uuid } = await Test.create({
    url,
    location,
    device,
    webhookUrl,
    webhookSecret,
    isPrivate
  })

  console.log(`Test created, ID: ${uuid}`)
}
createTest()

View an existing test#

Read Page Tests

# Pro tip: Add the --json flag for JSON output
calibre test show <uuid>

#!/usr/bin/env node

import { Test } from 'calibre'

const getTestData = async () => {
  // Required
  const uuid = 'dfa1a00'

  // Fetch the test results
  const results = await Test.getTestByUuid(uuid)

  // Output the formatted JSON response
  console.log(JSON.stringify(results, null, 2))
}

getTestData()

You can read CLI documentation for calibre test show here.

Retrieve test artifacts#

Read Page Tests

For each Single Page Test, Calibre stores the following information:

lighthouse.json
render progress screenshots
MP4 video render
HAR file (Request log)
all other metrics and data available through the interface

You can obtain Single Page Test artifacts with the CLI and the Node.js API. When using the CLi, files will be saved to a test-artifacts directory. The Node.js API will return a list of URLs where the files can be downloaded.

calibre test download-artifacts <uuid>

#!/usr/bin/env node

import { Test } from 'calibre'

const getTestArtifactUrls = async () => {
  // Required
  const uuid = 'dfa1a00'

  // Fetch the test results
  const results = await Test.fetchArtifacts(uuid)

  // Output the formatted JSON response
  console.log(JSON.stringify(results, null, 2))
}

getTestArtifactUrls()

You can read CLI documentation for calibre test download-artifacts here.

List all tests#

Read Page Tests

calibre test list

#!/usr/bin/env node

import { Test } from 'calibre'

const listAllTests = async () => {
  // Fetch the test list
  const tests = await Test.getList()

  // Output the formatted JSON response
  console.log(JSON.stringify(tests, null, 2))
}

listAllTests()

You can read CLI documentation for calibre test list here.