Getting started
This guide provides everything you need to get started with the SDK.
Installation
You can get started by installing our SDK:
pip install carbonate-sdk
For this guide, we'll be using WebDriverManager to automatically download and launch the latest version of Chrome:
pip install webdriver-manager selenium
This step is not necessary if you already have Chrome running.
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:
import os
import unittest
import carbonate_sdk
from selenium import webdriver
from webdriver_manager.chrome import ChromeDriverManager
from selenium.webdriver.chrome.service import Service
class my_first_test(unittest.TestCase):
browser = None
carbonate = None
@classmethod
def setUpClass(cls) -> None:
# This can be any browser supported by webdriver
driver = webdriver.Chrome(
service=Service(executable_path=ChromeDriverManager().install())
)
cls.browser = carbonate_sdk.WebDriver(driver)
cls.carbonate = carbonate_sdk.SDK(
browser=self.browser,
cache_dir=os.path.join(os.path.splitext(__file__)[0]),
api_user_id="<your user ID>", # TODO: Change me
api_key="<your API key>" # TODO: Change me
)
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.
@carbonate_sdk.test("carbonate")
def test_select_birthday_from_the_dropdown(self):
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
Notice how we've decorated the test with the @carbonate_sdk.test("carbonate")
. This annotation wraps your test, automatically setting the test name and injecting the logs into the test output. If you use a different variable name to reference the Carbonate SDK, you will need change the argument passed to this decorator to match it.
Advanced actions
If you need more control over actions, you can use Carbonate to locate an element and perform the actions yourself:
from selenium.webdriver.support.ui import Select
# ...
@carbonate_sdk.test("carbonate")
def test_select_birthday_from_the_dropdown(self):
# ...
select = self.carbonate.lookup('the event type dropdown')
Select(select).select_by_visible_text('Birthday')
Performing assertions
You can also perform assertions using Carbonate.
@carbonate_sdk.test("carbonate")
def test_select_birthday_from_the_dropdown(self):
# ...
self.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:
from selenium.webdriver.support.ui import Select
# ...
@carbonate_sdk.test("carbonate")
def test_select_birthday_from_the_dropdown(self):
# ...
select = self.carbonate.lookup('the event type dropdown')
self.assertEqual('Birthday', Select(select).first_selected_option.text)
TLDR;
You can find a working example repository here
pip install carbonate-sdk webdriver-manager selenium
import os
import unittest
import carbonate_sdk
from selenium import webdriver
from webdriver_manager.chrome import ChromeDriverManager
from selenium.webdriver.chrome.service import Service
class my_first_test(unittest.TestCase):
browser = None
carbonate = None
@classmethod
def setUpClass(cls) -> None:
# This can be any browser supported by webdriver
driver = webdriver.Chrome(
service=Service(executable_path=ChromeDriverManager().install())
)
cls.browser = carbonate_sdk.WebDriver(driver)
cls.carbonate = carbonate_sdk.SDK(
browser=self.browser,
cache_dir=os.path.join(os.path.splitext(__file__)[0]),
api_user_id="<your user ID>", # TODO: Change me
api_key="<your API key>" # TODO: Change me
)
@carbonate_sdk.test("carbonate")
def test_select_birthday_from_the_dropdown(self):
self.carbonate.load(
'https://carbonate.dev/demo-form',
)
self.carbonate.action('select Birthday from the event type dropdown')
self.assertTrue(
self.carbonate.assertion('the event type dropdown should be set to Birthday')
)