This Tutorial Will Help you Get Started with TestProject Python SDK. Learn how 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.
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.
The best thing about using the TestProject platform and SDK is that it’s totally free, forever. The SDK is open-source, too, so if you want to contribute to the project, you can!
Table of Contents:
TestProject Python SDK
What is TestProject Python SDK
In this tutorial, you will see in detail 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.
Once you have created an account on the TestProject platform (again, this is free), you can download your Agent.
After downloading it, you will need to install it 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, its not a 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:
In order to communicate with the agent, you will need a developer token as well. 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 this as an argument when you create a new driver session, as we will see this in a bit.
Once 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 Test Project-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 been completed successfully. We will 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 recommend this, 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
Replace 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 customized projects, jobs, 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 results. 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 report the test manually:
Projects 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
You can even add screenshots to your custom report steps. This 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
We’re good to go. The TestProject Agent also acts as the Appium server, so there’s no 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 dashboards for you on the TestProject platform in a very effective way.
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 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 go for a ride on his bicycle or a run or relax by reading a good book.