estpad has long been promising an API, and the project is now nearly ready. The code has been implemented for all endpoints and webhooks, along with UI settings to control access keys and configure the webhooks etc. Remaining work includes our own testing (!), reviewing the documentation, and the server/networking deployment of the API servers. The deployment aspects are critical as we want to protect the availability of the main UI app servers from errant
(buggy, malicious even!) code flooding the endpoints with requests.

The rest of this post is to give you a teaser/taster of the API and what it will look like. The syntax presented here is not final, but do write in if any of the choices being implied here raise questions for you.

As a reminder, if you are interested in early access to the beta version of the API, to both get started with it but also help test it in real scenarios, then please register your interest and enthusiasm with support@testpad.com.

Endpoints and Webhooks

The API will be presented in two parts:

• a collection of endpoints for making calls to, and
• a collection of events for subscribing webhooks to.

Endpoints

Full documentatation will be released alongside the beta of the API, but the general goals of the endpoints are to enable:

• injecting test results from external systems (such as automated testing and CI systems), with options for doing this whole script at a time, whole test run at a time, or just individual results one at a time
• creating new folders to post new scripts into
• extracting result and progress statistics at the folder, script and run levels

Example, injecting whole script of tests and results

For example, to create a new script in project 5 in folder f2, populated with tests, header fields, test runs and results, you would send an HTTP POST:

POST /projects/5/folders/f2/scripts
{
  "name": "Automated tests for rain predictor",
  "fields": ["(weather)", "build", "date"],
  "runs": [
    ... run definitions ...
  ],
  "tests": [
    ... test definitions with results per test...
  ]
}

Example, extracting a folder progress summary

For example, to fetch the current progress statistics for folder f3 in project 4, but without also drilling down in the contents and progress of each contained script, you would send an HTTP GET with parameters:

GET /projects/4/folders/f3?progress=terse&scripts=none

Generating a response along the lines of:

{
  ...
  "data": {
    "folder": {
      "id": "f12",
      "name": "Release folder 3.2",
      "progress": {
        "pass": 31,
        "fail": 42,
        "block": 0,
        "query": 1,
        "total": 87
        "summary": "Pass:31 Fail:42 Block:0 Query:1 Total:74/87",
      },
    }
    ...
  }
}

Webhooks

Again, full documentation to follow, but the general goals of the webhooks are to enable external URLs to be called in response to test run events arising in Testpad. Further events will be added in time, but the initial collection of subscribable events are mainly designed for:

• individual results being set, filterable for e.g. just failed results (which you might connect up to the automatic creation of a JIRA ticket, assuming you want the possible duplication this will entail!), and
• run-level events such as test runs being started and completed

Example, subscribing to results set to fail

To connect an external action, such as a Zap in Zapier or some custom integration with JIRA or AWS Lambda, you would configure a webhook using the Testpad interface (API endpoints to subscribe webhooks won't be in v1, but certainly could be added if there's demand in the future).

Configuring a webhook means telling Testpad that you want your URL, e.g. https://hooks.zapier.com/hooks/catch/345678/abc34, to be called (by Testpad) whenever the event result.fail occurs.

For now, events will be generated for all projects in an account, however we anticipate providing for project-level filtering fairly soon after the initial release (and again, feedback welcome on this).

When a result.fail does then fire, your URL would be called with an HTTP POST:

POST https://hooks.zapier.com/hooks/catch/345678/abc34
...
... HTTP headers for signatures and content meta data
...

[
  {
    "_event": {
      "topic": "result.fail", 
      "id": "bb8f5cba-17b73e73688", 
      "ts": { ... various timestamp formats ... },
    }, 
    "result": {
      "comment": "", 
      "issue": "", 
      "result": "fail", 
      "url": "https://stef.ontestpad.com/script/3657/#2/1.2"
    },
    "context": {
      "account": { ... }, 
      "user":    { ... }
      "project": { ... },
      "folder":  { ... },
      "script":  { ... },
      "test":    { ... }, 
      "run":     { ... }
    }
  }
]

Timescales

Our most frequent support email these days (besides requests for old invoices - sorry folks, and ahem FastSpring) are customers asking when the API will be out. Having long got this wrong, I'm not promising a specific date. However, the project is mostly complete and the hope, but not promise, is to have this out early next year.

Meanwhile, if you are in the crowd itching to integrate your other tools with Testpad, I hope the above details are exciting and thank you for your continued patience!

Any questions or feedback, please do write in to support@testpad.com

If you liked this article, consider sharing