Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Beliagal/qa-report-automation/llms.txt

Use this file to discover all available pages before exploring further.

This guide is intended for developers who want to run Valoraclick QA Tool directly from the Python source, contribute to the codebase, or build a custom executable for distribution. If you are a QA analyst who simply wants to generate test reports, you do not need this guide — head to the Quickstart page and download the pre-built QA_Tool_v2.7.exe instead.

​
Prerequisites

Before you begin, ensure the following are available on your machine:
  • Python 3.13 or later — the project targets Python 3.13+. Download from python.org.
  • Windows OS — required for the pywin32 dependency that powers the Google Drive .lnk shortcut resolution. The application will not fully function on macOS or Linux.
  • Git — needed to clone the repository. Download from git-scm.com.

​
Developer Setup

1

Clone the Repository

Open a terminal (PowerShell or Command Prompt) and clone the project from GitHub, then navigate into the project directory:
git clone https://github.com/Beliagal/qa-report-automation.git
cd qa-report-automation
2

Create and Activate a Virtual Environment

Create an isolated Python virtual environment inside the project folder and activate it. Using a virtual environment keeps the project dependencies separate from your system Python installation:
python -m venv .venv
.venv\Scripts\activate
Once activated, your terminal prompt will be prefixed with (.venv), confirming the environment is live.
3

Install Dependencies

Install all pinned dependencies from requirements.txt:
pip install -r requirements.txt
This installs the GUI framework, PDF engine, image library, build tooling, test runner, and the Windows platform bindings in one step.
4

Run the Application

Launch the tool directly from source:
python main.py
The CustomTkinter window will open maximized. All features — metadata form, step logging, real-time preview, PDF export, and Google Drive CSV backup — are fully available when running from source on Windows.

​
Key Dependencies

The GUI framework for the entire application. CustomTkinter extends Python’s standard tkinter library with modern, dark-themed widgets that render natively on Windows. It powers the scrollable control panel, entry fields, combo boxes, text areas, and action buttons.
The PDF generation engine. fpdf2 is used by PDFService to construct the test report — laying out metadata headers, step-by-step tables with Pass/Fail color coding, and embedded screenshot images — and write the result to a .pdf file chosen by the user. The README incorrectly references ReportLab; the actual engine throughout the source is fpdf2.
Python’s image processing library. Pillow handles opening, decoding, and resizing PNG and JPEG screenshots before they are embedded into the PDF report by fpdf2. It also provides image format validation when a user selects a file via the image picker.
The build tool used to package the application into a standalone Windows executable (QA_Tool_v2.7.exe). PyInstaller bundles the Python interpreter, all dependencies, and application assets into a single distributable file that end-users can run without any Python installation.
The test runner for the project’s automated test suite. Pytest is used during development to run unit and integration tests against the application’s service layer (PDF generation, CSV export, session persistence). It is not required at runtime.
Windows-specific Python bindings for the Win32 API. CSVService uses pywin32 to resolve .lnk Windows shortcut files, allowing the tool to locate your local Google Drive sync folder automatically and write the CSV backup without requiring any manual path configuration from the user.
pywin32 is a Windows-only package and cannot be installed on macOS or Linux. If you attempt to run the application on a non-Windows system, the Google Drive CSV backup feature will be unavailable. The rest of the application — PDF generation, screenshot embedding, session persistence — may function in principle, but the project is only officially supported and tested on Windows.

​
Project Structure

Once the repository is cloned, the key source files are:
FilePurpose
main.pyEntry point — instantiates and runs TestingApp
gui.pyTestingApp class — all CustomTkinter UI logic
services.pyPDFService (fpdf2 report generation) and CSVService (Google Drive backup)
models.pyReportData — the data model holding metadata and test steps
logic.pyPure utility functions: date validation and Pass/Fail color lookup
config.jsonRuntime configuration — tester names list and current version string
sesion_testing.jsonAuto-generated session file written after each step (not committed)

​
Configuration File

The config.json file at the project root controls two runtime settings: 
{
    "testers": [
        "Tester General",
        "QA Lead"
    ],
    "version_actual": "1.0.0"
}
KeyTypeDescription
testersarray of stringsList of recognized tester names for the project
version_actualstringCurrent application version string

​
Building the Executable

Once your development environment is set up and working, you can compile the application into a distributable .exe using PyInstaller. See the Building the Executable guide for the full build command, asset bundling configuration, and packaging best practices.

Build docs developers (and LLMs) love

Get started for freeTalk to us