logo logo

Getting Started with TestProject Python SDK

Getting Started with TestProject Python SDK

With the TestProject Python SDK, you can execute your Selenium and Appium tests using the power of the TestProject platform. This means you’ll benefit from automatic test reporting in HTML and PDF, automatic updates and configuration of your Selenium browser drivers, collaborative reporting dashboards, and much more (Learn more about the benefits of TestProject OpenSDK).

In this article, we’ll take a look at how to get started with the TestProject Python SDK. We’ll first see how to create a TestProject powered Selenium test ‘from scratch’, and then you’ll how you can convert your existing test suite into one that uses the TestProject platform.

🐍 Watch a webinar recording to get started with the TestProject Python OpenSDK! 🐍

Table of Contents

  1. You’re here →Getting Started with TestProject Python SDK
  2. Creating Mobile Appium Tests with TestProject Python SDK
  3. HTML Test Reports for Selenium & Appium Python Test Automation

Installing the TestProject Python SDK

The TestProject Python SDK is 100% free and open source, and is available as a PyPI package. You can install the package using pip:

pip install testproject-python-sdk

This will install the SDK as well as its dependencies. To prevent version conflicts across projects, it is recommended to use a virtual environment for the development of your tests.

Configuring your TestProject Agent

Like all TestProject SDKs, the Python SDK executes tests using the TestProject Agent. This Agent takes care of browser driver installation and configuration as well as reporting to the TestProject platform. You can download the Agent from here.

By default, the SDK will communicate with the Agent on its default address, which is http://localhost:8585. If you’re running the Agent on another port, or even an entirely different machine, you can configure the correct address by setting the TP_AGENT_URL environment variable to the correct address.

Configuring your developer token

To communicate with the Agent, you need a developer token. You can configure the SDK to use it by obtaining a token from https://app.testproject.io/#/integrations/sdk, and setting an environment variable TP_DEV_TOKEN with the token value.

Creating your first test

After installing and setting up the SDK, it’s time to start writing our first test 💪
Here is a fully functional example test that opens the TestProject demo application, logs in and checks that a greeting message is displayed:

from src.testproject.sdk.drivers import webdriver

def simple_test():
    driver = webdriver.Chrome()


    driver.find_element_by_css_selector("#name").send_keys("John Smith")

    passed = driver.find_element_by_css_selector("#logout").is_displayed()

    print("Test passed") if passed else print("Test failed")


if __name__ == "__main__":

If you’re already familiar with developing Selenium-based tests in Python, this code should not be difficult to understand. Let’s run it and see what happens! But first, make sure that your TestProject Agent is running. 

Running the test

Let’s assume that the example test we just saw resides in a Python module called web_test.py. Since we made this module runnable using if __name__ == “__main__”, we can run this test simply by executing the following command:

python web_test.py

This will request a Chrome driver instance from the TestProject Agent, run the tests and report results to the TestProject platform. If you configured your developer token and Agent address correctly, you’ll see the following output in your console, indicating that our test was executed successfully:

Test passed
2020-07-13 09:30:03,884 INFO Connection to Agent at closed successfully

Process finished with exit code 0

Let’s take a look at the reports that were generated.

Inspecting the test reports

The TestProject Agent will automatically report your test results to the TestProject platform. If you head over to https://app.testproject.io/#/reports, you’ll see a project called ‘Unnamed Project’:

TestProject Python SDK - Generated Test Reports

If you click on this, you’ll see an overview of the test runs associated with this project. This will contain a job called ‘web_test’ (the job name is automatically derived from the Python module name) and a passed test called ‘simple_test’ (the test name is automatically derived from the test method name):

TestProject Python SDK - Generated Test Reports

As you can see, the test is marked as passed, and all the individual actions that were performed by the browser driver instance are reported to the right, all out of the box, without the need for additional configuration!

The TestProject Python SDK offers you a variety of options to customize your reporting. We will take a closer look at those in a follow-up article (coming soon!). One thing that is worthy of mentioning here, though, is that values that are entered into password fields are automatically redacted, as you can see in step 5 of the report. This feature can also be switched off if desired. You’ll see how in the article on reporting coming soon. 

Supported unit testing frameworks

Currently, the TestProject Python SDK supports the unittest and pytest unit testing frameworks. If you have existing unittest– or pytest-based Selenium tests, it is very easy to convert these to TestProject-powered tests.

Let’s take a look at this pytest-based example. The process is exactly the same for unittest, by the way:

from selenium import webdriver
from tests.pageobjects.web import LoginPage, ProfilePage

def test_example_using_chrome():
    driver = webdriver.Chrome()
    LoginPage(driver).open().login_as("John Smith", "12345")
    assert ProfilePage(driver).greetings_are_displayed() is True

Assuming that you have added the TestProject SDK as a dependency to your project, and that you have configured both the Agent and your developer token as described earlier in this article, the only thing you need to do to change this import statement:

from selenium import webdriver

to this:

from src.testproject.sdk.drivers import webdriver

and you’re good to go. It is that easy! Now, let’s assume that this test is part of a module example_test in a package called tests. If you run this test using:

pytest tests\example_test.py

and go to the TestProject reports page again, you’ll see a report that looks like this:

TestProject Python SDK - Generated Test Reports

As you can see, the SDK has automatically derived the test name (‘test_example_using_chrome’) and the job name (‘example_test), from the test method name and the package name, respectively. Additionally, if you’re using pytest or unittest, the SDK will also automatically infer a project name based on the package that the test modules are in. The project, job and test names can also be customized if you like. You will see how to do that in the reporting article coming soon – Stay tuned for that 😉


As we’ve seen in this TestProject Python SDK tutorial, with just one unified SDK (that’s also available in Java and C# by the way), developers and testers receive a go-to toolset, solving some of the greatest challenges in open source test automation. Using the TestProject SDK will save you a bunch of time, while and enjoy the following benefits out of the box:

  • Open source and available as a Maven dependency / a NuGet package / a PyPI project.
  • 5-minute simple Selenium and Appium setup with a single Agent deployment.
  • Automatic test reports in HTML/PDF format (including screenshots and customization capabilities).
  • Collaborative reporting dashboards with execution history and RESTful API support.
  • Always up-to-date with the latest and stable Selenium driver version.
  • A simplified, familiar syntax for both web and mobile applications.
  • Complete test runner capabilities for both local and remote executions, anywhere.
  • Cross platform support for Mac, Windows, Linux and Docker.
  • Ability to store and execute tests locally on any source control tool, such as Git.

For those of you who prefer watching tutorials – You should definitely watch these awesome webinar recordings presented by Bas Dijkstra ✨

[July 28, 2020] Selenium & Appium Python Testing with TestProject OpenSDK

👉 Get the Presentation Slides 👈

[Oct 8, 2020] Advanced Session – Python Testing with the TestProject OpenSDK: Complete CI/CD Flow

👉 Get the Presentation Slides 👈

We can’t wait for you to start exploring the new TestProject Python SDK 🎉
Share your experience in the comments below.
Happy PyTesting! 🤩

About the author

Bas Dijkstra

Bas 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. When he’s not working he likes to take his bicycle for a ride, go for a run or read a good book.


9 4 comments
  • SANJAY YADAV July 29, 2020, 3:56 pm

    Very interesting, good job and thanks for sharing such a good blog. I am looking for some good Online IT Training blog sites for studying.

  • Core89 August 4, 2020, 8:05 pm

    Hi, I am already using an agent for the piepeline execution. How to integrate your agent and execute the sdk>???

    • David Goichman August 5, 2020, 1:05 pm

      Hello Core,
      To use our SDK in your tests you will need to change the driver creation in your code.
      Depending on the SDK you’re using, you’ll need to change the import and driver initialization.
      For example, in Python:

      # from selenium import webdriver <– replace this import
      from src.testproject.sdk.drivers import webdriver

      def test_create_a_chrome_driver_instance():
      driver = webdriver.Chrome()
      # Your test code goes here

      And then you can run your code through your pipeline using the TestProject driver, the reports will be generated automatically on the TestProject cloud platform.

    • David Goichman August 5, 2020, 6:06 pm

      I’d also like to add to that last comment that we’ve recently added some documentation you could check out that relates to CI/CD using the TestProject SDK and agent.
      You can find it here:

Leave a Reply