TestProject Python SDK Tutorial For Selenium & Appium Tests

This Tutorial Will Help you Get Started with TestProject Python SDK. Learn to Install, Configure & Use SDK’s Most Powerful Features:

Selenium and Appium have been among the most popular open-source testing frameworks for desktop browsers and mobile-based testing for years.

The TestProject Python SDK builds on these tools and they provide you with the power of the TestProject platform, giving you beautiful HTML and PDF reports on their reporting platforms, automatic browser detection, driver configuration, and much more.

And the best thing is that using the TestProject platform and SDK is totally free, forever. The SDK is an open-source, too, so if you want to contribute to the project, you can!

What is TestProject Python SDK?

In this tutorial, you will see how to get started with the TestProject Python SDK, how to leverage the TestProject platform with your existing Selenium and Appium-based tests, as well as how to use some of the SDK’s most powerful features.

Note: Are your tests written in a language other than Python? No need to worry, TestProject offers SDKs for Java and C# as well, with more languages coming in the near future.

Installation and Configuration

Python SDK is available on PyPI, the Python package index. Here, we are assuming that you have a working Python installation, all you need to do is to install the SDK and for that, you need to run the following command:

pip install testproject-python-sdk

This will install the SDK and its required dependencies, including Selenium and the Python Appium client.

Before we can start using the SDK, we need to do two more things.

#1) Install and configure the TestProject Agent on your machine:

The TestProject Agent is responsible for browser driver installation and configuration, as well as for sending reports generated by the SDK to the TestProject platform.

After you have created an account on the TestProject platform (again, this is free), you can download your Agent.

After downloading, you will need to install and start it. By default, the Agent runs on http://localhost:8585. If you want to run the Agent on a different port, or even on an entirely different machine, that’s no problem. In this case, all you need to do is specify the correct Agent address in an environment variable TP_AGENT_URL to let the SDK know where it’s running.

#2) Get and configure a developer token:

To communicate with the Agent, you will need a developer token, too. After installing the Agent, you can get your development token from the TestProject platform site as shown in the image below.

Specify your developer token in an environment variable TP_DEV_TOKEN to make the SDK aware of it. Alternatively, you can specify it as an argument when you create a new driver session, as we will see this in a bit.

After you have downloaded the SDK, installed, configured, and started the Agent, obtained and configured your developer token, you’re ready to go.

Creating Our First TestProject-powered Selenium Test

Let’s assume we have a Selenium-based test that navigates to the TestProject demo web app. It provides login credentials and checks that we are greeted to indicate that the login action has completed successfully. Let’s also assume that we use the Pytest unit testing framework to run this test and execute the assertions.

Such a test might look something like this:

from selenium import webdriver
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome()
    driver.get('https://example.testproject.io/web/')
    driver.find_element_by_id('name').send_keys('John Smith')
    driver.find_element_by_id('password').send_keys('12345')
    driver.find_element_by_id('login').click()
    assert driver.find_element_by_id('greetings').is_displayed() is True
    driver.quit()

The example above uses Chrome as a browser. In addition to Chrome, the SDK also supports the following desktop browsers:

• Firefox
• Edge
• Internet Explorer
• Safari

For this example, we haven’t used any of the abstraction patterns that are common in Selenium-based tests, such as Page Objects, but if you do use these, that is no problem at all. In fact, we do recommend it, as this creates a clear separation between your test flow (actions, test data) and the implementation details of your web pages (element locators).

After the completion of all the installation and configuration steps shown above, all you need to do to turn this test into a TestProject-powered test is to replace the import statement as explained below.

from selenium import webdriver

Relace with this one:

from src.testproject.sdk.drivers import webdriver

That’s it! Once you run the test now, the SDK will request a driver instance from the TestProject Agent and use that to execute the test. It will also send reporting instructions to the TestProject platform, which are then used to create HTML reports. Let’s have a look at those!

Inspecting Reports On The TestProject Platform

Going to the TestProject, and selecting the ‘Reports’ options from the menu, you can see that a new report has been created for the test we have just run. Refer to the image below.

As you can see, the SDK has automatically inferred a project name (software_testing_help), a job name (examples), and a test name (test_login_to_testproject_example_app) and used these when creating the report. This is supported for both Pytest and Unittest, as well as for tests that are not run using a dedicated unit testing framework.

We’ll see how to specify the customized project, job, and test names, as well as a number of other useful reporting options in the next section.

All driver commands that have been executed during the test are automatically added to the report, together with their result. TestProject also generates overviews and dashboards out of the box.

Reporting Customization Options with TestProject

While TestProject generates rich and usable reports out of the box, there are a number of ways in which you can customize them to fit your information requirements even better.

As we have seen in the previous example, TestProject is able to automatically infer project, job, and test names for the most popular Python unit testing frameworks. If you want to use custom names in your reports, though, that can be done as well, in two different ways.

#1) Using a decorator

The TestProject SDK also features a @report decorator that you can use to decorate your test methods and that you can use to specify the custom project, job, and test names as shown below:

from src.testproject.sdk.drivers import webdriver
from src.testproject.decorator import report
	
@report(project="Software Testing Help", job="SDK Examples", test="Login Test")
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome()
    # the rest of the test method remains unchanged

When we run this decorated test method and inspect the reports, we can see that the specified names have been used in the generated report, instead of the automatically inferred ones.

#2) Specifying project and job names in the driver constructor and reporting a test manually:

Project and job names can also be overridden by specifying them in the constructor of the driver object. This can be done as follows:

from src.testproject.sdk.drivers import webdriver
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome(projectname='Software Testing Help',
 jobname='SDK Examples')
    # the rest of the test method remains unchanged

If you want to override the automatically inferred test name, you can report a test manually at the end of the test, like this:

from src.testproject.sdk.drivers import webdriver
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome(projectname='Software Testing Help',
 jobname='SDK Examples')
    driver.get('https://example.testproject.io/web/')
    driver.find_element_by_id('name').send_keys('John Smith')
    driver.find_element_by_id('password').send_keys('12345')
    driver.find_element_by_id('login').click()
    assert driver.find_element_by_id('greetings').is_displayed() is True
    driver.report().test(name='Login Test', passed=True)
    driver.quit()

If you choose to use the manual reporting option, you should disable automatic reporting of tests (which is enabled by default), to ensure that tests are not reported twice, which would corrupt your report and dashboards.

You can disable automatic reporting using the following command:

from src.testproject.sdk.drivers import webdriver
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome()
    driver.report().disable_auto_test_reports(disabled=True)
    # the rest of the test method remains as above

This will make the report look exactly the same as the last screenshot above.

#3) Disabling Reporting of Driver commands

If you don’t want your report to contain every individual driver command that was executed during the test, you can disable the automatic reporting of them like this:

from src.testproject.sdk.drivers import webdriver
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome()
    driver.report().disable_command_reports(disabled=True)
    # the rest of the test method remains unchanged

You can also re-enable driver command reporting later in your tests by calling the same method again but with the argument disabled=False.

If you still want to report some intermediate steps during your test, you can do that as well:

from src.testproject.sdk.drivers import webdriver
def test_login_to_testproject_example_app():
    driver = webdriver.Chrome()
    driver.report().disable_command_reports(disabled=True)
    driver.report().step(description="An intermediate step", message="A 
custom message", passed=True, screenshot=True)
    # here goes the rest of the test method

As you can see, you can even add screenshots to your custom report steps. These will be integrated into the HTML report on the TestProject platform automatically.

The TestProject SDK offers more options to further customize your reporting. See the official documentation on the TestProject website, GitHub, or PyPI for a complete overview.

Running Appium-based Tests Using TestProject

Next to Selenium-based tests, the TestProject SDK can also run tests on mobile devices using Appium. Consider this example, running against a native Android app on an emulator:

from appium import webdriver
def test_native_android_app():
	
    desired_capabilities = {
        "appActivity": "io.testproject.demo.MainActivity",
        "appPackage": "io.testproject.demo",
        "udid": "<your emulator name goes here>",
        "browserName": "",
        "platformName": "Android",
    }    
    
    driver = webdriver.Remote(desired_capabilities=desired_capabilities)
    driver.find_element_by_id('name').send_keys('John Smith')
    driver.find_element_by_id('password').send_keys('12345')
    driver.find_element_by_id('login').click()
    assert driver.find_element_by_id('greetings').is_displayed()
    driver.quit()

To use the power of the TestProject platform here, again, we only need to change

from appium import webdriver

To:

from src.testproject.sdk.drivers import webdriver

And we’re good to go. The TestProject Agent also acts as the Appium server, so there’s no more need to run that yourself on the machine that is running your tests.

All reporting features described above are also available for Appium-based tests.

SDK supports running mobile tests:

• For Android as well as iOS.
• On emulators as well as on real devices.
• On native apps as well as mobile browsers

Examples of all of these can be found in the SDK code repository on GitHub.

Conclusion

As you have seen in this tutorial, the TestProject Python SDK can help you supercharge your existing Selenium- and Appium-based tests by taking away the chores of configuring your browser drivers and Appium server, and it generates great HTML reports and dashboard for you on the TestProject platform.

Best of all, the TestProject Python SDK is absolutely free of charge.

=> Head on over to TestProject to try it out for yourself!

About the Author: Bas Dijkstra

The author teaches companies around the world how to improve their testing efforts through test automation. He is an independent trainer, consultant, and developer living in the Netherlands. In his free time, he likes to take his bicycle for a ride, go for a run or read a good book.