ruby_raider 1.1.4 → 3.0.0

data/README.md

@@ -10,10 +10,10 @@
 <br />
 <div align="center">
    <a href="https://github.com/RubyRaider/ruby_raider">
-   <img src="https://www.ruby-raider.com/assets/icon-DYY74ofR.png" alt="Logo" style="width:200px;">
+   <img src="assets/ruby_raider_logo.svg" alt="Logo" style="width:200px;">
    </a>
    <p align="center">
-      <a href="https://github.com/RubyRaider/ruby_raider#getting-started"><strong>Explore the docs »</strong></a>
+      <a href="https://github.com/RubyRaider/ruby_raider#getting-started"><strong>Explore the docs</strong></a>
       <br />
       <br />
       <a href="https://rubygems.org/gems/ruby_raider">Rubygems</a>
@@ -22,126 +22,189 @@
       ·
       <a href="https://github.com/RubyRaider/ruby_raider/issues">Request Feature</a>
    </p>
-   <p align="center"> For more information and updates on releases, see <a href="https://ruby-raider.com">https://ruby-raider.com</a></p>
+   <p align="center"> For more information and updates on releases, see https://ruby-raider.onrender.com/</p>
 </div>
 
 ## What is Ruby Raider?
 
-Ruby Raider is a generator and scaffolding gem to make UI test automation easier
+Ruby Raider is a CLI gem and API backend for scaffolding and generating UI test automation frameworks. It supports both interactive command-line usage and programmatic invocation via [Raider Desktop](https://ruby-raider.com).
 
-### At the moment Ruby Raider supports generating the following frameworks:
+## Supported Frameworks
 
-| Web Testing Framework | Visual Testing Framework          | Mobile Testing Framework           | Accessibility Testing Framework |
-|-----------------------|-----------------------------------|------------------------------------|---------------------------------|
-| Cucumber and Selenium | Cucumber, Applitools and Selenium | Cucumber and Appium for IOS        | Cucumber and Axe for web        |
-| Rspec and Selenium    | Rspec, Applitools and Selenium    | Rspec and Appium for IOS           | Rspec and Axe for web           |
-| Cucumber and Watir    |                                   | Cucumber and Appium for Android    |                                 |
-| Rspec and Watir       |                                   | Rspec and Appium for Android       |                                 |
-|                       |                                   | Cucumber and Appium Cross-platform |                                 |
-|                       |                                   | Rspec and Appium Cross-platform    |                                 |
+### Web Testing
 
-***In order to run the Appium tests, download the example [app](https://github.com/saucelabs/my-demo-app-rn).***
-***Remember to use the full path of the app that you download in the capabilities file and start the server using one of
-the commands below:***
+| Test Framework | Selenium | Watir | Capybara |
+|----------------|----------|-------|----------|
+| RSpec          | ✅       | ✅    | ✅       |
+| Cucumber       | ✅       | ✅    | ✅       |
+| Minitest       | ✅       | ✅    | ✅       |
 
-```ruby
-raider u start_appium
-appium --base /wd/hub  
-```
+### Mobile Testing (Appium)
+
+| Test Framework | iOS | Android | Cross-Platform |
+|----------------|-----|---------|----------------|
+| RSpec          | ✅  | ✅      | ✅             |
+| Cucumber       | ✅  | ✅      | ✅             |
+| Minitest       | ✅  | ✅      | ✅             |
+
+### Optional Add-ons (Web Only)
 
-***In order to run the visual tests with applitools, you need to create an account and get your api key, you can read
-more [here](https://applitools.com/docs/topics/overview/obtain-api-key.html#:~:text=If%20you%20already%20have%20an,Your%20key%20will%20be%20displayed.)
-.***
+| Add-on | Flag | Description |
+|--------|------|-------------|
+| Accessibility | `--accessibility` | Adds axe gem + example accessibility tests |
+| Visual Regression | `--visual` | Adds chunky_png + visual comparison helpers |
+| Performance | `--performance` | Adds Lighthouse auditing (requires `npm install -g lighthouse`) |
 
-***To use the open ai integration you need to set up the OPENAI_ACCESS_TOKEN environment variable and
-you can also set the optional OPENAI_ORGANIZATION_ID if you have an organization***
+### CI/CD Platforms
 
-This works in all the platforms (Tested on Mac OS, Linux and Windows).
+Projects can be generated with built-in CI/CD pipelines for **GitHub Actions** or **GitLab CI/CD**.
 
-## Getting started
+### Test Reporters
 
-To get the project up and running.
+Choose a reporter with `--reporter`: `allure`, `junit`, `json`, `both`, `all`, or `none`.
 
-**Just do:**
+***The web tests run against the [Raider Test Store](https://raider-test-site.onrender.com/).***
+
+***To run Appium tests, download the example [app](https://github.com/RaiderHQ/raider_test_app) and start the server:***
+
+```bash
+raider u start_appium
+```
 
-```ruby
+This works on all platforms (Mac OS, Linux and Windows).
+
+## Getting Started
+
+Install the gem:
+
+```bash
 gem install ruby_raider
 ```
 
-**Then do:**
+Create a new project interactively:
 
-```ruby
-raider new [name_of_project]
+```bash
+raider new [project_name]
 ```
 
-Then a TUI/CLI will appear where the configuration of which frameworks you want to be generated/scaffolded can be
-selected.
+Or skip the menu with parameters:
 
-Select the ones you will like to work with.
+```bash
+raider new [project_name] -p framework:rspec automation:selenium
+```
 
-If you already know which frameworks you want to use, you can do:
+Add optional features:
 
-```ruby
-raider new [name_of_project] -p framework:[framework] automation:[automation_type]
+```bash
+raider new my_project -p framework:rspec automation:selenium --accessibility --visual --performance
 ```
 
-An example of the command above would be:
+Skip flags for leaner projects:
 
-```ruby
-raider new test_project -p framework:rspec automation:selenium
+```bash
+raider new my_project -p framework:cucumber automation:watir --skip_ci --skip_video --reporter none
 ```
 
-### Ruby raider provides the following list of basic commands
+## Commands
 
-###### Anything between square brackets([...]) is where your imput goes
+###### Anything between square brackets ([...]) is where your input goes
 
-```ruby
-Commands :
-raider generate # Provides access to all the scaffolding commands
-raider help [COMMAND] # Describe available commands or one specific command
-raider new [PROJECT_NAME] # Creates a new framework based on settings picked
-raider utility # Provides access to all the utility commands 
-raider version # It shows the version of Ruby Raider you are currently using
-```
+### Main Commands
 
-All the basic commands have their corresponding shortcut:
+```
+raider new [PROJECT_NAME]       # Create a new framework project
+raider adopt                    # Import an existing test project
+raider generate                 # Access scaffolding commands
+raider utility                  # Access utility commands
+raider plugin_manager           # Manage plugins
+raider version                  # Show current version
+raider help [COMMAND]           # Describe available commands
+```
 
-* g for generate
-* n for new
-* u for utility
-* v for version
+Shortcuts: `n` (new), `a` (adopt), `g` (generate), `u` (utility), `pm` (plugin_manager), `v` (version)
 
 ### Scaffolding Commands
 
-Ruby Raider also supports scaffolding:
+```
+raider g page [NAME]            # Create a page object
+raider g spec [NAME]            # Create an RSpec test
+raider g feature [NAME]         # Create a Cucumber feature
+raider g steps [NAME]           # Create step definitions
+raider g helper [NAME]          # Create a helper class
+raider g component [NAME]       # Create a component class
+raider g scaffold [NAME(S)]     # Create page + test + steps
+raider g destroy [NAME(S)]      # Delete scaffolded files
+raider g from_url [URL]         # Generate page & spec from a live URL
+```
 
-* To create a new page object you do: ```raider g page [PAGE_NAME]```
-* To create a new spec you do: ```raider g spec [SPEC_NAME]```
-* To create a new feature you do: ```raider g feature [FEATURE_NAME]```
-* To create a new steps definition you do: ```raider g steps [STEPS_NAME]```
-* To create both a page/spec or a page/feature/steps you do: ```raider g scaffold [SCAFFOLD_NAME]```
+Options:
 
-It's possible to add the option --path or p if you want to specify where to create your features, pages, helpers and
-specs.
+* `--from [FILE]` — Generate spec from an existing page object
+* `--ai` — Use LLM for intelligent test scenario generation
+* `--dry_run` — Preview files without creating them
+* `--uses [PAGES]` — Specify page dependencies
+* `--path [PATH]` — Custom output path
+* `--crud` — Generate full CRUD scaffold (list, create, detail, edit + tests)
 
-If you want to set the default path for the creation of your features, helpers and specs:
+### Utility Commands
 
-```ruby
-raider u path [PATH_NAME] - -feature or f
-raider u path [PATH_NAME] - -spec or s
-raider u path [PATH_NAME] - -helper or h
 ```
+raider u path [PATH]            # Set default paths for scaffolding
+raider u url [URL]              # Set default project URL
+raider u browser [BROWSER]      # Set default browser
+raider u browser_options [OPTS] # Set browser options
+raider u raid                   # Run all tests
+raider u timeout [SECONDS]      # Set test timeout
+raider u viewport [DIMENSIONS]  # Set viewport size (e.g., 1920x1080)
+raider u platform [PLATFORM]    # Set platform for cross-platform tests
+raider u debug [on/off]         # Toggle debug mode
+raider u start_appium           # Start Appium server
+raider u desktop                # Download Raider Desktop
+raider u llm [PROVIDER]         # Configure LLM provider (openai, anthropic, ollama)
+```
+
+### Plugin Commands
 
-If you don't specify an option, path will assume you want to change the default path for pages.
+```
+raider pm add [NAME]            # Add a plugin to your project
+raider pm delete [NAME]         # Remove a plugin
+raider pm list                  # List available plugins
+raider pm local                 # List installed plugins
+```
 
-### Appium Server Command
+### Adopt Command
 
-To initialise Appium server run this command:
+Import an existing test project into Ruby Raider conventions:
 
-```ruby
-raider u start_appium
+```bash
+raider adopt project [SOURCE_PATH]
+```
+
+## LLM Integration
+
+Ruby Raider supports optional LLM-powered features for intelligent test generation. Configure a provider:
+
+```bash
+raider u llm openai      # Configure OpenAI
+raider u llm anthropic   # Configure Anthropic
+raider u llm ollama      # Configure Ollama (local, no API key needed)
+```
+
+Then use the `--ai` flag with scaffolding commands for smarter code generation.
+
+## Development
+
+```bash
+bundle install          # Install dependencies
+bundle exec rspec       # Run all tests
+bundle exec rspec --tag ~slow  # Run fast tests only (skip E2E)
+bundle exec rubocop     # Run linter
+bundle exec reek        # Run code smell detection
 ```
 
-### Sponsors
+## Links
 
-This project is tested with BrowserStack.
+* [RubyGems](https://rubygems.org/gems/ruby_raider)
+* [GitHub](https://github.com/RubyRaider/ruby_raider)
+* [Website](https://ruby-raider.onrender.com/)
+* [Community](https://gitter.im/RubyRaider/community)

data/RELEASE.md

@@ -0,0 +1,412 @@
+# Release Process Documentation
+
+## Overview
+
+Ruby Raider uses a **fully automated release process**. You only need to run a single command, and everything else happens automatically via GitHub Actions.
+
+## Prerequisites
+
+Before releasing, ensure you have:
+
+1. ✅ Merged all changes to `master` branch
+2. ✅ All tests passing locally
+3. ✅ RuboCop and Reek checks passing
+4. ✅ GitHub repository configured with secrets:
+   - `RUBYGEMS_API_KEY` - RubyGems API key for publishing
+
+## One-Command Release
+
+```bash
+# For bug fixes (1.1.4 -> 1.1.5)
+bin/release patch
+
+# For new features (1.1.4 -> 1.2.0)
+bin/release minor
+
+# For breaking changes (1.1.4 -> 2.0.0)
+bin/release major
+```
+
+That's it! Everything else is automated.
+
+---
+
+## What Happens Automatically
+
+### 1. Local Checks (bin/release script)
+
+The release script will:
+- ✅ Verify working directory is clean
+- ✅ Confirm you're on master/main branch
+- ✅ Run all unit tests
+- ✅ Run integration tests
+- ✅ Run RuboCop linter
+- ✅ Run Reek code smell detector
+- ✅ Calculate new version number
+- ✅ Ask for confirmation
+- ✅ Update `lib/version` file
+- ✅ Create git commit with version bump
+- ✅ Create git tag (e.g., `v1.2.0`)
+- ✅ Push commit and tag to GitHub
+
+**If any step fails, the release is aborted.**
+
+### 2. GitHub Actions Workflow (Triggered by Tag)
+
+When the tag is pushed, the `.github/workflows/release.yml` workflow:
+
+**Validation Phase:**
+- ✅ Verifies version in `lib/version` matches tag
+- ✅ Runs all tests again (unit + integration)
+- ✅ Runs RuboCop
+- ✅ Runs Reek
+
+**Build Phase:**
+- ✅ Builds the gem (`ruby_raider-X.Y.Z.gem`)
+
+**Release Phase:**
+- ✅ Generates changelog from git commits
+- ✅ Creates GitHub Release with:
+  - Release notes
+  - Changelog
+  - Gem file attachment
+- ✅ Publishes gem to RubyGems.org
+
+**All of this happens automatically within 2-3 minutes.**
+
+---
+
+## Example Release Flow
+
+```bash
+$ bin/release minor
+
+🧪 Running tests...
+......................................
+
+✓ All tests and linters passed
+
+📦 Release Summary
+  Current version: 1.1.4
+  New version:     1.2.0
+  Bump type:       minor
+
+This will:
+  1. Update lib/version to 1.2.0
+  2. Commit changes
+  3. Create git tag v1.2.0
+  4. Push to GitHub (triggers automated release)
+  5. Publish gem to RubyGems (via GitHub Actions)
+  6. Create GitHub release with changelog
+
+Proceed with release? [y/N] y
+
+📝 Updating version to 1.2.0...
+✓ Updated lib/version
+
+📌 Creating commit and tag...
+✓ Created commit and tag v1.2.0
+
+🚀 Pushing to GitHub...
+✓ Pushed to GitHub
+
+============================================================
+🎉 Release 1.2.0 initiated successfully!
+============================================================
+
+The GitHub Actions workflow is now:
+  1. Running tests
+  2. Building the gem
+  3. Publishing to RubyGems
+  4. Creating GitHub release
+
+Monitor progress at:
+  https://github.com/RubyRaider/ruby_raider/actions
+
+Release will be available at:
+  https://github.com/RubyRaider/ruby_raider/releases/tag/v1.2.0
+  https://rubygems.org/gems/ruby_raider/versions/1.2.0
+
+✨ Thank you for contributing to Ruby Raider!
+```
+
+---
+
+## Semantic Versioning Guide
+
+Ruby Raider follows [Semantic Versioning](https://semver.org/):
+
+### Patch Release (X.Y.Z+1)
+
+**When:** Bug fixes, small improvements, no new features
+
+**Examples:**
+- Fix template rendering bug
+- Update documentation
+- Performance improvements
+- Dependency updates
+
+**Command:**
+```bash
+bin/release patch  # 1.1.4 -> 1.1.5
+```
+
+### Minor Release (X.Y+1.0)
+
+**When:** New features, backward-compatible changes
+
+**Examples:**
+- Add new framework support
+- New template system
+- New CLI commands
+- Enhanced functionality
+
+**Command:**
+```bash
+bin/release minor  # 1.1.4 -> 1.2.0
+```
+
+### Major Release (X+1.0.0)
+
+**When:** Breaking changes, major refactors
+
+**Examples:**
+- Drop Ruby 2.x support
+- Change public API
+- Remove deprecated features
+- Architectural changes
+
+**Command:**
+```bash
+bin/release major  # 1.1.4 -> 2.0.0
+```
+
+---
+
+## Monitoring the Release
+
+### 1. GitHub Actions Progress
+
+Visit: https://github.com/RubyRaider/ruby_raider/actions
+
+You'll see the "Automated Release" workflow running with steps:
+- ✅ Checkout code
+- ✅ Run tests
+- ✅ Build gem
+- ✅ Generate changelog
+- ✅ Create GitHub Release
+- ✅ Publish to RubyGems
+
+**Expected duration:** 2-3 minutes
+
+### 2. GitHub Release
+
+Visit: https://github.com/RubyRaider/ruby_raider/releases
+
+You'll see the new release with:
+- Version number
+- Changelog (auto-generated from commits)
+- Gem file download
+- Installation instructions
+
+### 3. RubyGems.org
+
+Visit: https://rubygems.org/gems/ruby_raider
+
+The new version will appear within 1-2 minutes of publication.
+
+---
+
+## Troubleshooting
+
+### Problem: "Working directory is not clean"
+
+**Solution:** Commit or stash your changes first
+```bash
+git status
+git add .
+git commit -m "Your changes"
+# Then try release again
+```
+
+### Problem: "Tests failed"
+
+**Solution:** Fix the failing tests before releasing
+```bash
+bundle exec rspec
+bundle exec rubocop --auto-correct
+bundle exec reek
+```
+
+### Problem: "Version mismatch in workflow"
+
+**Solution:** This means `lib/version` doesn't match the tag
+
+This should never happen if using `bin/release`, but if it does:
+```bash
+# Check version
+cat lib/version
+
+# Update manually
+echo "1.2.0" > lib/version
+git add lib/version
+git commit -m "Fix version"
+git push
+```
+
+### Problem: "RubyGems API key not configured"
+
+**Solution:** Add the secret in GitHub:
+
+1. Get your RubyGems API key:
+   ```bash
+   curl -u your-rubygems-username https://rubygems.org/api/v1/api_key.yaml
+   ```
+
+2. Add to GitHub Secrets:
+   - Go to: https://github.com/RubyRaider/ruby_raider/settings/secrets/actions
+   - Click "New repository secret"
+   - Name: `RUBYGEMS_API_KEY`
+   - Value: (paste your API key)
+   - Click "Add secret"
+
+### Problem: "Failed to push to GitHub"
+
+**Solution:** Check your authentication
+```bash
+# Test push access
+git push origin master
+
+# If using HTTPS, you may need a personal access token
+# If using SSH, ensure your key is added
+```
+
+---
+
+## Manual Release (Backup Method)
+
+If the automated system fails, you can release manually:
+
+```bash
+# 1. Update version
+echo "1.2.0" > lib/version
+
+# 2. Commit
+git add lib/version
+git commit -m "Bump version to 1.2.0"
+
+# 3. Create tag
+git tag -a v1.2.0 -m "Release version 1.2.0"
+
+# 4. Push
+git push origin master
+git push origin v1.2.0
+
+# 5. Build gem
+gem build ruby_raider.gemspec
+
+# 6. Push to RubyGems
+gem push ruby_raider-1.2.0.gem
+
+# 7. Create GitHub Release manually
+# Visit: https://github.com/RubyRaider/ruby_raider/releases/new
+```
+
+---
+
+## Release Checklist
+
+Before releasing, verify:
+
+- [ ] All PRs merged to master
+- [ ] CHANGELOG or commit messages are clear
+- [ ] Tests passing locally (`bundle exec rspec`)
+- [ ] RuboCop passing (`bundle exec rubocop`)
+- [ ] Reek passing (`bundle exec reek`)
+- [ ] Version bump type is correct (patch/minor/major)
+- [ ] GitHub Actions secrets configured (RUBYGEMS_API_KEY)
+
+Then run:
+
+```bash
+bin/release [patch|minor|major]
+```
+
+And monitor at:
+- https://github.com/RubyRaider/ruby_raider/actions
+
+---
+
+## Post-Release
+
+After a successful release:
+
+1. ✅ Verify gem on RubyGems: https://rubygems.org/gems/ruby_raider
+2. ✅ Check GitHub Release: https://github.com/RubyRaider/ruby_raider/releases
+3. ✅ Test installation:
+   ```bash
+   gem install ruby_raider -v 1.2.0
+   raider --version
+   ```
+4. ✅ Announce release (Twitter, Discord, etc.)
+5. ✅ Update website if needed
+
+---
+
+## Configuration Files
+
+### Release Workflow
+- **File:** `.github/workflows/release.yml`
+- **Trigger:** Push of tag matching `v*.*.*`
+- **Actions:** Test → Build → Release → Publish
+
+### Release Script
+- **File:** `bin/release`
+- **Usage:** `bin/release [major|minor|patch]`
+- **Purpose:** Local validation and version bumping
+
+### Version File
+- **File:** `lib/version`
+- **Format:** Single line with version number (no 'v' prefix)
+- **Example:** `1.2.0`
+
+---
+
+## FAQ
+
+**Q: Can I release from a branch?**
+A: The script will warn you. It's recommended to release from master/main only.
+
+**Q: Can I skip tests?**
+A: No. Tests are mandatory for releases to ensure quality.
+
+**Q: How do I rollback a release?**
+A: You can't unpublish from RubyGems, but you can:
+1. Yank the version: `gem yank ruby_raider -v X.Y.Z`
+2. Release a new patch version with fixes
+
+**Q: What if the GitHub Actions workflow fails?**
+A: Check the logs, fix the issue, delete the tag, and try again:
+```bash
+git tag -d v1.2.0
+git push origin :refs/tags/v1.2.0
+# Fix issue, then re-run bin/release
+```
+
+**Q: How long does a release take?**
+A: ~2-3 minutes from pushing the tag to gem being available on RubyGems.
+
+---
+
+## Support
+
+If you encounter issues with the release process:
+
+1. Check the [troubleshooting section](#troubleshooting)
+2. Review GitHub Actions logs
+3. Open an issue: https://github.com/RubyRaider/ruby_raider/issues
+
+---
+
+**Last Updated:** 2026-02-10
+**Automation Version:** 1.0