Tauk Reports using Github Actions

Github Actions is a free solution to set up Continuous Integration and Continuous Delivery (CI/CD) for your Selenium test suite. In the previous blog posts, I discussed how to integrate your test suite with the Tauk Python package to generate Tauk Reports. With the help of Github Actions, it is possible to generate these reports in a CI/CD environment.

In this blog post, I aim to set up a sample Selenium test suite in a Github repo, and define a Github workflow configuration file to run Selenium tests on each push. Since this repository will be integrated with Tauk using the Tauk Package, your tests will also generate reports in the Tauk Web UI for each run.

Assumed Knowledge

For this blog post, it is recommended that you have knowledge of the following:

• Integrating tauk python package with your unittest suite.
• Using environment variables to configure Tauk API Access for your test runs.

In my previous blog post — Parallel Test Execution and Tauk — I have described both of these items in detail.

Creating a new Selenium Suite (Optional)

Let us start by creating a fresh Github repository. You can do so by navigating to https://github.com/new

NOTE:

• The repository should be public as Github Actions free-tier only pertains to public repos. For private repos, as long as you do not exceed the Github Actions quotas, you will not be charged. You can read more about billing of Github Actions here.

We will aim for a directory structure that looks like this.

.
├── LICENSE
├── README.md
├── requirements.txt
└── test
    ├── __init__.py
    ├── tauk_test.py
    └── tauk_welcome_test.py

Let us go ahead and write the code for the Selenium suite before I explain how to set up CI/CD. If you already have a Selenium Suite, simply skip this section.

Creating a .gitignore

Clone this repository on your local system. Add a .gitignore file to the root of your repository.

__pycache__/
venv/
.idea/
.env

Creating a Virtual Environment

Create a virtual environment to manage Python dependencies for this project. You can create a new Python virtual environment using the following shell command. You can then activate this environment so that all installed Python packages are done so in the environment.

# Create a new virtual environment
python3 -m venv venv
# Activate the newly created environment
source venv/bin/activate

Installing Dependencies using pip

This project has a few dependencies. These can be installed all at once using pip. In the root of your repository, create a new file called requirements.txt

selenium==4.3.0
tauk==2.1.3
webdriver-manager==3.8.1
python-dotenv==0.20.0

You can install these by the following shell command. Make sure your environment is activated as this command might conflict with the global installation of these packages in your system otherwise.

pip install -r requirements.txt

Create a .env

To store environment variables for your local runs, you also need to create a .env file. This file will store Tauk API credentials and configurations.

TAUK_API_TOKEN=XXXXX-XXXXXXXXXXXXXXXXXXXXXX
TAUK_PROJECT_ID=XXXXXXXXX

You can get these secrets from the Tauk Web UI.

Create a Base Test with Fixtures

Next up, let’s create a base test case that:

• defines start up and clean up steps for test case
• loads environment variables from .env
• defines Chrome driver options
• creates a Chrome driver, and
• initializes Tauk object so that it links to the unittest lifecycle.

Make a new package in your root folder. You can do so by creating a new directory called test. Within that directory, create an empty file called __init__.py

Within that same directory, create a new file called tauk_test.py and add the following content to it.

This file defines the chrome_options necessary for a headless chrome run. It loads environment variables from the .env created earlier using the previously installed package python_dotenv. Finally, it initializes Tauk() and gives it access to the driver so that the necessary properties and screenshots for the test runs can be captured in the Tauk report.

Create a Test

Let us extend the base test and create a test case which utilizes the fixtures defined above.

Within the ./test directory, create a new file called tauk_welcome_test.py and add the following content.

This will click a button on the Tauk Welcome page. Tauk will recognize this as TaukWelcomeTest.

Run using unittest CLI

Let us utilize the unittest command line interface to run this test case. In the root of your repository, execute this shell command.

python -m unittest test.tauk_welcome_test.WelcomeTest.test_ClickPrimaryButton

You should see the following command output.

2022-07-14T17:45:30-0700 [42634-MainThread] INFO Setting run ID for current execution as cd38253c8ba543c5b97f9e12c697d7b6
2022-07-14T17:45:32-0700 [42634-MainThread] INFO Registering driver instance: driver=[<selenium.webdriver.chrome.webdriver.WebDriver (session="537e4ba68f549a756c8d8b3893b43e10")>], unittestcase=[test_ClickPrimaryButton (test.tauk_welcome_test.WelcomeTest)]
.
----------------------------------------------------------------------
Ran 1 test in 8.664s
OK

You should also see a new report in the Project View of the Tauk Web UI.

Setting up Github Actions

Github actions allows you to run user-defined or pre-defined scripts on certain events. These events can be a scheduled trigger of jobs or a push to your repository. Once the event is detected, Github runs a script on instances that are in accordance to the configurations described in workflow files.

Creating a Github Workflow

Github checks for workflow files within your repository. By default, the workflow files are stored in the ./.github/workflows folder in your repository.

Let us create a workflow config file called tauk_tests.yaml.

Glossary for Workflow Keywords

The above file will run the Python Selenium tests every time code is pushed to the repository.

• name: This keyword indicates the name of your workflow.
• on: This keyword indicates that the workflow should be triggered when the vent specified here is detected. For this example, the tauk_tests workflow will be triggered every time a push is detected on the main branch of your repository.
• jobs: The jobs keyword defines what jobs to run and which instances to run them on. There can be multiple jobs. Each sub key within this config object will be the name of the job. In this example, there is only one job called tauk_tests.
• runs-on: This defines what platform to run these jobs on. Instances for Windows, MacOS, and Linux are available. You can also set up your own runners for your jobs.
• steps: Each step is run sequentially. It can also be named which will then be displayed in the logs. A - symbol marks the beginning of each step.
• uses and run: A step can either use a pre-defined script which are called Actions or define their own shell script. uses points out which pre-defined Action to run. The runs keyword defines a shell script.

Explanation of the tauk_tests workflow script

Now that we are familiar with the keywords, it is time to understand how we are running the Selenium tests.

• The first step is to checkout the latest commit from the main branch on the runner. This is achieved by running the actions/checkout script.
• Next up, it is time to set up the Python environment for your test to run. This is achieved using the actions/setup-python script. You can read more about this script here.
• Then, we install the dependencies using pip. You might notice that this is the same command that you used while setting up the local version of the repository in the previous section.
• Next up, we create a .env file for this run and load the Tauk environment variables here. You might have noticed that I added the .env file in the .gitignore. This was done to ensure that no credentials were stored or hardcoded in the open source code.
• Lastly, we run the tests using the same command that we used in the previous section. This command utilizes the unittest command line interface.

Adding Github Secrets

The meticulous reader might have noticed that the Tauk environment variables are loaded dynamically in the shell script using the ${{ }} syntax. These are actually supplied by Github Secrets that you can set in the Settings of your repository.

On the main page of your repository in Github, click on Settings → Secrets → Actions.

Create a new secret by clicking on the New repository secret button on the top right.

Store your Tauk API token here. Use the same naming convention as you used in the local .env file. Repeat these steps to create another secret for TAUK_PROJECT_ID.

Trigger your Github Actions Workflow

Now, it is time to trigger the workflow by staging, committing, and pushing the changes to your repo. You can do so by using these commands.

# Staging all changed files
git add -A
# Commiting the changes
git commit -m "Adding Workflow"
# Pushing to Remote
git push

You should see a new workflow run being triggered in the Actions tab. You can click on the latest run. It should look something like the screenshot below.

You can toggle each step defined in your YAML file to see command outputs. If you expand the Test with unittest step, you should see that your tests generated the same output as in your local runs.

Since your workflow run triggered Selenium tests with Tauk() initialized, you should be able to see new Tauk reports in the Project Detail view in the Tauk Web UI.

Conclusion

In the preceding sections, we went over how to create a new Selenium suite in Python, integrate it with Tauk , and setup Github workflows. The code for this tutorial is stored in the repository https://github.com/thetauk/selenium-github-actions. This allows you to leverage Github Actions to generate Tauk reports for your existing Selenium suite.

As always, if you have any questions about this blog post, you can reach out to us by joining our Discord server:

Join the Tauk Discord Server!