{"id":36454386,"url":"https://github.com/jianloong/robogo","last_synced_at":"2026-01-11T23:01:26.442Z","repository":{"id":303189989,"uuid":"1014024210","full_name":"JianLoong/robogo","owner":"JianLoong","description":"A modern, developer-friendly test automation framework with clean YAML syntax for comprehensive end-to-end testing written in Go.","archived":false,"fork":false,"pushed_at":"2025-07-23T10:58:21.000Z","size":5503,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-23T12:33:21.061Z","etag":null,"topics":["api-rest","banking","finance","go","kafka","spanner-database","swift-messages","test-automation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JianLoong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-04T22:38:57.000Z","updated_at":"2025-07-23T10:58:25.000Z","dependencies_parsed_at":"2025-07-06T08:39:25.795Z","dependency_job_id":"0810d790-e19c-4bc1-bcda-f6c1d9742707","html_url":"https://github.com/JianLoong/robogo","commit_stats":null,"previous_names":["jianloong/robogo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JianLoong/robogo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JianLoong%2Frobogo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JianLoong%2Frobogo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JianLoong%2Frobogo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JianLoong%2Frobogo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JianLoong","download_url":"https://codeload.github.com/JianLoong/robogo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JianLoong%2Frobogo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28326166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T22:11:01.104Z","status":"ssl_error","status_checked_at":"2026-01-11T22:10:58.990Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rest","banking","finance","go","kafka","spanner-database","swift-messages","test-automation"],"created_at":"2026-01-11T23:01:25.599Z","updated_at":"2026-01-11T23:01:26.425Z","avatar_url":"https://github.com/JianLoong.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Robogo\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n**A multi-service automation tool written in Go**\r\n\r\n*Clean YAML-based workflows for HTTP APIs, databases, messaging systems, file operations, and more*\r\n\r\n---\r\n\r\n### 🚀 Quick Links\r\n\r\n| **Getting Started** | **Examples** | **Documentation** | **Architecture** |\r\n|:---:|:---:|:---:|:---:|\r\n| [Installation](#installation) | [Your First Test](#your-first-test) | [Complete Examples](examples/README.md) | [KISS Principles](#kiss-principles) |\r\n| [Basic Usage](#basic-usage) | [Test Categories](#example-tests) | [Action Reference](#action-categories) | [Execution Flow](docs/execution-flow-diagram.md) |\r\n| [Quick Start](#quick-start) | [Security Examples](#security-examples) | [Error Handling](docs/error-failure-states-diagram.md) | [Development Guide](internal/README.md) |\r\n\r\n---\r\n\r\n\u003c/div\u003e\r\n\r\n**Multi-Service Automation**: Robogo enables developers to automate workflows across HTTP APIs, databases, messaging systems, and file operations with clear, readable YAML definitions that improve productivity and reduce manual work.\r\n\r\n## Features\r\n\r\n### Core Capabilities\r\n- **Developer-Friendly**: Clear, readable YAML workflows that developers can easily understand and maintain\r\n- **Multi-Service Integration**: Automate workflows across HTTP APIs, databases, messaging systems, and file operations\r\n- **Simple YAML Workflows**: Write automation in clean, readable YAML format with powerful features\r\n- **KISS Architecture**: Keep It Simple and Straightforward - no over-engineering or complex abstractions\r\n\r\n### Actions \u0026 Integrations\r\n- **HTTP Automation**: Full HTTP client with all methods, authentication, and response processing\r\n- **Database Operations**: PostgreSQL, MongoDB, and Google Cloud Spanner with secure credential management\r\n- **Messaging Systems**: Kafka and RabbitMQ operations with producer/consumer support\r\n- **File Operations**: Local file reading and secure SCP file transfers via SSH/SFTP\r\n- **Financial Messaging**: SWIFT message generation for banking and financial workflows\r\n- **Data Processing**: JSON/XML parsing, construction, and extraction with jq/xpath support\r\n- **String Operations**: Random generation, formatting, encoding/decoding, and manipulation\r\n- **Utility Actions**: UUID generation, time operations, sleep/timing, assertions, and logging\r\n\r\n### Advanced Features\r\n- **Variable Substitution**: Dynamic variables with `${variable}` and `${ENV:VARIABLE}` syntax\r\n- **Security-First**: Automatic sensitive data masking, no-log mode, and environment variable support\r\n- **Control Flow**: Conditional execution (`if`), retry logic with backoff, and nested step collections\r\n- **Data Extraction**: Extract data from responses using jq, xpath, or regex patterns\r\n- **Error Handling**: Comprehensive error categorization with user-friendly messages\r\n- **Clean CLI Tool**: Immediate connection handling - no hanging processes\r\n\r\n### Recent Improvements (2024)\r\n- **Architecture Simplification**: Removed 6+ abstraction layers, eliminated dependency injection\r\n- **SCP File Transfer**: Secure SSH/SFTP support with password and key authentication\r\n- **Enhanced Security**: Step-level security controls, comprehensive data masking\r\n- **File Organization**: Split large files into focused, maintainable modules\r\n- **Comprehensive Documentation**: README files throughout codebase for better navigation\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\n# Build for your platform\r\ngo build -o robogo ./cmd/robogo\r\n```\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Run a single test\r\n./robogo run my-test.yaml\r\n\r\n# Run test with custom .env file\r\n./robogo --env production.env run my-test.yaml\r\n\r\n# List available actions\r\n./robogo list\r\n\r\n# Show version\r\n./robogo version\r\n```\r\n\r\n### Output Formats\r\n\r\nRobogo supports multiple output formats for different use cases:\r\n\r\n```bash\r\n# Console output (default) - human-readable table format\r\n./robogo run test.yaml\r\n\r\n# JUnit XML output - for CI/CD integration\r\n./robogo run test.yaml --output junit --output-file results.xml\r\n\r\n# JSON output - for programmatic processing\r\n./robogo run test.yaml --output json --output-file results.json\r\n\r\n# Quiet mode - suppress console output when writing to file\r\n./robogo run test.yaml --output junit --output-file results.xml --quiet\r\n```\r\n\r\n**CI/CD Integration Examples:**\r\n```bash\r\n# GitHub Actions / Jenkins / GitLab CI\r\n./robogo run tests/integration.yaml --output junit --output-file test-results.xml\r\n\r\n# Generate both XML and JSON reports\r\n./robogo run test.yaml --output junit --output-file results.xml\r\n./robogo run test.yaml --output json --output-file results.json\r\n```\r\n\r\n📖 **Complete Documentation**: See **[docs/junit-xml-output.md](docs/junit-xml-output.md)** for detailed JUnit XML structure, mapping, and CI/CD integration examples.\r\n\r\n### Your First Workflow\r\n\r\nThe quickest way to get started is with our showcase HTTP example:\r\n\r\n```bash\r\n# Run the main showcase workflow (no setup needed)\r\n./robogo run examples/02-http/01-http-get.yaml\r\n```\r\n\r\n**Main Showcase Example:**\r\n```yaml\r\ntestcase: \"TC-HTTP-001\"\r\ndescription: \"Workflow to demonstrate HTTP response processing\"\r\n\r\nvariables:\r\n  vars:\r\n    base_url: \"http://localhost:8000/base64/SFRUUEJJTiBpcyBhd2Vzb21l\"\r\n    expected_value: \"HTTPBIN is awesome\"\r\n\r\nsteps:\r\n  - name: \"Make HTTP request\"\r\n    action: http\r\n    args: [\"GET\", \"${base_url}\"]\r\n    result: \"http_response\"\r\n\r\n  - name: \"Extract status code\"\r\n    action: jq\r\n    args: [\"${http_response}\", \".status_code\"]\r\n    result: \"status_code\"\r\n\r\n  - name: \"Verify status code\"\r\n    action: assert\r\n    args: [\"${status_code}\", \"==\", \"200\"]\r\n\r\n  - name: \"Extract response body\"\r\n    action: jq\r\n    args: [\"${http_response}\", \".body\"]\r\n    result: \"response_body\"\r\n\r\n  - name: \"Verify expected content\"\r\n    action: assert\r\n    args: [\"${response_body}\", \"==\", \"${expected_value}\"]\r\n```\r\n\r\n**Expected output:**\r\n```\r\nRunning test case: TC-HTTP-001\r\nDescription: Workflow to demonstrate HTTP response processing\r\nSetup: 0, Steps: 7, Teardown: 0\r\n\r\nStep 1: Make HTTP request\r\n  Action: http\r\n  Args: [GET http://localhost:8000/base64/SFRUUEJJTiBpcyBhd2Vzb21l]\r\n  Options: map[timeout:5s]\r\n  Result Variable: http_response\r\n  Executing... \r\n✓ PASSED (10.959687ms)\r\n\r\nStep 2: Extract status code\r\n  Action: jq\r\n  Args: [.status_code]\r\n  Result Variable: status_code\r\n  Executing... \r\n✓ PASSED (973.434µs)\r\n    Data: 200\r\n\r\nStep 3: Verify status code\r\n  Action: assert\r\n  Args: [200 == 200]\r\n  Executing... \r\n✓ PASSED (306.971µs)\r\n\r\nStep 4: Extract response body\r\n  Action: jq\r\n  Args: [.body]\r\n  Result Variable: response_body\r\n  Executing... \r\n✓ PASSED (151.688µs)\r\n    Data: HTTPBIN is awesome\r\n\r\nStep 5: Verify expected content\r\n  Action: assert\r\n  Args: [HTTPBIN is awesome == HTTPBIN is awesome]\r\n  Executing... \r\n✓ PASSED (475.234µs)\r\n\r\nTest Summary:\r\n  Name: TC-HTTP-001\r\n  Status: PASS\r\n  Duration: 13.589684ms\r\n\r\n|   # | Step Name                                | Status   | Duration     |\r\n|-----|------------------------------------------|----------|--------------|\r\n|   1 | Make HTTP request                        | PASS     | 10.959687ms  |\r\n|   2 | Extract status code                      | PASS     | 973.434µs    |\r\n|   3 | Verify status code                       | PASS     | 306.971µs    |\r\n|   4 | Extract response body                    | PASS     | 151.688µs    |\r\n|   5 | Verify expected content                  | PASS     | 475.234µs    |\r\n```\r\n\r\n**What this demonstrates:**\r\n- HTTP requests with response capture (`result: \"http_response\"`)\r\n- JSON data extraction using `jq` action (`.status_code`, `.body`)\r\n- Variable substitution and storage (`${http_response}`, `${status_code}`)\r\n- Assertions for validation (`assert` action)\r\n- Clean workflow structure with clear step-by-step execution\r\n- Performance timing for each step\r\n\r\n## Documentation\r\n\r\n### 📚 **Getting Started**\r\n- **[examples/README.md](examples/README.md)** - Comprehensive test examples from beginner to expert\r\n- **[docs/execution-flow-diagram.md](docs/execution-flow-diagram.md)** - Visual architecture flow diagram\r\n- **[docs/error-failure-states-diagram.md](docs/error-failure-states-diagram.md)** - Error handling and state management flow\r\n\r\n### 🏗️ **Architecture**\r\n- **[internal/README.md](internal/README.md)** - Core architecture principles and KISS design\r\n- **[internal/execution/README.md](internal/execution/README.md)** - Execution strategy pattern system\r\n- **[internal/actions/README.md](internal/actions/README.md)** - Complete action system documentation\r\n\r\n### 📖 **Reference**\r\n- **[docs/README.md](docs/README.md)** - Documentation overview and navigation guide\r\n- **[docs/junit-xml-output.md](docs/junit-xml-output.md)** - JUnit XML output format and CI/CD integration\r\n- **[examples/13-output-formats/README.md](examples/13-output-formats/README.md)** - Output format examples and usage patterns\r\n- **[CLAUDE.md](CLAUDE.md)** - Development instructions and project context\r\n\r\n## Action Categories\r\n\r\n### Core Actions\r\n- **`assert`** - Test assertions and validations\r\n- **`log`** - Logging and output messages  \r\n- **`variable`** - Variable manipulation and setting\r\n\r\n### HTTP \u0026 API Testing\r\n- **`http`** - HTTP requests (GET, POST, PUT, DELETE, etc.) with full header and authentication support\r\n\r\n### Database Operations\r\n- **`postgres`** - PostgreSQL database queries and operations\r\n- **`spanner`** - Google Cloud Spanner distributed database support\r\n\r\n### File Operations\r\n- **`file_read`** - Local file reading with format detection\r\n- **`scp`** - Secure file transfer via SSH/SFTP (upload/download)\r\n\r\n### Messaging Systems\r\n- **`kafka`** - Apache Kafka producer/consumer operations\r\n- **`rabbitmq`** - RabbitMQ message operations\r\n- **`swift_message`** - SWIFT financial messaging (MT103)\r\n\r\n### Data Processing\r\n- **`jq`** - JSON data processing and extraction\r\n- **`xpath`** - XML data processing and queries\r\n- **`json_parse`/`json_build`** - JSON parsing and construction\r\n- **`xml_parse`/`xml_build`** - XML parsing and construction\r\n- **`csv_parse`** - CSV file and string parsing with configurable delimiters, headers, and row limits\r\n\r\n### String \u0026 Encoding\r\n- **`string_random`** - Random string generation\r\n- **`string_replace`/`string_format`** - String manipulation\r\n- **`base64_encode`/`base64_decode`** - Base64 operations\r\n- **`url_encode`/`url_decode`** - URL encoding\r\n- **`hash`** - Cryptographic hashing (MD5, SHA1, SHA256)\r\n\r\n### Utilities\r\n- **`uuid`** - UUID v4 generation\r\n- **`time`** - Time operations and formatting\r\n- **`sleep`** - Delays and timing control\r\n- **`ping`** - Network connectivity testing with ICMP ping\r\n\r\n### Security \u0026 Validation\r\n- **`ssl_cert_check`** - SSL certificate validation, expiry checking, chain verification, and hostname validation\r\n\r\n## Test Structure\r\n\r\n### Example Tests\r\n\r\nRobogo includes 56 comprehensive test examples organized into 12 categories. Here are the key examples:\r\n\r\n| Category | Example | Features Demonstrated | Command |\r\n|----------|---------|----------------------|---------|\r\n| **HTTP Basics** | [01-http-get.yaml](examples/02-http/01-http-get.yaml) | GET requests, jq extraction, assertions | `./robogo run examples/02-http/01-http-get.yaml` |\r\n| **HTTP POST** | [02-http-post.yaml](examples/02-http/02-http-post.yaml) | POST with JSON, nested data extraction | `./robogo run examples/02-http/02-http-post.yaml` |\r\n| **Utilities** | [00-util.yaml](examples/01-basics/00-util.yaml) | UUID generation, basic logging | `./robogo run examples/01-basics/00-util.yaml` |\r\n| **Environment Variables** | [17-env-var-test.yaml](examples/10-security/17-env-var-test.yaml) | ${ENV:VAR} syntax, credential management | `./robogo run examples/10-security/17-env-var-test.yaml` |\r\n| **Security** | [19-no-log-security.yaml](examples/10-security/19-no-log-security.yaml) | no_log, sensitive_fields, data masking | `./robogo run examples/10-security/19-no-log-security.yaml` |\r\n| **Database** | [03-postgres-basic.yaml](examples/03-database/03-postgres-basic.yaml) | PostgreSQL operations, queries | `./robogo run examples/03-database/03-postgres-basic.yaml` |\r\n| **MongoDB** | [40-mongodb-basic.yaml](examples/03-database/40-mongodb-basic.yaml) | MongoDB document operations, aggregations | `./robogo run examples/03-database/40-mongodb-basic.yaml` |\r\n| **Conditional Logic** | [08-control-flow.yaml](examples/09-advanced/08-control-flow.yaml) | Conditional execution with if statements | `./robogo run examples/09-advanced/08-control-flow.yaml` |\r\n| **Retry Logic** | [13-retry-demo.yaml](examples/09-advanced/13-retry-demo.yaml) | Retry with backoff, error handling | `./robogo run examples/09-advanced/13-retry-demo.yaml` |\r\n| **Nested Steps** | [21-simple-nested-test.yaml](examples/09-advanced/21-simple-nested-test.yaml) | Grouped operations, continue-on-error | `./robogo run examples/09-advanced/21-simple-nested-test.yaml` |\r\n| **File Transfer** | [23-scp-simple-test.yaml](examples/05-files/23-scp-simple-test.yaml) | SSH/SFTP file operations | `./robogo run examples/05-files/23-scp-simple-test.yaml` |\r\n| **Network Testing** | [26-ping-network-test.yaml](examples/11-network/26-ping-network-test.yaml) | ICMP ping connectivity testing | `./robogo run examples/11-network/26-ping-network-test.yaml` |\r\n| **SSL Certificate** | [34-ssl-cert-check.yaml](examples/11-network/34-ssl-cert-check.yaml) | Certificate validation, expiry checks | `./robogo run examples/11-network/34-ssl-cert-check.yaml` |\r\n| **CSV Processing** | [35-csv-parsing.yaml](examples/06-data-processing/35-csv-parsing.yaml) | CSV parsing, extraction, filtering | `./robogo run examples/06-data-processing/35-csv-parsing.yaml` |\r\n\r\n**📁 Browse all examples:** See **[examples/README.md](examples/README.md)** for the complete catalog with beginner to expert examples.\r\n\r\n### Key Test Structure Elements\r\nAll Robogo tests follow this pattern:\r\n```yaml\r\ntestcase: \"Test Name\"\r\ndescription: \"What this test does\"\r\n\r\nvariables:\r\n  vars:\r\n    variable_name: \"value\"\r\n    api_url: \"${ENV:API_URL}\"  # Environment variables\r\n\r\nsteps:\r\n  - name: \"Make HTTP request with built-in extraction\"\r\n    action: http\r\n    args: [\"GET\", \"${api_url}\"]\r\n    extract:\r\n      type: \"jq\"\r\n      path: \".status_code\"\r\n    result: status_code\r\n    \r\n  - name: \"Verify result\"\r\n    action: assert\r\n    args: [\"${status_code}\", \"==\", \"200\"]\r\n```\r\n\r\n**Important:** Use `jq` action to extract data from HTTP responses - simple `${response.field}` syntax doesn't work for complex objects. You can either:\r\n1. **Use built-in `extract`** (modern approach): Add `extract` block to any step for automatic data extraction\r\n2. **Use separate `jq` step** (traditional approach): Extract in a separate step, then use the extracted value\r\n\r\n**Extract Types:** Robogo supports multiple built-in extract types:\r\n- `jq` - JSON path queries (`.field`, `.array[0]`, etc.)\r\n- `xpath` - XML path queries for XML data\r\n- `regex` - Regular expression pattern matching with capture groups\r\n- `csv` - CSV data extraction with row/column/cell extraction and filtering support\r\n\r\n**Advanced Features:** The examples table above includes advanced patterns like retry logic, control flow, nested steps, and security features. For the complete catalog with complexity levels, see **[examples/README.md](examples/README.md)**.\r\n\r\n## Security Features\r\n\r\n### Security Examples\r\n\r\nRobogo provides comprehensive security features for sensitive data handling:\r\n\r\n| Security Feature | Example | What It Demonstrates | Command |\r\n|-----------------|---------|---------------------|---------|\r\n| **Environment Variables** | [17-env-var-test.yaml](examples/10-security/17-env-var-test.yaml) | `${ENV:VAR}` syntax, credential management | `export TEST_ENV_VAR=\"test_value\" \u0026\u0026 ./robogo run examples/10-security/17-env-var-test.yaml` |\r\n| **Database Security** | [03-postgres-secure.yaml](examples/03-database/03-postgres-secure.yaml) | .env file usage, secure DB connections | `./robogo run examples/03-database/03-postgres-secure.yaml` |\r\n| **No-Log Mode** | [19-no-log-security.yaml](examples/10-security/19-no-log-security.yaml) | Complete logging suppression, sensitive fields | `./robogo run examples/10-security/19-no-log-security.yaml` |\r\n| **Step-Level Masking** | [20-step-level-masking.yaml](examples/10-security/20-step-level-masking.yaml) | Custom field masking, fine-grained controls | `./robogo run examples/10-security/20-step-level-masking.yaml` |\r\n\r\n**Key Security Features:**\r\n- **Automatic masking**: Password, token, key fields automatically hidden\r\n- **Custom masking**: Use `sensitive_fields: [\"field_name\"]` for custom fields\r\n- **No-log mode**: Use `no_log: true` to suppress all step logging\r\n- **Environment variables**: Use `${ENV:VARIABLE}` for secure credential access\r\n\r\n### Secret Management Philosophy\r\n\r\n**Robogo follows the principle of external secret management:**\r\n\r\n- **🔐 Pipeline Responsibility**: CI/CD pipelines and deployment systems should retrieve secrets from proper secret stores (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, etc.)\r\n- **📋 Environment Variable Injection**: Secrets are injected as environment variables using `${ENV:SECRET}` syntax\r\n- **🚫 No Built-in Secret Stores**: Robogo intentionally doesn't implement secret management to avoid reinventing security infrastructure\r\n- **🔌 Integration via Standards**: Uses standard environment variable patterns that work with any secret management system\r\n- **🏗️ Infrastructure Separation**: Secret management is an infrastructure concern, not an automation tool concern\r\n\r\n**Example Integration Patterns:**\r\n```bash\r\n# HashiCorp Vault\r\nexport API_TOKEN=\"$(vault kv get -field=token secret/api)\"\r\n\r\n# AWS Secrets Manager  \r\nexport DB_PASSWORD=\"$(aws secretsmanager get-secret-value --secret-id prod/db/password --query SecretString --output text)\"\r\n\r\n# Kubernetes Secrets (in pod)\r\nexport API_KEY=\"$(cat /var/secrets/api-key)\"\r\n\r\n# CI/CD Pipeline (GitHub Actions)\r\nexport DATABASE_URL=\"${{ secrets.DATABASE_URL }}\"\r\n```\r\n\r\n**Why This Approach:**\r\n- ✅ **Security Best Practice**: Leverages proven, audited secret management systems\r\n- ✅ **Flexibility**: Works with any secret store or deployment pattern  \r\n- ✅ **Separation of Concerns**: Automation logic separate from credential management\r\n- ✅ **Compliance Ready**: Integrates with enterprise security policies\r\n- ✅ **No Vendor Lock-in**: Not tied to specific secret management solutions\r\n\r\n## Development Environment\r\n\r\n### Prerequisites\r\n- Go 1.24+\r\n- Docker \u0026 Docker Compose (for services)\r\n\r\n### Development Services\r\n\r\n```bash\r\n# Start all services\r\ndocker-compose up -d\r\n\r\n# Services available:\r\n# - PostgreSQL: localhost:5432 (user: robogo_testuser, pass: robogo_testpass, db: robogo_testdb)\r\n# - Kafka: localhost:9092  \r\n# - Spanner Emulator: localhost:9010\r\n# - HTTPBin: localhost:8000\r\n# - SSH Server: localhost:2222 (user: testuser, pass: testpass)\r\n```\r\n\r\n### Environment Configuration\r\n\r\nCreate `.env` file for secure credential management:\r\n```bash\r\n# Database credentials\r\nDB_HOST=localhost\r\nDB_PORT=5432\r\nDB_USER=robogo_testuser\r\nDB_PASSWORD=robogo_testpass\r\nDB_NAME=robogo_testdb\r\n\r\n# API credentials\r\nAPI_BASE_URL=https://api.example.com\r\nAPI_TOKEN=your_secret_token_here\r\n\r\n# SSH credentials for SCP testing\r\nSSH_PASSWORD=testpass\r\n```\r\n\r\n### Database Setup\r\n\r\n**PostgreSQL** - Use environment variables for credentials:\r\n```yaml\r\nvariables:\r\n  vars:\r\n    db_url: \"postgres://${ENV:DB_USER}:${ENV:DB_PASSWORD}@${ENV:DB_HOST}:${ENV:DB_PORT}/${ENV:DB_NAME}?sslmode=disable\"\r\n\r\nsteps:\r\n  - name: \"Test database connection\"\r\n    action: postgres\r\n    args: [\"query\", \"${db_url}\", \"SELECT version()\"]\r\n    result: db_version\r\n```\r\n\r\n**Google Cloud Spanner** - Set up emulator:\r\n```bash\r\n# After starting docker-compose\r\n# Linux/Mac:\r\nSPANNER_EMULATOR_HOST=localhost:9010 ./setup-spanner.sh\r\n# Windows:\r\n.\\setup-spanner.ps1\r\n```\r\n\r\n## Example Tests\r\n\r\nThe **[examples/](examples/)** directory contains 56 comprehensive test examples organized into 12 categories by feature and complexity:\r\n\r\n### Quick Examples\r\n```bash\r\n# HTTP testing (no services required)\r\n./robogo run examples/02-http/01-http-get.yaml\r\n\r\n# Database testing (requires docker-compose up -d)\r\n./robogo run examples/03-database/03-postgres-basic.yaml\r\n\r\n# SCP file transfer testing\r\n./robogo run examples/05-files/23-scp-simple-test.yaml\r\n\r\n# Messaging systems\r\n./robogo run examples/04-messaging/05-kafka-basic.yaml\r\n\r\n# Security features\r\n./robogo run examples/10-security/19-no-log-security.yaml\r\n```\r\n\r\n### Example Categories\r\n- **Beginner**: Basic HTTP, database, and file operations\r\n- **Intermediate**: Multi-step workflows, environment variables, data extraction\r\n- **Advanced**: Complex control flow, retry logic, nested operations\r\n- **Expert**: Security-aware testing, production-ready patterns\r\n\r\n## Architecture\r\n\r\n### KISS Principles\r\nRobogo follows **Keep It Simple and Straightforward** architecture:\r\n\r\n- **No Dependency Injection**: Direct object construction throughout\r\n- **No Over-abstraction**: Simple, direct implementations\r\n- **Minimal Interfaces**: Only where absolutely necessary\r\n- **Strategy Pattern**: Clean execution routing for different step types\r\n\r\n### Design Philosophy: Explicit Tests Over Loops\r\n\r\nRobogo intentionally **does not support `for` and `while` loops** in test definitions. This design decision prioritizes **test clarity and maintainability** over code brevity.\r\n\r\n**Why no loops?**\r\n- **Test purpose matters**: Behavioral tests should be explicit about what they're testing\r\n- **Debugging clarity**: `test_user_creation_with_missing_email()` is clearer than \"step 7 failed in user creation loop\"\r\n- **Living documentation**: Tests serve as executable specifications - loops obscure intent\r\n- **Industry alignment**: Most YAML-based testing frameworks avoid complex control flow\r\n\r\n**When to use explicit tests vs loops:**\r\n- ✅ **Explicit tests for**: Business logic validation, user workflows, API contract testing\r\n- ❌ **Avoid loops for**: Individual test scenarios, specific edge cases, acceptance criteria\r\n- ⚠️ **Loops might be appropriate for**: Framework testing, property-based testing, infrastructure validation\r\n\r\n**Example of preferred explicit approach:**\r\n```yaml\r\n# ✅ Clear and maintainable\r\nsteps:\r\n  - name: \"User registration accepts valid email\"\r\n    action: http\r\n    args: [\"POST\", \"/users\", '{\"email\": \"user@example.com\"}']\r\n    \r\n  - name: \"User registration rejects email without @\"\r\n    action: http  \r\n    args: [\"POST\", \"/users\", '{\"email\": \"invalid-email\"}']\r\n```\r\n\r\nInstead of:\r\n```yaml  \r\n# ❌ Obscures test intent\r\nsteps:\r\n  - name: \"Test email validation\"\r\n    for: \"[user@example.com, invalid-email]\"\r\n    action: http\r\n    args: [\"POST\", \"/users\", '{\"email\": \"${item}\"}']\r\n```\r\n\r\nThis philosophy aligns with industry best practices where test automation frameworks either avoid loops entirely (GitHub Actions) or use specialized syntax (Robot Framework) rather than general-purpose loops.\r\n\r\n### Execution Flow\r\n1. **CLI** receives command and parses YAML test file\r\n2. **TestRunner** creates execution environment with variables and strategy router\r\n3. **ExecutionStrategyRouter** routes steps based on priority:\r\n   - **ConditionalExecutionStrategy** (Priority 4): Handles `if` conditions\r\n   - **RetryExecutionStrategy** (Priority 3): Handles `retry` configuration\r\n   - **NestedStepsExecutionStrategy** (Priority 2): Handles `steps` arrays\r\n   - **BasicExecutionStrategy** (Priority 1): Handles simple actions\r\n4. **Actions** perform actual operations and return structured results\r\n5. **Results** are processed, masked for security, and displayed\r\n\r\nFor detailed architecture documentation, see **[internal/README.md](internal/README.md)** and **[docs/execution-flow-diagram.md](docs/execution-flow-diagram.md)**.\r\n\r\n## Error Handling\r\n\r\n### Dual Error System\r\n- **ErrorInfo**: Technical problems (network failures, syntax errors, etc.)\r\n- **FailureInfo**: Logical test failures (assertion failures, unexpected responses)\r\n\r\n### Visual Error Flow Diagram\r\nFor a comprehensive visual explanation of Robogo's error handling, execution flow, and state management, see:\r\n**[docs/error-failure-states-diagram.md](docs/error-failure-states-diagram.md)** - Complete mermaid diagram showing execution strategies, error classification, and result processing.\r\n\r\n### Structured Error Messages\r\n```yaml\r\n# Technical error example\r\nsteps:\r\n  - name: \"Invalid database query\"\r\n    action: postgres\r\n    args: [\"query\", \"invalid://connection\", \"SELECT 1\"]\r\n    # Results in ErrorInfo with connection details and suggestions\r\n\r\n# Logical failure example  \r\n  - name: \"Assertion failure\"\r\n    action: assert\r\n    args: [\"${status_code}\", \"==\", \"200\"]  # After extracting with jq\r\n    # Results in FailureInfo showing expected vs actual values\r\n```\r\n\r\n## Shift-Left Testing Benefits\r\n\r\nRobogo enables **true shift-left testing** by allowing developers to:\r\n\r\n### For Developers\r\n- **Run Full E2E Tests Locally**: Complete integration tests with databases, messaging, and external APIs\r\n- **Clear Test Intent**: YAML format makes test logic immediately visible and understandable\r\n- **Fast Feedback**: Quick test execution with immediate connection handling\r\n- **Easy Setup**: Simple environment setup for comprehensive testing\r\n\r\n### For Teams\r\n- **Improved Collaboration**: QA and developers can read and modify the same test definitions\r\n- **Living Documentation**: Tests serve as executable specifications of system behavior\r\n- **Early Bug Detection**: Catch integration issues before they reach staging environments\r\n- **Reduced Testing Debt**: E2E tests written during development, not as an afterthought\r\n\r\n### Example: Developer Workflow\r\n```bash\r\n# 1. Run relevant tests during development\r\n./robogo run tests/user-registration-flow.yaml\r\n./robogo run tests/payment-processing.yaml\r\n\r\n# 2. Validate changes before commit\r\n./robogo run tests/critical-paths.yaml\r\n\r\n# 3. Run in CI/CD pipeline\r\n./robogo run tests/smoke-tests.yaml\r\n```\r\n\r\n## Parallel Execution\r\n\r\nRobogo is designed for **test-level parallelism** (multiple test files) rather than **step-level parallelism** (steps within a test).\r\n\r\n### ⚠️ Output Mixing Issue\r\n\r\nWhen running tests in parallel **without output redirection**, the stdout will be mixed and confusing:\r\n\r\n```bash\r\n# ❌ This will create mixed, unreadable output\r\n./robogo run test1.yaml \u0026 \\\r\n./robogo run test2.yaml \u0026 \\\r\n./robogo run test3.yaml \u0026 \\\r\nwait\r\n```\r\n\r\n### ✅ Recommended Parallel Approaches\r\n\r\n**Option 1: Redirect to separate files**\r\n```bash\r\n# Each test outputs to its own file\r\n./robogo run test1.yaml \u003e test1.log 2\u003e\u00261 \u0026 \\\r\n./robogo run test2.yaml \u003e test2.log 2\u003e\u00261 \u0026 \\\r\n./robogo run test3.yaml \u003e test3.log 2\u003e\u00261 \u0026 \\\r\nwait\r\n\r\n# View results separately\r\ncat test1.log test2.log test3.log\r\n```\r\n\r\n**Option 2: Run sequentially with timing**\r\n```bash\r\n# Fast sequential execution, readable output\r\ntime ./robogo run test1.yaml\r\ntime ./robogo run test2.yaml  \r\ntime ./robogo run test3.yaml\r\n```\r\n\r\n**Option 3: Use CI/CD parallelism**\r\n```yaml\r\n# GitHub Actions example\r\njobs:\r\n  test:\r\n    strategy:\r\n      matrix:\r\n        test: [test1.yaml, test2.yaml, test3.yaml]\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - run: ./robogo run ${{ matrix.test }}\r\n```\r\n\r\n### Why Sequential Steps?\r\nSteps within a test are intentionally sequential because they represent a logical flow where later steps depend on earlier results:\r\n\r\n```yaml\r\nsteps:\r\n  - name: \"Create user\"\r\n    action: http\r\n    args: [\"POST\", \"/users\", \"...\"]\r\n    result: response\r\n    \r\n  - name: \"Verify user created\"  # This DEPENDS on the above step\r\n    action: assert\r\n    args: [\"${status_code}\", \"==\", \"201\"]  # After extracting with jq\r\n```\r\n\r\n## Test Data Management\r\n\r\nRobogo **does not include built-in test data management** (fixtures, factories, seeding utilities) and is intentionally designed this way following KISS principles.\r\n\r\n### Design Philosophy\r\n\r\n- **No Over-abstraction**: Use actual database/API operations instead of data management frameworks\r\n- **Direct Operations**: Tests perform real operations that mirror production workflows\r\n- **External Integration**: Leverage existing data tools rather than reinventing them\r\n- **Transparency**: Clear visibility into what data operations are happening\r\n\r\n### Recommended Approaches\r\n\r\n**Setup/Teardown with Database Actions:**\r\n```yaml\r\nsetup:\r\n  - name: \"Create test data\"\r\n    action: postgres\r\n    args: [\"execute\", \"${db_url}\", \"INSERT INTO users (name, email) VALUES ('Test User', 'test@example.com')\"]\r\n\r\nteardown:\r\n  - name: \"Clean up test data\"  \r\n    action: postgres\r\n    args: [\"execute\", \"${db_url}\", \"DELETE FROM users WHERE email = 'test@example.com'\"]\r\n```\r\n\r\n**API-Based Data Management:**\r\n```yaml\r\nsetup:\r\n  - name: \"Create test user via API\"\r\n    action: http\r\n    args: [\"POST\", \"${api_url}/users\", \"${user_data}\"]\r\n    extract:\r\n      type: \"jq\"\r\n      path: \".body.id\"\r\n    result: user_id\r\n\r\nteardown:\r\n  - name: \"Delete test user\"\r\n    action: http\r\n    args: [\"DELETE\", \"${api_url}/users/${user_id}\"]\r\n```\r\n\r\n**External Scripts Integration:**\r\n```yaml\r\nsetup:\r\n  - name: \"Seed test database\"\r\n    action: bash\r\n    args: [\"./scripts/seed-test-data.sh\", \"${ENV:TEST_ENVIRONMENT}\"]\r\n```\r\n\r\n**Dynamic Data Generation:**\r\n```yaml\r\n- name: \"Generate unique test data\"\r\n  action: time\r\n  args: [\"20060102150405\"]\r\n  result: timestamp\r\n\r\n- name: \"Create unique user email\"\r\n  action: string_format\r\n  args: [\"test-user-{}@example.com\", \"${timestamp}\"]\r\n  extract:\r\n    type: \"jq\"\r\n    path: \".result\"\r\n  result: unique_email\r\n```\r\n\r\nThis approach maintains test clarity while allowing flexible integration with existing data management tools and practices.\r\n\r\n## Test Scheduling\r\n\r\nRobogo is designed as a **single-execution CLI tool** that runs individual tests on-demand and exits cleanly. It **does not have built-in scheduling capabilities** and is intentionally architected this way following KISS principles.\r\n\r\n### Design Philosophy\r\n- **No Built-in Scheduling**: No cron, timers, or background job processing\r\n- **CLI-First Design**: Meant to be invoked manually or by external schedulers  \r\n- **Immediate Execution Model**: Runs test → exits (no persistent processes)\r\n- **External Integration**: Designed to work with existing scheduling infrastructure\r\n\r\n### Scheduling Options\r\n\r\n**Cron (Linux/Mac)**\r\n```bash\r\n# Run test every hour\r\n0 * * * * /path/to/robogo run /path/to/test.yaml\r\n\r\n# Run test every 5 minutes\r\n*/5 * * * * /path/to/robogo run /path/to/test.yaml \u003e\u003e /var/log/robogo.log 2\u003e\u00261\r\n\r\n# Run test daily at 2 AM\r\n0 2 * * * /path/to/robogo run /path/to/nightly-test.yaml\r\n```\r\n\r\n**Windows Task Scheduler**\r\n```powershell\r\n# Create scheduled task that runs robogo\r\nschtasks /create /tn \"RobogoTest\" /tr \"C:\\path\\to\\robogo.exe run test.yaml\" /sc hourly\r\n```\r\n\r\n**CI/CD Pipeline Scheduling**\r\n```yaml\r\n# GitHub Actions example\r\nname: Scheduled Tests\r\non:\r\n  schedule:\r\n    - cron: '0 */6 * * *'  # Every 6 hours\r\njobs:\r\n  test:\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - uses: actions/checkout@v3\r\n      - name: Run Integration Tests\r\n        run: ./robogo run examples/12-integration/09-e2e-integration.yaml\r\n```\r\n\r\n**Docker with Cron**\r\n```dockerfile\r\nFROM golang:1.21-alpine\r\nCOPY robogo /usr/local/bin/robogo\r\nCOPY tests/ /tests/\r\n# Add cron job\r\nRUN echo \"0 */2 * * * /usr/local/bin/robogo run /tests/health-check.yaml\" | crontab -\r\nCMD [\"crond\", \"-f\"]\r\n```\r\n\r\n**Kubernetes CronJob**\r\n```yaml\r\napiVersion: batch/v1\r\nkind: CronJob\r\nmetadata:\r\n  name: robogo-tests\r\nspec:\r\n  schedule: \"0 */4 * * *\"  # Every 4 hours\r\n  jobTemplate:\r\n    spec:\r\n      template:\r\n        spec:\r\n          containers:\r\n          - name: robogo\r\n            image: robogo:latest\r\n            command: [\"./robogo\", \"run\", \"tests/smoke-test.yaml\"]\r\n          restartPolicy: OnFailure\r\n```\r\n\r\n### Why External Scheduling?\r\n\r\nThis design aligns with robogo's **KISS architecture** principles:\r\n- **Simple \u0026 Direct**: Focus on reliable test execution, not infrastructure concerns\r\n- **CLI Tool Design**: Clean exit, no hanging processes, easy integration\r\n- **Immediate Connections**: Open/close per operation, no persistent state to manage\r\n- **Minimal Dependencies**: Let existing tools handle scheduling rather than reinventing\r\n\r\n**Benefits:**\r\n- **Reliability**: Use proven scheduling systems (cron, K8s, CI/CD)\r\n- **Flexibility**: Any scheduling system can invoke robogo\r\n- **Simplicity**: No complex scheduling logic to maintain or debug\r\n- **Integration**: Works seamlessly with existing infrastructure\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Service connection errors**: Ensure Docker services are running (`docker-compose ps`)\r\n2. **Environment variable issues**: Check `.env` file exists and variables are properly formatted\r\n3. **SCP/SSH connection issues**: Verify SSH server is running and credentials are correct\r\n4. **Variable resolution errors**: Check `${variable}` syntax and variable names\r\n5. **Database connection errors**: Verify Docker services are healthy\r\n\r\n### Debug Tips\r\n\r\n- Use `log` actions to inspect variable values\r\n- Check Docker service logs: `docker-compose logs \u003cservice\u003e`\r\n- Use shorter timeouts for faster feedback during development\r\n- Enable verbose logging for debugging complex variable substitution\r\n\r\n### Getting Help\r\n\r\n- **Documentation**: Start with **[examples/README.md](examples/README.md)** for practical examples\r\n- **Architecture**: See **[internal/README.md](internal/README.md)** for understanding the codebase\r\n- **Issues**: Report bugs or feature requests on the project repository\r\n\r\n## Contributing\r\n\r\n1. **Follow KISS principles**: Avoid over-engineering and complex abstractions\r\n2. **Add examples**: Every new feature should include working test examples\r\n3. **Update documentation**: Keep README files current with code changes\r\n4. **Security-first**: Ensure sensitive data is properly masked\r\n5. **Test thoroughly**: Verify examples work with standard Docker setup\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjianloong%2Frobogo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjianloong%2Frobogo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjianloong%2Frobogo/lists"}