Structuring a Python Test Automation Framework for Web & API apps with Sphinx Documentation

When developing a Python test automation framework, maintaining a well-structured project is crucial for scalability and maintainability. Additionally, integrating Sphinx for documentation ensures that the project remains well-documented. This article outlines an effective folder structure for a test automation framework and how to set up Sphinx for documentation generation.

Project Directory Structure

A typical Python test automation framework structured for Sphinx documentation can follow this hierarchy:

project_root/
│– src/
│ ├── pages/
│ │ ├── base_page.py
│ │ ├── login_page.py
│ │ ├── home_page.py
│ ├── utils/
│ │ ├── logger.py
│ │ ├── config_loader.py
│ ├── api/
│ │ ├── api_client.py
│ │ ├── endpoints.py
│– tests/
│ ├── ui/
│ │ ├── test_login.py
│ │ ├── test_cart.py
│ ├── api/
│ │ ├── test_booking.py
│– config/
│ ├── settings.yaml
│ ├── test_data.json
│– test_data/
│ ├── users.xlsx
│– docs/
│ ├── conf.py
│ ├── index.rst
│ ├── api_reference.rst
│ ├── test_docs.rst
│– conftest.py
│– pytest.ini
│– requirements.txt
│– README.md
│– Makefile

Setting Up Sphinx for Documentation

Sphinx is a powerful tool for generating project documentation in various formats, including HTML and PDF.

Step 1: Install Sphinx

Ensure you have Sphinx installed in your Python environment:

pip install sphinx

Step 2: Initialize Sphinx

Navigate to the docs/ directory and initialize Sphinx:

sphinx-quickstart
Follow the prompts to configure your documentation project.

Step 3: Configure conf.py

Modify docs/conf.py to include the project source path:

import os
import sys
sys.path.insert(0, os.path.abspath(‘../src’))
Enable autodoc to automatically generate documentation from docstrings:

extensions = [‘sphinx.ext.autodoc’, ‘sphinx.ext.napoleon’]

Step 4: Document Your Code

Use docstrings in your Python modules to generate documentation. Example:

class LoginPage:
“””
Represents the login page of the application.

Attributes:
    driver: WebDriver instance used for interactions.
"""
def __init__(self, driver):
    """Initializes LoginPage with a WebDriver instance."""
    self.driver = driver

Step 5: Build Documentation

Run the following command in the docs/ directory:

make html
This generates HTML documentation in _build/html/, which you can view in a browser.

Conclusion

By organizing the framework into modular directories and integrating Sphinx for documentation, the test automation framework remains well-structured and maintainable. This approach ensures that new team members can quickly understand the framework and its components.