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:

composer require carbonate/sdk --dev

Next, install the libraries required to control the browser:

composer require symfony/panther --dev

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:

<?php 
namespace Tests\End2End;

use Carbonate\SDK;
use Carbonate\Browser\PantherBrowser;
use Symfony\Component\Panther\Client as PantherClient;
use Symfony\Component\Panther\PantherTestCase;
use Throwable;

class MyFirstTest extends PantherTestCase
{
    private static $carbonate;
    private static $browser;
    
    public static function setUpBeforeClass(): void
    {
        parent::setUpBeforeClass();

        // Replace these with your driver details
        self::$browser = new PantherBrowser(
            PantherClient::createChromeClient()
        );

        self::$carbonate = new SDK(
            self::$browser,
            __DIR__ .'/'. pathinfo(__FILE__, PATHINFO_FILENAME),
            "<your user ID>", // TODO: Change me
            "<your API key>" // TODO: Change me
        );
    }

    protected function setUp(): void
    {
        parent::setUp();
        self::$carbonate->startTest(__CLASS__, $this->getName());
    }

    protected function tearDown(): void
    {
        parent::tearDown();
        self::$carbonate->endTest();
    }

    protected function onNotSuccessfulTest(Throwable $t): void
    {
        self::$carbonate->handleFailedTest($t);
        parent::onNotSuccessfulTest($t);
    }
}

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.

Performing actions

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

    public function testSelectBirthdayFromTheDropdown()
    {
        self::$carbonate->load(
           'https://carbonate.dev/demo-form'
        );
        
        self::$carbonate->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:

use Facebook\WebDriver\WebDriverSelect;

    // ...
    
    public function testSelectBirthdayFromTheDropdown()
    {
        // ...
        $select = new WebDriverSelect(self::$carbonate->lookup('the event type dropdown'));
        
        $select->selectByVisibleText('Birthday');
    }

Performing assertions

You can also perform assertions using Carbonate.

    public function testSelectBirthdayFromTheDropdown() 
    {
        // ...
        $this->assertTrue(
          self::$carbonate->assertion('the event type dropdown should be set to Birthday')
        );
        
        // ... 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:

use Facebook\WebDriver\WebDriverSelect;

  // ...

    public function testSelectBirthdayFromTheDropdown() 
    {
        // ...
        $select = new WebDriverSelect(self::$carbonate->lookup('the event type dropdown'));
        
        $this->assertSame(
            'Birthday', 
            $select->getFirstSelectedOption()->getAttribute('value')
        );
    }

TLDR;

You can find a working example repository here

composer require carbonate/sdk phpunit/phpunit symfony/panther dbrekelmans/bdi --dev

<?php
namespace Tests\End2End;

use Carbonate\SDK;
use Carbonate\Browser\PantherBrowser;
use Symfony\Component\Panther\Client as PantherClient;
use Symfony\Component\Panther\PantherTestCase;
use Throwable;

class MyFirstTest extends PantherTestCase
{
    private $carbonate;
    private $browser;

    public static function setUpBeforeClass(): void
    {
        parent::setUpBeforeClass();

        // Replace these with your driver details
        self::$browser = new PantherBrowser(
            PantherClient::createChromeClient()
        );

        self::$carbonate = new SDK(
            self::$browser, 
            __DIR__ .'/'. pathinfo(__FILE__, PATHINFO_FILENAME),
            "<your user ID>", // TODO: Change me
            "<your API key>" // TODO: Change me
        );
    }
    
    protected function setUp(): void
    {
        parent::setUp();
        self::$carbonate->startTest(__CLASS__, $this->getName());
    }


    protected function tearDown(): void
    {
        parent::tearDown();
        self::$carbonate->endTest();
    }
    
    protected function onNotSuccessfulTest(Throwable $t): void
    {
        self::$carbonate->handleFailedTest($t);
        parent::onNotSuccessfulTest($t);
    }
    
    public function testSelectBirthdayFromTheDropdown() 
    {
        self::$carbonate->load(
           'https://carbonate.dev/demo-form'
        );
        
        self::$carbonate->action('select Birthday from the event type dropdown');
                
        $this->assertTrue(
            self::$carbonate->assertion('the event type dropdown should be set to Birthday')
        );
    }
}