diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..ee7519d --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,22 @@ +name: Tests + +on: + pull_request: + push: + branches: [feature/*] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install dependencies + run: pip install ".[test]" + + - name: Run unit tests + run: pytest tests/utest/ -v \ No newline at end of file diff --git a/Agent/utilities/readme.me b/Agent/utilities/readme.me deleted file mode 100644 index 76ec5bd..0000000 --- a/Agent/utilities/readme.me +++ /dev/null @@ -1,3 +0,0 @@ -here will be all utilities -might include more folder ( helper for dealing with images for example ) -or refactored ( potentially ) diff --git a/Makefile b/Makefile index 1c4b853..909b5f3 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # Makefile pour le projet Robot Framework Agent -.PHONY: help install install-dev test lint format sync-requirements clean +.PHONY: help install install-dev test lint format clean help: ## Afficher cette aide @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' @@ -30,18 +30,6 @@ format-check: ## Vérifier le formatage sans modifier black --check Agent/ tests/ isort --check Agent/ tests/ -sync-requirements: ## Synchroniser requirements.txt depuis pyproject.toml (nécessite pip-tools) - @echo "⚠️ Vérifiez que pip-tools est installé: pip install pip-tools" - pip-compile pyproject.toml -o requirements.txt --no-header - @echo "# Robot Framework Agent - Development Dependencies" > requirements-dev.tmp - @echo "# Install: pip install -r requirements-dev.txt" >> requirements-dev.tmp - @echo "" >> requirements-dev.tmp - @echo "-r requirements.txt # Include production dependencies" >> requirements-dev.tmp - @echo "" >> requirements-dev.tmp - pip-compile --extra dev pyproject.toml --no-header | grep -v "robotframework\|openai\|Pillow\|tiktoken\|python-dotenv\|requests" >> requirements-dev.tmp - mv requirements-dev.tmp requirements-dev.txt - @echo "✅ requirements.txt et requirements-dev.txt synchronisés depuis pyproject.toml" - clean: ## Nettoyer les fichiers générés rm -rf build/ dist/ *.egg-info rm -rf .pytest_cache/ .coverage htmlcov/ diff --git a/atest_agent.robot b/atest_agent.robot deleted file mode 100644 index 5afd8df..0000000 --- a/atest_agent.robot +++ /dev/null @@ -1,27 +0,0 @@ -*** Settings *** -Documentation This will be the most high level acceptance test for the library -... the library will contains methods like do / check / analyse ... -... each method will collect some mobile app evidence like XML hierarchy and screenshot -... send them to the LLM to get a response -... in a more low level of acceptance test we can test that request to the ai -... and see how it works with different models and different requests -... - - -... typical actions in the automation are ; click element , input text , -... page should contains text , -Library AppiumLibrary -Library Agent -*** Test Cases *** -Test case 1 - [Documentation] this doesn't work of cours e bcause we didn't code the - ... high level keywords yet , but just as an example - Open Application remote_url=https://hub-cloud.browserstack.com/wd/hub - ${prompt}= Set Variable click on the button enter some value - ${prompt2}= Set Variable input this text in the texte field: hello - ${prompt3}= Set Variable click on the submit button - ${prompt4}= Set Variable check that the text hello is displayed under the button of submit - Agent.do instruction=${prompt} - Agent.do instruction=${prompt2} - Agent.do instruction=${prompt3} - Agent.check instruction=${prompt4} \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 743096c..b8f9871 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,14 +5,15 @@ build-backend = "setuptools.build_meta" [project] name = "robotframework-agent" version = "0.0.1" -description = "AI-driven test automation agent for apps using Robot Framework" +description = "AI-driven test automation agent for apps" readme = "readme.md" requires-python = ">=3.8" license = {text = "CC0-1.0"} authors = [ - {name = "Your Name", email = "your.email@example.com"} + {name = "Abdelkader HASSINE", email = "contact.abdelkaderhassine@gmail.com"}, + {name = "Pavlo Ivashchenko", email = "pawloiwanov@gmail.com"}, ] -keywords = ["robotframework", "testing", "ai", "automation", "llm"] +keywords = ["robotframework", "ai", "automation", "automation agent", "llm", "testing"] classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", @@ -29,13 +30,8 @@ classifiers = [ ] dependencies = [ - # Core Framework "robotframework>=6.0", - "robotframework-appiumlibrary>=3.0", - "Appium-Python-Client>=5.0", - # Default LLM Provider "openai>=1.0.0", - # Utilities "Pillow>=10.0.0", "tiktoken>=0.5.0", "python-dotenv>=1.0.0", @@ -43,92 +39,45 @@ dependencies = [ ] [project.optional-dependencies] -# Development tools for contributors +web = [ + "playwright>=1.40.0", +] +mobile = [ + "robotframework-appiumlibrary>=3.0", + "Appium-Python-Client>=5.0", +] +test = [ + "pytest>=8.0.0", + "pytest-cov>=4.1.0", +] dev = [ - # Testing + "playwright>=1.40.0", + "robotframework-appiumlibrary>=3.0", + "Appium-Python-Client>=5.0", "pytest>=8.0.0", "pytest-cov>=4.1.0", "pytest-xdist>=3.5.0", - "pytest-rerunfailures>=14.0", - "robotframework-pabot>=5.0", - "robotframework-retryfailed>=0.2.0", - # Code quality "black>=24.0.0", "flake8>=7.0.0", "mypy>=1.8.0", "isort>=5.13.0", - # Documentation - "sphinx>=7.0.0", - "sphinx-rtd-theme>=2.0.0", - # Build tools - "build>=1.0.0", - "twine>=5.0.0", - # Development utilities - "ipython>=8.20.0", - "ipdb>=0.13.13", "pre-commit>=3.6.0", - # All LLM providers for testing "anthropic>=0.20.0", "google-generativeai>=0.3.0", - # Vision features for testing - "gradio-client>=1.0.0", + "gradio-client>=2.0.0", ] - -# BrowserStack cloud testing browserstack = [ "browserstack-sdk>=1.30.0", "browserstack-local>=1.2.0", ] - -# Additional LLM providers anthropic = [ "anthropic>=0.20.0", ] gemini = [ "google-generativeai>=0.3.0", ] -all-llm = [ - "anthropic>=0.20.0", - "google-generativeai>=0.3.0", -] - -# Vision/VLM features vision = [ - "gradio-client>=1.0.0", -] - -# All extras combined -all = [ - # Testing - "pytest>=8.0.0", - "pytest-cov>=4.1.0", - "pytest-xdist>=3.5.0", - "pytest-rerunfailures>=14.0", - "robotframework-pabot>=5.0", - "robotframework-retryfailed>=0.2.0", - # Code quality - "black>=24.0.0", - "flake8>=7.0.0", - "mypy>=1.8.0", - "isort>=5.13.0", - # Documentation - "sphinx>=7.0.0", - "sphinx-rtd-theme>=2.0.0", - # Build tools - "build>=1.0.0", - "twine>=5.0.0", - # Development utilities - "ipython>=8.20.0", - "ipdb>=0.13.13", - "pre-commit>=3.6.0", - # All LLM providers - "anthropic>=0.20.0", - "google-generativeai>=0.3.0", - # Vision features - "gradio-client>=1.0.0", - # BrowserStack - "browserstack-sdk>=1.30.0", - "browserstack-local>=1.2.0", + "gradio-client>=2.0.0", ] [project.urls] diff --git a/readme.md b/readme.md index 111da21..0ce787d 100644 --- a/readme.md +++ b/readme.md @@ -1,137 +1,78 @@ # Robot Framework Agent -Robot Framework Agent is an open-source experiment to bring intent-level, LLM-augmented automation directly into Robot Framework suites. The goal is simple: describe what should happen in natural language and let the agent turn that intent into Appium/Selenium actions, visual checks, and future autonomous behaviors. No hype—just a practical attempt to give Robot Framework a “brain” testers can actually use. +Enable Agent-mode automation. Write natural-language steps; and let the Agent turns them into tool-based UI actions and checks on web and mobile. [![RoboCon 2026 – What if Robot Framework Had a Brain](https://img.shields.io/badge/RoboCon%202026-What%20if%20Robot%20Framework%20Had%20a%20Brain-orange?style=for-the-badge)](https://www.robocon.io/agenda/helsinki#what-if-robot-framework-have-a-brain) -## Project Status & Vision +Alpha — An evolving experiment, with varying levels of maturity across keywords - Not recommended for production yet. -This repository is an ongoing exploration toward building a practical agentic toolkit for software testers. +## Quick Start -**Current focus** -- `Agent.Do` — interpret natural-language actions -- `Agent.Check` — interpret natural-language assertions +```robot +*** Settings *** +Library Agent llm_client=openai llm_model=gpt-4o-mini -Both keywords are in active development. Work is underway to make them stable, predictable, and usable on real production application. +*** Test Cases *** +Login + Agent.Do enter "user@example.com" in email field + Agent.Do enter "password1234" in the password field + Agent.Do click on login button + Agent.Check verify homepage is displayed +``` -**Near-term goals** -- add mid-level capabilities such as locating visual/semantic elements -- extend `Agent.ReportBug` so legacy suites (without agentic capabilities) can file actionable reports automatically -- expose internal locator/vision data for debugging -- experiment with autonomous behaviours in controlled, test-safe ways +## Installation -None of this is final; the library is evolving through experiments, refactoring, and real-world usage. Contributions, critiques, and field tests are welcome. +```bash +# Core +pip install robotframework-agent -## Presented at RoboCon 2026 (Helsinki) +# Web testing (+ Playwright) +pip install robotframework-agent[web] -This project will be showcased at RoboCon 2026 during the talk **“What if Robot Framework Had a Brain?”** -👉 https://www.robocon.io/agenda/helsinki#what-if-robot-framework-have-a-brain +# Mobile testing (+ Appium) +pip install robotframework-agent[mobile] -The session will cover the architecture behind the agent, early field results, and how intent-based keywords can help teams work at a higher abstraction level without abandoning Robot Framework’s strengths. +# Development (all tools) +pip install robotframework-agent[dev] +``` -## Support & Sponsorship +## Keywords -If you find this work useful, inspiring, or simply want to help move agentic testing forward, you can support the project by: +**Agent.Do** `` +- Execute actions: click, scroll, input text, select, navigate +- Example: `Agent.Do scroll down to footer` -- sponsoring dedicated development time -- funding compute for VLM/LLM experimentation -- contributing code, test cases, or research notes +**Agent.Check** `` +- Perform a visual or semantic verification. +- Example: `Agent.Check verify login form is visible` -This is not a finished product; it’s an open laboratory for building smarter testing tools. Any support—small or large—helps the project grow and stay independent. +**Agent.Ask** `` `format=text|json` +- Query current UI state +- Example: `Agent.Ask What is the product price?` -## Overview +**Agent.Find Visual Element** `` `format=normalized|pixels|center` +- Locate elements by description +- Example: `Agent.Find Visual Element search button` -Robot Framework Agent exposes high-level keywords to describe actions and checks in natural language; the agent then translates them into Appium (real device/emulator) and other UI interactions. +## Technical Notes -## Usage (Robot Framework) +``` +Instruction → LLM → UI Context → Tool Selection → Execution +``` -In your `.robot` file: -```robot -*** Settings *** -Library Agent llm_client=openai llm_model=gpt-4o-mini +Design choices are informed by research on AI agents and UI perception. +Ideas are iterated and evaluated in our evolving lab suite: +[AgentArena](https://github.com/aidriventesting/AgentArena). -*** Test Cases *** -Agent Example - Agent.Do accept cookies - Agent.Check the screen correctly shows the Homepage -``` -### Notes -- Provided keywords: `Agent.Do `, `Agent.Check `. -- Works with real mobile devices and BrowserStack; see more details below. - -## Running Tests on BrowserStack - -### Prerequisites -1. BrowserStack Account - - Sign up at browserstack.com if you don't have an account - - Get your username and access key from BrowserStack dashboard - -2. Environment Setup - ```bash - # Install required dependencies - pip install -r requirements.txt - pip install browserstack-sdk - ``` - -3. Configuration - - Create/update `browserstack.yml` in your project root - - Configure your credentials: - ```yaml - userName: YOUR_USERNAME - accessKey: YOUR_ACCESS_KEY - ``` - - Update app path with your app's BrowserStack URL: - ```yaml - app: bs://YOUR_APP_ID - ``` - -### Running Tests -1. Single Test Execution - ```bash - browserstack-sdk robot tests/atest/your_test.robot - ``` - -2. Running Test Suites - ```bash - browserstack-sdk robot tests/atest/ - ``` - -3. Parallel Execution - ```bash - browserstack-sdk robot --variable parallel_execution:true tests/atest/ - ``` - -### Device Configuration -- Edit `browserstack.yml` to specify target devices: - ```yaml - platforms: - - deviceName: Samsung Galaxy S21 - platformVersion: 12.0 - platformName: Android - # Add more devices as needed - ``` - -### Development Tips -1. Debug Mode - - Set `debug: true` in browserstack.yml - - Enable detailed logs: `consoleLogs: info` - -2. Local Testing - - For testing with local apps/servers: - ```yaml - browserstackLocal: true - ``` - -3. Build Identification - - Set unique build names for tracking: - ```yaml - buildName: "Dev Build" - buildIdentifier: ${BUILD_NUMBER} - ``` - -### Viewing Results -1. Real-time monitoring: BrowserStack dashboard -2. Test reports: Available in `log/` directory after execution -3. Session videos: Automatically recorded and available in BrowserStack dashboard \ No newline at end of file +## Presented at RoboCon 2026 (Helsinki) + +This project will be showcased at RoboCon 2026 during the talk **"What if Robot Framework Had a Brain?"** +👉 https://www.robocon.io/agenda/helsinki#what-if-robot-framework-have-a-brain + + +## Contributing + +Builders, testers, and curious minds welcome. +Code, issues, and real-world use cases help shape the project. \ No newline at end of file diff --git a/requirements-browserstack.txt b/requirements-browserstack.txt deleted file mode 100644 index 74fdd55..0000000 --- a/requirements-browserstack.txt +++ /dev/null @@ -1,15 +0,0 @@ -# Robot Framework Agent - BrowserStack Dependencies -# For BrowserStack cloud testing -# Install: pip install -r requirements-browserstack.txt - -# ============================================================================ -# Include production dependencies -# ============================================================================ --r requirements.txt - -# ============================================================================ -# BrowserStack Tools -# ============================================================================ -browserstack-sdk>=1.30.0 # BrowserStack SDK -browserstack-local>=1.2.0 # Local testing tunnel - diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index 7c7c2d6..0000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,59 +0,0 @@ -# Robot Framework Agent - Development Dependencies -# For contributors and developers -# Install: pip install -r requirements-dev.txt - -# ============================================================================ -# Include production dependencies -# ============================================================================ --r requirements.txt - -# ============================================================================ -# Additional LLM Providers (for testing all providers) -# ============================================================================ -anthropic>=0.20.0 # Claude models -google-generativeai>=0.3.0 # Gemini models - -# ============================================================================ -# Vision Features (for development/testing) -# ============================================================================ -gradio-client>=1.0.0 # OmniParser client - -# ============================================================================ -# Testing Tools -# ============================================================================ -pytest>=8.0.0 # Unit testing framework -pytest-cov>=4.1.0 # Coverage reporting -pytest-xdist>=3.5.0 # Parallel test execution -pytest-rerunfailures>=14.0 # Retry failed tests - -# Robot Framework testing -robotframework-pabot>=5.0 # Parallel RF execution -robotframework-retryfailed>=0.2.0 # Retry RF tests - -# ============================================================================ -# Code Quality & Formatting -# ============================================================================ -black>=24.0.0 # Code formatter -flake8>=7.0.0 # Linting -mypy>=1.8.0 # Type checking -isort>=5.13.0 # Import sorting - -# ============================================================================ -# Documentation -# ============================================================================ -sphinx>=7.0.0 # Documentation generator -sphinx-rtd-theme>=2.0.0 # ReadTheDocs theme - -# ============================================================================ -# Build Tools -# ============================================================================ -build>=1.0.0 # PEP 517 build -twine>=5.0.0 # Package upload to PyPI -wheel>=0.42.0 # Wheel building - -# ============================================================================ -# Development Utilities -# ============================================================================ -ipython>=8.20.0 # Enhanced Python shell -ipdb>=0.13.13 # Debugger -pre-commit>=3.6.0 # Git hooks diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 7be26be..0000000 --- a/requirements.txt +++ /dev/null @@ -1,34 +0,0 @@ -# Robot Framework Agent - Production Dependencies -# Install: pip install -r requirements.txt - -# ============================================================================ -# Core Framework -# ============================================================================ -robotframework>=6.0 -robotframework-appiumlibrary>=3.0 -Appium-Python-Client>=5.0 -playwright>=1.40.0 - -# ============================================================================ -# LLM Providers (at least one required) -# ============================================================================ -# OpenAI (default provider) -openai>=1.0.0 - -# Uncomment if you use these providers: -# anthropic>=0.20.0 # For Claude models -# google-generativeai>=0.3.0 # For Gemini models - -# ============================================================================ -# Utilities -# ============================================================================ -Pillow>=10.0.0 # Image processing -tiktoken>=0.5.0 # Token counting for LLMs -python-dotenv>=1.0.0 # Environment variables -requests>=2.31.0 # HTTP requests (image upload) - -# ============================================================================ -# Vision Features (OmniParser) -# ============================================================================ -# Required for visual click tool (OmniParser integration) -gradio-client>=2.0.0 # Gradio client for HuggingFace spaces