Python

Getting started
To get started, you need to complete the following prerequisites checklist:
Login to your account at https://app.testproject.io/ or register a new one.
​Download and install an Agent for your operating system or pull a container from Docker Hub.
Run the Agent and register it with your Account.
Get a development token from the Integrations / SDK page.
Installation
The TestProject Python SDK is available on PyPI. All you need to do is add it as a Python module using:
1
pip3 install testproject-python-sdk
Copied!
and you're good to go.
Test Development
Using a TestProject driver is identical to using a Selenium driver. Once you have added the SDK as a dependency to your project, changing the import statement is enough in most cases.
You can create a TestProject-powered version of a test using Chrome by using the TestProject Chrome driver:
1
# from selenium import webdriver  <-- replace this import
2
from src.testproject.sdk.drivers import webdriver
3
​
4
def test_create_a_chrome_driver_instance():
5
    driver = webdriver.Chrome()
6
    # Your test code goes here
7
    driver.quit()
Copied!
Here's an example of a complete test that is using the Chrome driver from the TestProject SDK:
1
from src.testproject.sdk.drivers import webdriver
2
​
3
def simple_test():
4
    driver = webdriver.Chrome()
5
​
6
    driver.get("https://example.testproject.io/web/")
7
​
8
    driver.find_element_by_css_selector("#name").send_keys("John Smith")
9
    driver.find_element_by_css_selector("#password").send_keys("12345")
10
    driver.find_element_by_css_selector("#login").click()
11
​
12
    passed = driver.find_element_by_css_selector("#logout").is_displayed()
13
​
14
    print("Test passed") if passed else print("Test failed")
15
​
16
    driver.quit()
17
​
18
if __name__ == "__main__":
19
    simple_test()
Copied!
Drivers
The TestProject SDK overrides standard Selenium/Appium drivers with extended functionality.
The examples shown in this document are based on Chrome. The SDK works in the same way for all other supported browsers:
Firefox
Safari
Edge
Internet Explorer
Android apps (using Appium)
iOS apps (using Appium)
Development token
The SDK uses a development token for communication with the Agent and the TestProject platform. To configure your development token for use with the SDK, you have to specify it in an environment variable TP_DEV_TOKEN.
Alternatively, you can pass in your developer token as an argument to the driver constructor:
1
def test_create_a_chrome_driver_instance():
2
    driver = webdriver.Chrome(token='YOUR_TOKEN_GOES_HERE')
3
    # Your test code goes here
4
    driver.quit()
Copied!
TestProject Agent
By default, drivers communicate with the local Agent listening on http://localhost:8585. This value can be overridden by setting the TP_AGENT_URL environment variable to the correct Agent address.
Remote (Cloud) Driver
By default, TestProject Agent communicates with the local Selenium or Appium server. In order to initialize a remote driver for cloud providers such as SauceLabs or BrowserStack, a custom capability cloud:URL should be set, for example:
1
def driver():
2
    chrome_options = ChromeOptions()
3
    chrome_options.set_capability("cloud:URL", "https://{USERNAME}:{PASSWORD}@ondemand.us-west-1.saucelabs.com:443/wd/hub")
4
    driver = webdriver.Chrome(chrome_options=chrome_options, projectname="Examples")
5
    yield driver
6
    driver.quit()
Copied!
Reports
By default, the TestProject SDK reports all executed driver commands and their results to the TestProject Cloud. This allows us to create and display detailed HTML reports and statistics in your project dashboards.
Reports can be completely disabled using this driver constructor:
1
def test_disable_reporting():
2
    driver = webdriver.Chrome(disable_reports=True)
3
    # no reports will be created for this test
4
    driver.quit()
Copied!
Implicit project and job names
The SDK will attempt to infer Project and Job names when you use pytest or unittest. For example:
when using pytest, tests in the my_tests.py module in the e2e_tests/chrome package will be reported with a project name e2e_tests.chrome and job name my_tests.
when using unittest, tests in the my_tests.py module in the e2e_tests/chrome package will be reported with a project name chrome and job name my_tests.
Examples using inferred project and job names:
​pytest​
​unittest​
Explicit project and job names
Project and Job names can be also specified explicitly using this constructor:
1
def test_specify_project_and_job_names_in_driver_constructor():
2
    driver = webdriver.Chrome(projectname='My custom project', jobname='My custom job')
3
    # Your test code goes here
4
    driver.quit()
Copied!
or using the @report decorator:
1
from src.testproject.decorator import report
2
​
3
@report(project='My project', job='My job')
4
def test_specify_project_and_job_name_in_decorator():
5
    driver = webdriver.Chrome()
6
    # Your test code goes here
7
    driver.quit()
Copied!
Examples using explicitly specified project and job names:
​pytest​
​unittest​
Test reports
Cloud and Local Report
By default, the execution report is uploaded to the cloud, and a local report is created, as an HTML file in a temporary folder.
At the end of execution, the report is uploaded to the cloud, and SDK outputs to the console/terminal the path for a local report file:
Execution Report: {temporary_folder}/report.html
This behavior can be controlled, by requesting only a LOCAL or only a CLOUD report.
When the Agent is offline, and only a _cloud_ report is requested, execution will fail with appropriate message.
Via a driver constructor:
1
driver = webdriver.Chrome(report_type=ReportType.LOCAL)
Copied!
Automatic test reporting
Tests are reported automatically when a test ends or when the quit() command is called on the driver. This behavior can be overridden or disabled (see the Disabling Reports section below).
In order to determine whether a test has ended, the call stack is inspected, searching for the current test method. When the test name is different from the latest known test name, it is concluded that the execution of the previous test has ended. This is supported for both pytest and unittest.
To override the inferring of the test name and specify a custom test name instead, you can use the @report decorator:
1
from src.testproject.decorator import report
2
​
3
@report(test='My test name')
4
def test_specify_test_name_in_decorator():
5
    driver = webdriver.Chrome()
6
    # Your test code goes here
7
    driver.quit()
Copied!
Here is a complete example using automatic reporting.
Manual test reporting
To report tests manually, you can use driver.report().test():
1
def test_report_test_manually():
2
    driver = webdriver.Chrome()
3
    # Your test code goes here
4
    driver.report().test(name='My test name', passed=True)
5
    driver.quit()
Copied!
Reporting steps
Steps are reported automatically for every driver commands that is executed. If this feature is disabled, or you would like to add steps manually, you can use driver.report().step():
1
def test_report_step_manually():
2
    driver = webdriver.Chrome()
3
    # Your test code goes here
4
    driver.report().step(description='My step description', message='An additional message', passed=False, screenshot=True)
5
    driver.quit()
Copied!
Here is a complete example using manual test reporting of tests and steps.
Disabling reports
If reports were not disabled when the driver was created, they can be disabled or enabled later. However, if reporting was explicitly disabled when the driver was created, they cannot be enabled later.
Disable all reports
The following will temporarily disable all reporting:
1
def test_temporarily_disable_all_reporting_then_reenable_it_later():
2
    driver = webdriver.Chrome()
3
    driver.report().disable_reports(True)
4
    driver.find_element_by_id('your_element_id').click()  # This statement will not be reported
5
    driver.report().disable_reports(False)
6
    driver.quit()
Copied!
Disable automatic test reports
The following will disable automatic reporting of tests. All steps will end up in a single test report, unless tests are reported manually using driver.report().test():
1
def test_disable_automatic_test_reporting():
2
    driver = webdriver.Chrome()
3
    driver.report().disable_auto_test_reports(True)
4
    # Tests will not be reported automatically from here on
5
    driver.quit()
Copied!
Disable driver command reports
The following will disable driver command reporting, which results in the reporting of tests that will have no steps, unless reported manually using driver.report().step():
1
def test_disable_automatic_reporting():
2
    driver = webdriver.Chrome()
3
    driver.report().disable_command_reports(True)
4
    # From here on, driver commands will not be reported automatically
5
    driver.quit()
Copied!
Disable driver command redaction
When driver commands are being reported, the SDK will, by default, redact the values typed into sensitive elements by replacing the actual text with three asterisks (***) in the report. Elements are considered sensitive if they:
have an attribute type with value password (all browsers and platforms)
are of type XCUIElementTypeSecureTextField (iOS / XCUITest only)
This redaction of sensitive commands can be disabled, if desired:
1
def test_disable_driver_command_report_redaction():
2
    driver = webdriver.Chrome()
3
    driver.report().disable_redaction(True)
4
    # From here on, driver commands will not be redacted
5
    driver.quit()
Copied!
If no test name is specified using the decorator, the test method name will be used as the test name in the report.
The importance of using quit()
Even more so than with regular Selenium- or Appium-based tests, it is important to make sure that you call the quit() method of your TestProject driver object at the end of every test that uses the TestProject SDK.
Upon calling quit(), the SDK will send all remaining report items to the Agent, ensuring that your report on the TestProject platform is complete.
Tip for pytest users: use a pytest fixture to ensure that quit() is called at the end of the test, even when an error occurred during test execution:
1
import pytest
2
​
3
@pytest.fixture
4
def driver():
5
    driver = webdriver.Chrome()
6
    yield driver
7
    driver.quit()
8
​
9
def test_using_pytest_fixture(driver):
10
    driver.get("https://example.testproject.io/web")
Copied!
Tip for unittest users: use the setUp() and tearDown() methods for driver creation and destroying:
1
import unittest
2
​
3
class ChromeTest(unittest.TestCase):
4
​
5
    def setUp(self):
6
        self.driver = webdriver.Chrome()
7
​
8
    def test_using_unittest_setup_and_teardown(self):
9
        driver.get("https://example.testproject.io/web")
10
​
11
    def tearDown(self):
12
        self.driver.quit()
Copied!
Logging
The TestProject Python SDK uses the logging framework built into Python. The default logging level is INFO and the default logging format is %(asctime)s %(levelname)s %(message)s, which results in log entries formatted like this:
13:37:45 INFO Using http://localhost:8585 as the Agent URL
If you wish, you can override the default log configuration:
For pytest users, it is recommended to provide alternative values in your pytest.ini​
Users of unittest can override the configuration by setting the TP_LOG_LEVEL and / or TP_LOG_FORMAT environment variables, respectively, to the desired values
See this page for a list of accepted logging levels and look here for more information on how to define a custom logging format.
Examples
Here is a list of all examples for the different drivers that are supported by this SDK:
Web
​Chrome test​
​Firefox test​
​Safari test​
​Edge test​
​Internet Explorer test​
Android
​Android native test​
​Android native app​
​Web test on mobile Chrome​
iOS
​iOS native test​
​iOS native app​
​Web test on mobile Safari​
License
The TestProject Python SDK is licensed under the LICENSE file in the root directory of the project source tree.