Sloth Python

🛠️ Installation

1. Create and activate a virtual environment

Windows (PowerShell):

py -3.11 -m venv .venv
.\.venv\Scripts\activate

Linux/macOS (bash/zsh):

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies

Choose one package manager after activating the virtual environment:

Using pip:

python -m pip install -r requirements.txt

Using uv:

uv pip install -r requirements.txt

This installs the packages used by Robot Framework, pytest, Playwright, and the supporting demo utilities.

3. Install Playwright browsers

playwright install

⚙️ Configuration

Runtime settings are read from environment variables. Shared test and AI-generation settings are centralized in config/config.py; provider-specific ai_stock settings are documented in ai_stock/readme.md.

Shared URLs

Variable	Default	Purpose
TANGERINE_URL	https://www.tangerine.ca/en/personal	Base URL for Tangerine UI tests
DEEP_SEEK_URL	https://api.deepseek.com	DeepSeek-compatible API endpoint
OPENAI_URL	https://api.openai.com/v1	OpenAI-compatible API endpoint

UI and Playwright

Variable	Default	Purpose
UI_LOCALE	en-US	Browser locale for Playwright tests
SLEEP_TIME	1	Generic delay used by selected fixtures
COOKIE_BANNER_TIMEOUT_SECONDS	5	Timeout for Tangerine cookie-banner handling
PW_HEADLESS	false	Run Playwright headlessly (1/0, true/false, yes/no, on/off)

AI test generation

Variable	Default	Purpose
AI_GEN_MODEL	gpt-4.1	LLM model identifier
AI_GEN_BASE_URL	OPENAI_URL	API endpoint used by the generator
AI_GEN_MAX_DOM_CHARS	12000	Maximum DOM characters sent to the model
AI_GEN_OUTPUT_DIR	temps/ai/generated_playwright	Directory for generated tests

Set the required provider key, such as OPENAI_API_KEY, through the environment before using AI features. Never commit credentials to the repository.

Optional qTest integration

Variable	Default	Purpose
QTEST_BASE_URL	https://yourcompany.qtestnet.com	qTest API base URL
QTEST_PROJECT_ID	123456	qTest project identifier
QTEST_API_TOKEN	your_token_here	qTest authentication token

Quick local check for shared settings:

python -m config.config

🐳 Docker and Database

The local MySQL service is defined in docker_compose.yml. It stores data in the named mysql-data Docker volume, so stopping or recreating the container does not remove the database.

Start and manage MySQL

Run these commands from the repository root:

# Start MySQL in the background
docker compose -f docker_compose.yml up -d mysql

# Check container and health status
docker compose -f docker_compose.yml ps mysql

# Follow MySQL startup and server logs
docker compose -f docker_compose.yml logs -f mysql

# Stop MySQL while retaining its data volume
docker compose -f docker_compose.yml stop mysql

# Start an existing stopped MySQL container
docker compose -f docker_compose.yml start mysql

The service is exposed at localhost:3306 by default. Set SLOTH_MYSQL_PORT before starting Compose to use another host port.

Connect to the local database

The default local connection values are:

Setting	Value
Host	127.0.0.1
Port	3306
Database	slothdb
User	slothuser
Password	slothpass123

Override these local defaults with SLOTH_MYSQL_DB, SLOTH_MYSQL_USER, SLOTH_MYSQL_PASSWORD, and SLOTH_MYSQL_ROOT_PASSWORD before the first docker compose ... up command. Do not use the default passwords outside local development.

For Python database helper usage and parameterized query examples, see utils/data_base/README.md.

🏃 Running Tests

Run commands from the repository root. Choose the narrowest workflow that matches the change you are validating.

Run all pytest and Robot tests

Run both test frameworks and return a failure if either suite fails:

$pytestExit = 0
$robotExit = 0

python -m pytest
$pytestExit = $LASTEXITCODE

python -m robot --outputdir temps/robot_all robot_tests/
$robotExit = $LASTEXITCODE

if ($pytestExit -ne 0 -or $robotExit -ne 0) {
   exit 1
}

Pytest results use the configured Allure output directory; Robot reports are written to temps/robot_all/.

Pytest suites

pytest covers the unit, API, and Playwright UI suites.

# Full pytest run
python -m pytest

# Fast unit and API smoke checks
python -m pytest -m "unit or api"

# One file / one test
python -m pytest pytest_tests/unit/test_csv_reader.py -q
python -m pytest pytest_tests/unit/test_csv_reader.py::test_read_csv_to_list_converts_numeric_cells_to_int -q

# UI tests
python -m pytest -m ui
python -m pytest pytest_tests/ui/tangerine -q

Playwright recording and debugging

Use Playwright Codegen to record actions and bootstrap UI tests:

python -m playwright codegen https://www.tangerine.ca/en/personal

Run a UI test visibly for debugging. Configure browser visibility and slow motion through environment variables:

$env:PW_HEADLESS = "false"
$env:PW_SLOW_MO = "200"
python -m pytest pytest_tests/ui/tangerine/test_codegen.py -q

• PW_HEADLESS=false opens a visible browser
• PW_SLOW_MO=200 slows Playwright actions by 200 milliseconds

This project uses Python pytest + Playwright, so run tests with python -m pytest ..., not npx playwright test.

For AI-based test generation, see AI-Generated UI Test Scripts.

Robot Framework suites

Robot demos live under robot_tests.

# All Robot suites
python -m robot --outputdir temps/robot_all robot_tests/

# Calculator demo
python -m robot --outputdir temps/robot_calculator robot_tests/calculator/

# Tangerine Playwright suite
python -m robot --outputdir temps/robot_tangerine_playwright robot_tests/ui/

# Dry run (syntax and keyword wiring only)
python -m robot --dryrun --outputdir temps/robot_tangerine_playwright_dryrun robot_tests/ui/

Robot writes output.xml, log.html, and report.html to the selected directory under temps/.

For Robot failures:

• failure screenshots are saved under <outputdir>/artifacts/playwright/screenshots/
• failure videos are saved under <outputdir>/artifacts/playwright/videos/
• for example, --outputdir temps/robot_all produces temps/robot_all/artifacts/playwright/
• screenshot/video links appear in Robot log.html and report.html
• passed-test videos are deleted to keep artifacts small

Allure results

Generate and serve an Allure report after a pytest run:

python -m pytest --alluredir=temps/allure-results --clean-alluredir
allure serve temps/allure-results

For pytest UI runs, Playwright records per-test video and keeps/attaches it only for failed tests. Videos are written under temps/playwright-videos/tangerine_playwright/.

The Tangerine Robot keyword libraries also bootstrap the project root import path automatically, so -P is typically not needed.

🤖 Self-Healing Framework (Playwright)

The Playwright UI tests use fallback locators and DOM similarity matching to recover from selector changes.

Try it

Install the Playwright browsers once, then run a Tangerine UI test from the repository root:

python -m playwright install
python -m pytest .\pytest_tests\ui\tangerine\test_signinpage.py -q

This opens the sign-in flow through the shared UI fixture and self-healing locator support. Set PW_HEADLESS=false to watch the browser, or add PW_SLOW_MO=200 to slow Playwright actions while learning the flow.

Components

Component	Responsibility
self_healing/element_finder.py	Tries the primary locator and configured fallbacks
self_healing/dom_similarity.py	Finds likely replacements in the current page DOM
self_healing/self_healing.py	Coordinates recovery and optional locator updates
self_healing/locator_store.py	Loads and persists keyed locator definitions
pytest_tests/ui/locators/	Stores the Tangerine locator JSON files

Recovery flow

1. Try the primary locator and its fallback strategies.
2. If they fail, scan the page DOM for a similar candidate.
3. Reject candidates below the similarity threshold.
4. Build a locator from the best candidate.
5. Update the primary locator when auto_update=True.

This reduces manual maintenance after small UI changes while keeping recovery decisions visible in the test logs.

Robot Framework integration

The Robot Tangerine suite uses the same locator store through robot_tests and currently supports these keys:

• tangerine.login
• tangerine.signup

Robot integration enables locator updates through SELF_HEAL_AUTO_UPDATE. Set that constant to False when a run must recover without rewriting locator files.

🤖 AI-Generated UI Test Scripts (Python + Playwright + MCP)

Generate runnable pytest + Playwright scripts from a natural-language goal and live page context.

Generation pipeline

1. Playwright opens the target URL and captures DOM, screenshot, and network context.
2. ai_gen/mcp_context.py packages the browser state into a structured snapshot.
3. ai_gen/prompt_builder.py creates the generation prompt.
4. An OpenAI-compatible model returns Python test code.
5. ai_gen/generator.py normalizes and writes the script to the requested output path.

The command-line entry point is ai_gen/cli.py.

CLI options

Option	Default	Description
--model	AI_GEN_MODEL (gpt-4.1)	LLM model name
--base-url	AI_GEN_BASE_URL	OpenAI-compatible API endpoint
--headless	false	Run context collection headlessly (true/false)

Additional examples

python -m ai_gen.cli `
   --url "https://www.tangerine.ca/app/#/login" `
   --goal "Verify username, password, and submit controls are present" `
   --test-name "test_tangerine_signin" `
   --output "temps/ai/generated_playwright/test_tangerine_signin.py"

python -m pytest -q temps/ai/generated_playwright/test_tangerine_signin.py

Review generated code before committing. DOM input is limited by AI_GEN_MAX_DOM_CHARS, and generated tests are plain pytest files; self-healing must be added explicitly when needed.

Validate the generator with:

python -m pytest -q pytest_tests/ai/test_ai_generation.py

🌱 Skill Spring Learning Lab

skill_spring is the repository's learning and research area: a collection of study tracks, experiments, notebooks, and reusable examples spanning software engineering, AI, and exploratory programming.

Learning paths

Directory	Focus
algorithms/	Algorithms, data structures, problem-solving patterns, and machine learning exercises
concepts/	Practical programming and test-automation concepts, from browser contexts to CI/CD
claude_code/	Claude, MCP, prompting, retrieval, tool use, and agent-oriented research
web_scraping/	Web scraping, browser utilities, networking, and data collection experiments
fun_part/	Small games, creative programs, exploratory utilities, and learning experiments

IDE Setup For skill_spring/claude_code Subprojects

skill_spring is the repository's learning and research area. It contains algorithms, test-automation concepts, web-scraping exercises, and Claude/MCP experiments.

Area	Starting point
Algorithms and data structures	skill_spring/algorithms/
Test-automation concepts	skill_spring/concepts/
Claude, MCP, and agent experiments	skill_spring/claude_code/
Web scraping and small experiments	skill_spring/web_scraping/ and skill_spring/fun_part/

Each runnable subproject carries its own setup instructions. For the Claude/MCP index and notebook guide, see Skill Spring Learning Notes.

📂 Project Structure

sloth-python/
├── ai_gen/                     # AI + MCP prompt-to-test generation
├── ai_stock/                   # AI-assisted stock analysis and reporting
├── config/                     # Shared runtime configuration
├── load_tests/                 # JMeter, load-runner, and Postman assets
├── pytest_tests/               # Pytest unit, API, UI, DDT, and AI tests
├── robot_tests/                # Robot Framework API, calculator, UI, DDT, and unit suites
├── self_healing/               # Shared Playwright locator-recovery framework
├── skill_spring/               # Learning and research tracks
├── test_data/                  # Test-data creation scripts and fixtures
├── utils/                      # Domain-oriented shared helpers
├── temps/                      # Generated reports, logs, videos, and temporary results
├── .github/workflows/          # GitHub Actions CI/CD definitions
├── .vscode/                    # Workspace settings
├── pyproject.toml              # Python tooling and pytest configuration
├── readme.md                   # Project documentation
├── requirements.txt            # Python dependencies
├── security.md                 # Security policy
└── uv.lock                     # uv dependency lock file

Feature Guides

Area	Guide
Self-healing locators	Self-Healing Framework
AI-assisted test generation	AI-Generated UI Test Scripts
Stock analysis	AI Stock Architecture
Database utilities	Database Utilities
Learning material	Skill Spring Learning Notes

🎓 Best Practices & Patterns

Keep changes focused, reusable, and easy to validate.

Testing and UI Automation

• Organize by behavior: Keep pytest suites under pytest_tests/ and Robot suites under robot_tests/, grouped by unit, api, ui, ddt, and ai where applicable.
• Use shared fixtures and page objects: Centralize setup, browser lifecycle, and page interactions instead of duplicating them in individual tests.
• Prefer stable selectors: Reuse shared locator definitions and self-healing helpers for Playwright flows when selector recovery is appropriate.
• Parameterize repeated scenarios: Use fixtures, markers, and parameterization to keep test coverage broad without duplicating test logic.

Python and Configuration

• Keep code typed and readable: Use clear names, type hints, focused functions, and useful docstrings.
• Reuse shared utilities: Prefer helpers in utils/, config/, and self_healing/ before introducing duplicates.
• Externalize settings: Read URLs, feature flags, and integration settings from environment variables with safe defaults.
• Protect secrets: Never commit API keys, tokens, or credentials; use environment variables and keep sensitive values out of logs.
• Format and lint consistently: Run Ruff checks and formatting before finalizing substantial Python changes.

AI and Learning Workflows

• Review generated code: Treat ai_gen/ output as a starting point and validate it with focused pytest runs before committing.
• Keep research reproducible: Follow the project README and notebook instructions under skill_spring/ for learning experiments.
• Prefer explainable analysis: Keep stock-analysis conclusions traceable to market data, news, and strategy inputs.

CI/CD and Reporting

• Validate in stages: Run focused tests locally, then the smoke or regression workflow as the change requires.
• Keep CI headless: Install Playwright browsers and use PW_HEADLESS=1 in automated UI runs.
• Preserve diagnostics: Use Allure, Robot HTML reports, screenshots, videos, and uploaded artifacts to investigate failures.

❤️ Support & Feedback

If Sloth Python helps you learn, automate, or experiment, your support helps keep the project maintained and growing.

Ways to help

• Sponsor the project to support maintenance and new examples.
• Report reproducible bugs or request features through GitHub Issues.
• Ask questions or discuss ideas through GitHub Discussions.
• Contribute tests, documentation, algorithms, automation examples, or AI tooling.

Thank you for helping make the project more useful for the next person who finds it.

Include useful context

For issues and questions, include:

• Python version, operating system, and relevant package or browser versions
• The smallest reproduction or clear steps to reproduce
• Expected and actual behavior
• Relevant command output or a redacted traceback
• The affected area, such as pytest, robot, ai_gen, ai_stock, or skill_spring

Report security vulnerabilities through the Security Policy, not a public issue. Never include API keys, tokens, credentials, or other sensitive values in reports.

📝 License

Sloth Python is distributed under the MIT License.

Permissions

Use	Permitted
Commercial use	Yes
Private use	Yes
Modification	Yes
Distribution	Yes

Condition

Redistributions must retain the applicable copyright and license notices.