catchpoint/cli repository overview

The official documentation is available here⁠.

⁠Deployment

To run, provide your CATCHPOINT_API_TOKEN to the container. Note: for privacy, this can be placed in a restricted .env file or you may use the --secret flag (Docker Swarm) or secretKeyRef (Kubernetes).

Example: docker run -e CATCHPOINT_API_TOKEN=*your token* --rm catchpoint/cli:1.0.0

Also, if CATCHPOINT_API_TOKEN is already set as an environment variable, you may simply pass it through with -e. docker run -e CATCHPOINT_API_TOKEN --rm catchpoint/cli:1.0.0

⁠Usage

The catchpoint-cli works with our Catchpoint V4 API to manipulate Tests and InstantTests.

Each command expects a noun and verb. For example, the noun test with the verb run runs a test. See Commands below for more details about the commands.

Some parameters are expected for all commands and can optionally be specified inside a config file or by environment variable:

⁠Example Usage

These examples assume you have CATCHPOINT_API_TOKEN set as an environment variable. [[TOC]]

Note: these examples tend to rely on variables set by previous steps.

⁠Creating, Running, Getting results

⁠1. Creating an inactive Playwright test

In shell/bash, we can declare the command itself as a variable like so:

CONTAINER_COMMAND="docker run -e CATCHPOINT_API_TOKEN -e CATCHPOINT_ENVIRONMENT --rm catchpoint/cli:1.0.0"

This will only print the help for the tool without an actual command. But now we can combine CONTAINER_COMMAND with others to make repeated calls.

This example creates an inactive test and then runs it as an instant test until complete. The variables DIVISION_ID, and PRODUCT_ID should be set first:

# Create the test and return only the ID
ID=$(${CONTAINER_COMMAND} test create --test-type Playwright --test-name "Inactive PW test" --division-id "${DIVISION_ID}" --product-id "${PRODUCT_ID}" --test-script 'await page.goto("https://example.com")' --end-time 2028-01-02T15:04:05 --status inactive --output-format json --output-fields .data.test.id)

You can now get the details of the test we just created (in JSON format) like so:

${CONTAINER_COMMAND} test get --test-ids "${ID}" --output-format json

⁠2. Run the test as an Instant Test

Now set NODE_ID for an active and running node and we can run the test against it:

RUN_ID=$(${CONTAINER_COMMAND} test run --test-id "${ID}" --node-ids "${NODE_ID}" --output-format json --output-fields .data.id)

In this case, we filtered the output to only give us the id of the instant-test run in the variable RUNID.

⁠3. Check the Instant Test results

Now we can use that to check the status in a loop until the test runtime is updated:

DEFAULT_ACTUAL_RUNTIME='"0001-01-01T00:00:00"'
TIMEOUT=60
ELAPSED=0
SLEEP_INTERVAL=5

while [ ${ELAPSED} -lt ${TIMEOUT} ]; do
    RUNTIME=$(${CONTAINER_COMMAND} test get-results --instant-test-id "${RUN_ID}" --node-id "${NODE_ID}" --output-format json --output-fields .data.instantTestRecord.actualRuntime)
    echo "Test runtime: ${RUNTIME} (${ELAPSED}s elapsed)"

    if [ "${RUNTIME}" != "${DEFAULT_ACTUAL_RUNTIME}" ]; then
        echo "Test completed successfully!"
        break
    fi

    sleep ${SLEEP_INTERVAL}
    ELAPSED=$((ELAPSED + SLEEP_INTERVAL))
done

Once we know the instant test has run successfully, we can get the full results (again, as json if desired):

${CONTAINER_COMMAND} test get-results --instant-test-id "${RUN_ID}" --node-id "${NODE_ID}" --output-format json

⁠4. Set the test as "Active"

If we want the test to run as a scheduled test, we can switch the status to active with the enable verb (or inactive with the disable verb):

${CONTAINER_COMMAND} test enable --test-ids "${ID}"

We can also get the status by filtering the result by the .data.tests[0].status field:

${CONTAINER_COMMAND} test get --test-ids "${ID}" --output-format json --output-fields .data.tests[0].status

This should print "Active"

⁠5. Delete the inactive test

Once we're done with the test, we can delete it:

${CONTAINER_COMMAND} test delete --test-ids "${ID}"