Skip to content

Home

Jump to bottom
Weipeng Zheng edited this page Mar 22, 2026 · 2 revisions

🦥 Sloth Python — Project Wiki

Welcome to the official wiki for Sloth Python — a professional Python test automation and algorithms reference project featuring AI-powered self-healing locators, automated test script generation, Robot Framework suites, and a 200+ algorithm library.

Repository: https://github.com/466725/sloth-python Sponsor: https://github.com/sponsors/466725 Version: v0.1.0 (2026-03-22)

📚 Wiki Pages

Page Description
Home You are here — project overview and navigation
Setup & Installation Full environment setup guide
Running Tests How to run pytest, Robot Framework, and generate reports
Self-Healing Locators How the AI-powered locator recovery works
AI Test Script Generation MCP + OpenAI-driven test generator
Robot Framework Suites Keyword-driven suites, keywords, and artifacts
Algorithm Library Overview of 214 algorithm implementations
Configuration Reference All environment variables and defaults
CI/CD Pipeline GitHub Actions smoke + nightly regression
Contributing How to fork, branch, test, and submit a PR

🎯 What Is Sloth Python?

Sloth Python is a reference-quality test automation and algorithms project built with Python. It demonstrates real-world professional patterns across:

  • ✅ pytest + Playwright UI test automation with Page Object Model
  • ✅ Robot Framework keyword-driven test suites
  • ✅ Self-healing locators — tests that repair broken selectors automatically
  • ✅ AI test generation — turn a natural-language goal into a running test file
  • ✅ 214 algorithm implementations across 10 categories
  • ✅ GitHub Actions CI/CD — smoke on every PR, nightly full regression

🚀 Quick Start (5 minutes)

# 1. Clone
git clone https://github.com/466725/sloth-python.git
cd sloth-python

# 2. Create virtual environment
python -m venv .venv
.venv\Scripts\activate          # Windows
source .venv/bin/activate       # Linux/Mac

# 3. Install dependencies
pip install -r requirements.txt
playwright install

# 4. Run smoke tests
pytest -m "unit or api"

# 5. Run Robot Framework calculator suite
python -m robot --outputdir temps robot_demos/calculator/

🏗️ Project Structure

sloth-python/
├── pytest_demo/
│   ├── ai_generation/                  # AI test script generator (MCP + OpenAI)
│   ├── self_healing/                   # Self-healing locator framework
│   ├── locators/                       # signinpage.json, signuppage.json
│   └── tests/
│       ├── unit/                       # Unit tests (config, csv_reader, locator_store)
│       ├── api/                        # API tests (DeepSeek/OpenAI)
│       ├── ui/tangerine_playwright/    # Playwright UI tests
│       └── AI/generated_playwright/   # AI-generated test output
│
├── robot_demos/
│   ├── calculator/                     # Data-driven + keyword-driven Robot suite
│   └── tangerine_playwright/           # Playwright UI suite (custom Python keywords)
│
├── algorithms/                         # 214 implementations across 10 categories
├── utils/                              # config.py, constants.py, csv_reader.py
├── fun_part/                           # Misc demos and educational examples
├── .github/
│   ├── workflows/ci.yml                # GitHub Actions CI/CD
│   └── ISSUE_TEMPLATE/                 # Bug, feature, docs, question templates
└── requirements.txt

🧪 Test Suite Overview

pytest suites

Suite Marker Location
Unit tests unit pytest_demo/tests/unit/
API tests api pytest_demo/tests/api/
UI / Playwright ui pytest_demo/tests/ui/tangerine_playwright/
AI generated ui pytest_demo/tests/AI/generated_playwright/ 
pytest -m unit            # Fast unit tests only
pytest -m "unit or api"   # Smoke set
pytest -m ui              # Playwright UI tests (needs browser)
pytest                    # Full suite

Robot Framework suites

Suite Location Keywords
Calculator robot_demos/calculator/ Built-in RF only
Tangerine Playwright robot_demos/tangerine_playwright/ Custom playwright_keywords.py 
python -m robot --outputdir temps robot_demos/calculator/
python -m robot --outputdir temps robot_demos/tangerine_playwright/
python -m robot --outputdir temps robot_demos/     # all suites

🤖 Self-Healing Locators

When a UI element cannot be found, the framework follows this recovery chain:

  1. Primary locator tried first
  2. Fallback locators tried next (stored in JSON per page)
  3. DOM similarity scan performed using fuzzy matching
  4. If a match is found (score ≥ 0.45): test passes and the locator file is auto-updated
  5. Next run uses the healed locator automatically

Locator files:

  • pytest_demo/locators/signinpage.json — login page selectors
  • pytest_demo/locators/signuppage.json — signup page selectors

Self-healing modules:

Module Role
self_healing.py Main entry point
element_finder.py Primary/fallback find logic
dom_similarity.py Fuzzy DOM scanning
locator_store.py Read/write locator JSON files
driver_manager.py Playwright page/context management

The Robot Framework Tangerine suite shares the same locator files but runs in read-only mode (auto_update=False) to avoid silently rewriting locators during Robot runs.

🔧 AI Test Script Generation

Generate a runnable pytest + Playwright test from a natural-language goal:

# Set your API key
$env:OPENAI_API_KEY = "your-key-here"    # Windows PowerShell
export OPENAI_API_KEY="your-key-here"    # Linux/Mac

# Generate a test
python -m pytest_demo.ai_generation.cli \
  --url "https://www.tangerine.ca/en/personal" \
  --goal "Verify homepage loads and Sign In button is visible" \
  --test-name "test_tangerine_homepage"

# Run the generated test
pytest -q pytest_demo/tests/AI/generated_playwright/test_tangerine_homepage.py

How it works end-to-end:

Step Module Action
1 mcp_context.py Opens page in Playwright, captures DOM + screenshot + network events
2 prompt_builder.py Packages context + goal into a structured AI prompt
3 ai_client.py Sends prompt to OpenAI-compatible API
4 generator.py Cleans response, strips markdown fences, validates output
5 paths.py Writes runnable .py file to output directory

Supported AI endpoints:

  • OpenAI (default)
  • DeepSeek: --base-url https://api.deepseek.com
  • Azure OpenAI: --base-url <your-azure-endpoint>

⚙️ Configuration Reference

All settings are centralized in utils/config.py and read from environment variables with safe defaults.

Variable Default Description
TANGERINE_URL https://www.tangerine.ca/en/personal Base URL for Tangerine UI tests
DEEP_SEEK_URL https://api.deepseek.com DeepSeek API base URL
OPENAI_URL https://api.openai.com OpenAI API base URL
PW_HEADLESS true Playwright headless mode (true/false)
UI_LOCALE en-US Browser locale
SLEEP_TIME 1 Generic sleep duration in fixtures
COOKIE_BANNER_TIMEOUT_SECONDS 5 Cookie banner wait time
OPENAI_API_KEY (required for AI gen) API key for test generator
AI_GEN_MODEL gpt-4.1 LLM model to use
AI_GEN_BASE_URL OpenAI endpoint Override for DeepSeek/Azure
AI_GEN_MAX_DOM_CHARS 12000 Max DOM size sent to model
AI_GEN_OUTPUT_DIR pytest_demo/tests/AI/generated_playwright Output folder for generated tests 
# Print all current config values
python -m utils.config

🔄 CI/CD Pipeline

Workflow Trigger What runs
Smoke test Push to master, all PRs pytest -m "unit or api" + Robot calculator suite
Nightly regression 2 AM UTC every day Full pytest + all Robot suites + Allure report generation

Artifacts uploaded per run (downloadable from Actions tab):

  • allure-report/
  • temps/log.html
  • temps/report.html
  • temps/output.xml

🏗️ Algorithm Library (214 implementations)

Category Notable Examples
backtracking/ N-Queens, Sudoku, Minimax, All Permutations, Subsets
divide_and_conquer/ Mergesort, Strassen Matrix, Closest Pair of Points
machine_learning/ KNN, SVM, Decision Tree, Linear/Logistic Regression, Gradient Descent
data_structures/ Binary Tree, Heap, Trie, Linked List, Disjoint Set, Hashing
sorts/ Quicksort, Mergesort, Heapsort, Radix, Counting, Bubble, Shell
searches/ Binary Search, BFS, DFS, A*, Interpolation Search
maths/ Primes, GCD, Fibonacci, 3n+1, Abs, Modular ops
strings/ KMP, Rabin-Karp, Edit Distance, Palindrome, Anagram
conversions/ Decimal↔Binary↔Hex↔Octal, Roman Numerals
traversals/ Inorder, Preorder, Postorder, Level-order

📦 Dependencies

Key packages from requirements.txt:

Package Purpose
pytest Primary test runner
playwright Browser automation
robotframework~=7.4 Robot Framework suites
allure-pytest Allure report integration
openai>=1.0.0 AI test script generation
mcp MCP protocol support
requests HTTP/API testing
scikit-learn, numpy ML algorithm support

🤝 Contributing

  1. Fork the repository on GitHub
  2. Create a branch: git checkout -b feature/your-feature
  3. Make changes — follow PEP 8, add type hints and docstrings
  4. Test locally: pytest -m "unit or api"
  5. Commit: git commit -m "feat: describe your change"
  6. Push + open a Pull Request

Full details: CONTRIBUTING.md

Community standards: CODE_OF_CONDUCT.md

Security issues: SECURITY.md

📋 Changelog

Latest release: v0.1.0 (2026-03-22) — Initial public release

Full changelog: CHANGELOG.md

❤️ Sponsor

If this project is useful to you, please consider sponsoring to support ongoing development:

Sponsor

📬 Quick Links

Resource Link
📦 Repository https://github.com/466725/sloth-python
🐛 Issues https://github.com/466725/sloth-python/issues
💬 Discussions https://github.com/466725/sloth-python/discussions
🚀 Releases https://github.com/466725/sloth-python/releases
⚙️ CI Runs https://github.com/466725/sloth-python/actions
❤️ Sponsor https://github.com/sponsors/466725

Clone this wiki locally