@testsigma/addon-sdk

Author-facing SDK for writing addons for the Testsigma test-automation platform.

Write your addon in TypeScript, declare its inputs and outputs once, get full type-safety + IDE autocomplete in execute(), and ship a single zip the Testsigma UI uploads.

Install

pnpm install @testsigma/addon-sdk

Quick start

import { defineAddonTemplate } from "@testsigma/addon-sdk";

export const readText = defineAddonTemplate({
  name: "myaddon.readText",
  description: "Read the text content of a located element.",
  actionText: "Read text from ${target} into ${value}",
  applicationType: ["WEB"],
  permissions: {},
  elements: {
    target: { description: "Element to read text from" },
  },
  outputs: {
    value: { type: "runtimeVar", description: "The element's text content" },
  },

  async execute(input, ctx) {
    const text = (await ctx.ui.browser.locate(input.elements.target).textContent()) ?? "";
    return {
      message: {
        success: `Read ${text.length} character(s)`,
        failure: `Could not read text`,
      },
      outputs: { value: text },
    };
  },
});

Each named export of a defineAddonTemplate() call becomes a step a test author can pick in the Testsigma step editor.

How applicationType shapes ctx.ui

The platforms you declare narrow the active adapter at compile time:

| applicationType | ctx.ui in execute() | |---|---| | ["WEB"] | { kind: "web"; browser } — ctx.ui.browser.locate(...) directly | | ["ANDROID"] or ["IOS"] | { kind: "mobile"; mobile } — ctx.ui.mobile.locate(...) directly | | ["WEB", "ANDROID"] | discriminated union — narrow with if (ctx.ui.kind === "web") | | [] | compile error — you must declare at least one platform |

Build + upload

The SDK is the author-time contract; the actual bundle you upload to Testsigma is produced by your project's pnpm run build:

pnpm install
pnpm run build      # produces dist/index.js + <name>-<version>.zip

Open your addon's detail page in the Testsigma Addons UI, click Upload Zip File, drop the generated .zip. The platform unzips, registers your steps from manifest.json, and serves the bundle to runners on first use.

Adapters available on ctx

| Field | When available | |---|---| | ctx.ui.browser | applicationType includes WEB or MOBILE_WEB | | ctx.ui.mobile | applicationType includes ANDROID or IOS | | ctx.runtime | always — read/write runtime variables by name | | ctx.logger | always — structured logger | | ctx.ai | only when permissions.ai is declared | | ctx.ocr | only when permissions.ocr is declared |

License

MIT — see LICENSE.