Testing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• test_telegram.py
• notification_service.py
• pos_app.py
• config.example.json
• install_dependencies.bat
• README_Notifications.txt

This guide provides instructions and explanations for testing the various components of the pos-tioadan project. The project utilizes a combination of a dedicated configuration test script for the Telegram notification service and manual verification procedures for the main Point of Sale (POS) application. The primary automated test is test_telegram.py, designed to ensure the notification system is correctly configured before deployment.

The testing strategy focuses on two main areas: ensuring reliable connectivity with the Telegram API for notifications and verifying the core business logic of the POS application through manual checks. This guide covers the setup, execution, and interpretation of these tests.

Testing the Telegram Notification Service

The project includes a standalone script, test_telegram.py, to verify the configuration and connectivity of the Telegram notification service. This script is the primary method for ensuring that out-of-stock alerts and daily reports can be sent successfully.

Sources: test_telegram.py, README_Notifications.txt

Prerequisites

Before running the test, a config.json file must be created in the root directory. This file should be a copy of config.example.json with the placeholder values replaced with actual credentials.

The test script specifically requires the telegram object to be correctly populated.

Key	Parent	Description	Example Value	Source
bot_token	telegram	The API token for your Telegram bot, obtained from @BotFather.	"123456789:ABC..."	config.example.json:3
chat_id	telegram	The unique identifier for the target chat where notifications will be sent.	"987654321"	config.example.json:4

The script will exit with an error if these values are missing or still contain default example strings.

Sources: test_telegram.py:126-137

Test Execution Flow

The test_telegram.py script performs a two-step verification process. It first validates the bot token and then attempts to send a test message.

The following diagram illustrates the execution flow of the test_telegram.py script.

Step 1: Bot Token Validation

The script first validates the bot_token by making a GET request to the Telegram API's /getMe endpoint.

• Endpoint: https://api.telegram.org/bot<bot_token>/getMe
• Purpose: To get basic information about the bot. A successful response confirms the token is valid.
• Success: If the response JSON contains "ok": true, the script prints the bot's name and username.
• Failure: If the token is invalid, the API returns an error description which is printed to the console, and the script terminates.

Sources: test_telegram.py:32-46

Step 2: Test Message Delivery

If the token is valid, the script proceeds to send a test message to the configured chat_id by making a POST request to the /sendMessage endpoint.

• Endpoint: https://api.telegram.org/bot<bot_token>/sendMessage
• Payload: A JSON object containing chat_id, text, and parse_mode.
• Test Message: The script sends a pre-formatted message mimicking a real "out of stock" alert to confirm that the bot can send messages to the specified chat.

# test_telegram.py:65-73
test_message = (
    "⚠️ ALERTA: Producto agotado\n\n"
    "📦 Producto: BALERO NISSAN\n"
    "🔑 Clave: TRA-200245\n"
    "🏷️ Categoría: BALERO IZQUIERDO\n"
    "🏢 Marca: TRACKONE\n\n"
    "⏰ Fecha y hora: 2025-12-27 14:30:00\n"
)

• Success: If the message is sent successfully, the API returns the message_id of the new message.
• Failure: Common failures include "chat not found". In this case, the script provides a helpful tip suggesting the user start a conversation with the bot first.

The sequence diagram below shows the interactions between the script and the Telegram API.

Manual Testing of the POS Application

The main POS application, pos_app.py, does not have an automated test suite. Its functionality must be verified through manual testing. The application is monolithic, with UI and database logic tightly coupled, making manual, user-driven testing the most practical approach.

Sources: pos_app.py, CLAUDE.md

Key Areas for Manual Testing

1. Sales Workflow

• Add to Cart: Scan or enter a product's "Clave" or "Código de barras". Verify that partial matches bring up a selection dialog.
• Stock Validation: Attempt to add more units of a product to the cart than are available in stock. The system should show a "Stock Insuficiente" warning.
• Edit Cart: Double-click an item in the cart to edit its quantity or apply a special price. Verify that stock limits are still respected.
• Remove from Cart: Select an item and click "Quitar Selección".
• Checkout: Click "Pagar". Verify that inventory quantities are correctly decremented in the "Entrada y Busqueda de Inventario" tab.
• Receipt Generation: After checkout, verify that a receipt preview appears and that the PDF can be saved to the Desktop\recibos folder.

Sources: pos_app.py:1003-1044, pos_app.py:1210-1288

2. Inventory Management

• Add Product: Use the "Escanéa código para meter/sumar inventario" input. If a product doesn't exist, the system should prompt to create a new one.
• Increment Stock: Scan an existing product's barcode in the inventory tab to increment its quantity by one.
• Edit Product: Double-click a product in the inventory list or use the "Editar Producto" button to open the edit dialog. Change all fields and save. Verify that barcode (Clave) uniqueness is enforced.
• Delete Product: Select a product and click "Eliminar Producto". Confirm the action and verify the product is removed.
• Import from XLSX: Use the "Importar XLSX" button. Test with a correctly formatted Excel file. Verify that new products are added and existing products are updated. Check for error reporting on invalid rows.
• Clear Database: Use the "Limpiar BD" button. The system requires a two-step confirmation, including typing "ELIMINAR", to prevent accidental data loss. Verify that all products and sales are deleted after confirmation.

Sources: pos_app.py:1550-1634, pos_app.py:1636-1736, pos_app.py:1335-1448

3. Reporting

• Manual Report Generation: In the "Reportes" tab, enter a date and click "Generar Reporte". Verify a PDF is created in the reports/ directory.
• Report Content: Open the generated PDF. Check that the sales summary, top-selling products, and out-of-stock products sections contain correct data for the specified date.

Sources: pos_app.py:910-1001

Environment and Setup Verification

The install_dependencies.bat script serves as a preliminary test for the environment where the notification service will run.

This diagram shows the steps the batch script takes.

This script verifies:

1. Python Installation: Checks if python is available in the system's PATH.
2. Dependencies: Attempts to install requests and pytz from requirements.txt.
3. Directory Structure: Ensures the logs directory exists.
4. Configuration File: Checks for the presence of config.json and warns the user if it's missing, guiding them to copy the example file.

Successfully running this script is a prerequisite for both running the notification service and executing the test_telegram.py script.
Sources: install_dependencies.bat:11-66