Skip to content

About

AI stock and it's test automation with Python, Pytest, Playwright, Robot, MCP and AI...

Topics

Resources

Contributing

Stars

4 stars

Watchers

3 watching

Forks

Latest commit

Β 

History

1,814 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Sloth Python

πŸ“š Documentation Index

Find project guides, feature documentation, development references, and learning material by topic. Several feature guides now live beside the application documentation that owns them.

Project guides

Product and feature guides

  • Alert Center β€” alert rules, evaluation, notifications, and rollback behavior.
  • Email notifications β€” SMTP setup, recipient groups, routing, and delivery diagnostics.
  • Stock autocomplete catalog β€” local search, remote refresh, and bundled catalog maintenance.
  • Analysis Context Pack β€” analysis inputs, data-quality metadata, prompt summaries, and public overview.
  • Trading strategies β€” built-in YAML strategies, custom definitions, and strategy-writing examples.

Development and testing

Repository collaboration and security

These documents guide contributors and coding assistants; they are not product documentation.

Learning material

The Claude Agent SDK folder also contains individual feature examples, such as session stores and plugins.

πŸ“‘ Table of Contents

πŸ› οΈ Installation

The root application requires Python 3.14 or newer. CI currently validates Python 3.14; later versions are not yet covered by the test configuration.

One-command DSA setup and verification with Just

Install Casey/just, Python 3.14, Node.js 24.15+ (24 LTS), npm 10+, and uv (python -m pip install uv). Then run:

just verify

This installs locked Python/npm dependencies and DSA browser assets, builds the frontend, and runs Python unit tests, isolated DSA API tests, Vitest, Playwright, and Cypress. It does not run unrelated demo UI suites. Browser test servers are started and stopped automatically; failures stop the command with a nonzero exit.

Run just dsa to set up and launch DSA at http://127.0.0.1:8000, or just to list recipes. No virtual-environment activation is needed. Provider-backed analysis still needs your own configuration; setup never overwrites .env. See the Just workflow guide for individual commands, prerequisites, and test isolation details.

1. Create and activate a virtual environment

Windows (PowerShell):

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

Linux/macOS (bash/zsh):

python3.14 -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 utils/config; 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/ai_gen 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 utils.config.config

🐳 Docker and Database

The local MySQL service is defined in docker/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 Docker services

Run these commands from the repository root. server hosts the Web/API app, analyzer runs scheduled analysis, and mysql starts the local database.

# Rebuild the application images without using the build cache
docker compose -f docker/docker-compose.yml build --no-cache server analyzer

# Start the Web/API and scheduled-analysis services
docker compose -f docker/docker-compose.yml up -d server analyzer

# Start every service, including MySQL
docker compose -f docker/docker-compose.yml up -d

# Follow application logs
docker compose -f docker/docker-compose.yml logs -f server analyzer

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

# Follow MySQL logs
docker compose -f docker/docker-compose.yml logs -f 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. For commands covering pytest, Robot Framework, Vitest, and Cypress, see the testing guide.

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/test-results-robot tests/robot_tests/ui_suites/
$robotExit = $LASTEXITCODE

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

Pytest results are written to temps/test-results-pytest/; Robot reports are written to temps/test-results-robot/.

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 tests/pytest_tests/test_csv_reader.py -q
python -m pytest tests/pytest_tests/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 tests/pytest_tests/ui_suites/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 tests/pytest_tests/ui_suites/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 tests/robot_tests/ui_suites/.

# All Robot suites
python -m robot --outputdir temps/test-results-robot tests/robot_tests/ui_suites/

# Tangerine Playwright suite
python -m robot --outputdir temps/test-results-robot tests/robot_tests/ui_suites/

# Dry run (syntax and keyword wiring only)
python -m robot --dryrun --outputdir temps/test-results-robot tests/robot_tests/ui_suites/

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/test-results-robot produces temps/test-results-robot/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/test-results-pytest --clean-alluredir
allure serve temps/test-results-pytest

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 .\tests\pytest_tests\ui_suites\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
tests/pytest_tests 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 under tests/robot_tests/ui_suites uses the same repository-relative locator store as pytest. Import shared helpers with from utils.self_healing import click, find_element. The keyword library bootstraps the repository root before importing these helpers, so -P is not required. The locator store 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. utils/ai_gen/mcp_context.py packages the browser state into a structured snapshot.
  3. utils/ai_gen/prompt_builder.py creates the generation prompt.
  4. An OpenAI-compatible model returns Python test code.
  5. utils/ai_gen/generator.py normalizes and writes the script to the requested output path.

Run the command-line entry point with python -m utils.ai_gen.cli. Relative --output paths are resolved from the repository root, not utils/ or the current working directory. Absolute paths are preserved.

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

Windows (PowerShell):

python -m utils.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

Linux/macOS (bash/zsh):

python -m utils.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

For Google search, use single quotes around the goal in PowerShell so the double quotes around "Amazon" are preserved:

python -m utils.ai_gen.cli `
   --url "https://www.google.com" `
   --goal 'Verify Google search by searching for "Amazon" and pressing Enter' `
   --test-name "test_google_search_for_amazon" `
   --output "temps\ai\generated_playwright\test_google_search_for_amazon.py"

Generated tests that accept page: Page use the page fixture from pytest-playwright, included in requirements.txt. If pytest reports fixture 'page' not found, install the project dependencies in the same Python environment used to run pytest:

python -m pip install -r requirements.txt
python -m playwright install chromium
python -m pytest -q temps/ai/generated_playwright --browser chromium

The plugin runs headlessly by default; add --headed to watch the browser. Existing Tangerine pytest suites keep their separate tangerine_homepage fixture.

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 tests\unit\test_ai_generation.py

πŸ“ˆ Daily Stock Analysis (DSA) User Guide

DSA combines market data, technical analysis, news, and language models to produce stock-analysis reports. It also includes a Web workspace for chat, backtesting, alerts, decision signals, and report history. These features are decision-support tools, not investment advice or automated trading.

Overview

Area What it provides
Analysis Reports for A-shares, Hong Kong stocks, U.S. equities, and supported Japan/Korea symbols
Data and research Quotes, historical bars, technical indicators, fundamentals, news, and source-quality context where available
Web workspace Watchlists, reports, history, strategy chat, backtesting, alerts, and settings
Operations CLI, FastAPI/Web service, local scheduler, Docker, and optional email delivery

Coverage varies by market and provider. Japan (.T) and Korea (.KS / .KQ) rely mainly on YFinance for daily bars, basic or delayed quotes, and technical indicators. Real-time quotes, complete symbol lists, full fundamentals, and region-specific market data may be unavailable. Missing data is not a zero value or a market signal.

Trading strategies

The current built-in strategies are YAML files in strategies/; Stock Analyzer is no longer a built-in strategy. Custom strategies can be loaded from AGENT_SKILL_DIR as YAML files or Markdown skill bundles. See the trading strategies guide for examples and configuration.

Quick start

From the repository root, install dependencies, copy .env.example to .env, and configure STOCK_LIST plus at least one model provider key. The LLM provider guide covers provider choices; .env.example lists supported settings.

Start the Web/API service:

python main.py --serve-only

Open http://127.0.0.1:8000; the interactive API reference is at /docs. For a Web-only development server and frontend commands, see the DSA Web guide.

Run modes

Goal Command
Analyze the configured watchlist python main.py
Analyze selected symbols python main.py --stocks 600519,hk00700,AAPL
Review market conditions python main.py --market-review
Run scheduled analysis python main.py --schedule
Start Web/API without an initial analysis python main.py --serve-only
Start Web/API and run an analysis python main.py --serve
Run the local Web launcher python webui.py

Deployment and configuration

Docker Compose defines separate server and analyzer services. Start the Web/API service with docker compose -f docker/docker-compose.yml up -d server; use the analyzer service for scheduled analysis. Persist the database, reports, and writable configuration file if settings must survive container replacement. See docker/docker-compose.yml.

STOCK_LIST in .env controls the analysis universe. Search and market-data sources use provider keys and fallbacks configured through environment variables or Web Settings. Email is the supported notification transport; configure it only if report or alert delivery is needed. Detailed feature behavior is in the LLM provider guide and DSA Web feature guides.

The Web/API service has no built-in authentication. Keep it on a trusted private network or place it behind an authenticated HTTPS reverse proxy; do not expose it directly to the public Internet.

API and Web references

🌱 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/
β”œβ”€β”€ utils/ai_gen/               # AI + MCP prompt-to-test generation
β”œβ”€β”€ ai_stock/                   # AI-assisted stock analysis and reporting (storage, templates, cache under ai_stock/stock_data)
β”œβ”€β”€ apps/                       # dsa-web (React/Vite frontend), dsa-web-playwright-tests, and dsa-web-cypress-tests
β”œβ”€β”€ 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
β”œβ”€β”€ utils/                      # Domain-oriented shared helpers (shared config lives in utils/config/config.py)
β”œβ”€β”€ temps/                      # Generated reports, logs, videos, static build output, and temporary results
β”œβ”€β”€ .github/workflows/          # GitHub Actions CI/CD definitions
β”œβ”€β”€ .vscode/                    # Workspace settings
β”œβ”€β”€ pyproject.toml              # Python tooling and pytest configuration
β”œβ”€β”€ readme.md                   # Project overview and quick-start guide
β”œβ”€β”€ requirements.txt            # Python dependencies
β”œβ”€β”€ contributing.md            # Repository development conventions and workflows
└── uv.lock                     # uv dependency lock file

πŸŽ“ Best Practices & Patterns

Keep changes focused, reusable, and easy to validate.

Testing and UI Automation

  • Organize by behavior: Keep pytest suites under tests/pytest_tests and Robot suites under tests/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/, 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 utils/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.

🧭 Repository Development Guide

Follow the repository conventions and focused development workflow: preserve existing contracts, update the relevant documentation, and validate the affected areas. The detailed guidance covers collaboration assets, project architecture, common commands, validation by change type, stability guardrails, review workflows, and delivery practices.

See contributing.md for the complete guide.

❀️ 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.

Sponsor on GitHub

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 privately to the project maintainers, not through 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.

About

AI stock and it's test automation with Python, Pytest, Playwright, Robot, MCP and AI...

Topics

Resources

Contributing

Stars

4 stars

Watchers

3 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages