Carbonate, AI end-to-end testing
SDK / Libraries
DocumentationGetting started

Getting started

This guide provides everything you need to get started with the SDK.

Installation

You can get started by installing our SDK:

npm install --save-dev @carbonate/sdk

Next, install the libraries required to control the browser:

npm install --save-dev puppeteer jest jest-puppeteer

Setup

After the SDK is installed, you need to incorporate it into your favourite testing framework. Start by instantiating the SDK in your setup function:

const {Puppeteer} = require("@carbonate/sdk/dist/browser");
const SDK = require("@carbonate/sdk").default;
const {describe, expect, test} = require("@jest/globals");
const path = require("path");

let browser = new Puppeteer(page);
let sdk = new SDK(
    browser,
    path.join(__dirname, path.parse(__filename).name),
    "<your user ID>", // TODO: Change me
    "<your API key>" // TODO: Change me
);

setSDK(sdk);

You need to replace <your user ID> and <your api key> with your own credentials. You can find these in the API section of your settings panel. Alternatively, you can leave these parameters out and define the environment variables CARBONATE_USER_ID and CARBONATE_API_KEY.

Jest config

To get the full benefits of Carbonate, you should also use our custom Jest environment:

// jest.config.js
module.exports = {
  preset: "jest-puppeteer",
  testEnvironment: "@carbonate/sdk/dist/jest/puppeteer.js",
  testTimeout: 30000 // Tweak this to suit your needs
};

Performing actions

Now that's all setup, you can start asking Carbonate to perform actions.

describe("Select Test", () => {
    test("Select birthday from the event type dropdown", async () => {
        await sdk.load(
           'https://carbonate.dev/demo-form'
        );

        await sdk.action('select Birthday from the event type dropdown')

        // ... add as many actions as you like
    });
});

Advanced actions

If you need more control over actions, you can use Carbonate to locate an element and perform the actions yourself:

describe("Select Test", () => {
    test("Select birthday from the event type dropdown", async () => {
        // ...
        const dropdown = await sdk.lookup('The dropdown')

        await dropdown.select('Birthday')
     });
});

Performing assertions

You can also perform assertions using Carbonate.

describe("Select Test", () => {
    test("Select birthday from the event type dropdown", async () => {
        // ...
        expect(
            await sdk.assertion('the event type dropdown should be set to Birthday')
        ).toBe(true);
        
        // ... add as many assertions as you like
    });
});

Advanced assertions

If you need more control over an assertion, you can use Carbonate to locate an element and perform the assertion yourself:

describe("Select Test", () => {
    test("Select birthday from the event type dropdown", async () => {
        // ...
        const dropdown = await sdk.lookup('The dropdown')

        expect(
            await (await dropdown.getProperty('value')).jsonValue()
        ).toBe('Birthday');
     });
});

TLDR;

You can find a working example repository here

npm install --save-dev @carbonate/sdk puppeteer jest jest-puppeteer

// jest.config.js
module.exports = {
  preset: "jest-puppeteer",
  testEnvironment: "@carbonate/sdk/dist/jest/puppeteer.js",
  testTimeout: 30000 // Tweak this to suit your needs
};
const {Puppeteer} = require("@carbonate/sdk/dist/browser");
const SDK = require("@carbonate/sdk").default;
const {describe, expect, test} = require("@jest/globals");
const path = require("path");

let browser = new Puppeteer(page);
let sdk = new SDK(
    browser,
    path.join(__dirname, path.parse(__filename).name),
    "<your user ID>", // TODO: Change me
    "<your API key>" // TODO: Change me
);

setSDK(sdk);

describe("Select Test", () => {
    test("Select birthday from the event type dropdown", async () => {
        await sdk.load(
           'https://carbonate.dev/demo-form'
        );

        await sdk.action('select Birthday from the event type dropdown')

        expect(
            await sdk.assertion('the event type dropdown should be set to Birthday')
        ).toBe(true);
    });
});