Python project structure for automated tests

Reading time ~4 minutes

Once the Python automated tests development is started, need to define a project/repository structure. Usually, each engineer does it in his/her own way. But do we have some common template?

Before we’ll look for a template of the project’s structure, let’s look into ways we can structure the code.


A module is a file containing Python definitions and statements. The file name is the module name with the suffix .py appended.

For instance,


The file is a module called login_page. If this module is required, it can be imported with

import login_page


A package is a directory which contains one or more Python’s modules and file. If there is a hierarchy of directories and each of them has to be a package, the has to be added to each directory.

For instance,

└── pages

The pages directory is a Python package. And it’s possible to import modules under pages package. For instance, if login module is required, it can be imported with

from pages import login

Structuring the project

The following project structure is a minimal common template for any test automation project:

├──               <- contains all information need to konw to work with this code
├── my_app_tests            <- is a main package for your code including automated tests
├── requirements.txt        <- contains all required dependencies (packages) of yuor project
└── tests                   <- is a main package for unit tests (not for automated tests)

What are benefits of this structure?

First of all, this is a common template used by Python community. This means that a lot of people of Python’s world could understand your code quickly. As a result, any knowledge transfer will go faster and you will save a lot of time and efforts.

Additionally, this will simplify integration with the Python’s tooling. Any new integration of static code analysis or whatever you need will take significantly less time.

Next one, this structure allows easily create a Python package and distribute with PYPI etc. Here only needs to create a configuration for setuptools. This can be useful if some common logic has to be shared between several projects.


Please take in mind that the proposed structure is the minimal one. And you could extend this if needed. Anyway, don’t try to reinvent the wheel.

Further reading

Selenium: large files upload

Do you know how does Selenium upload files? Is there a way to upload a huge file without errors?
Continue reading