|
| 1 | +# Cloud Provider Integration |
| 2 | + |
| 3 | +maestro-runner automatically detects cloud Appium providers from the `--appium-url` and reports test pass/fail after the run completes. |
| 4 | + |
| 5 | +## Supported providers |
| 6 | + |
| 7 | +- [TestingBot](testingbot.md) |
| 8 | +- [Sauce Labs](saucelabs.md) |
| 9 | + |
| 10 | +## How it works |
| 11 | + |
| 12 | +1. **Detect** — after `--appium-url` is parsed, each registered provider checks if the URL matches (e.g., contains "saucelabs") |
| 13 | +2. **Extract metadata** — after the Appium session is created, the provider reads session capabilities and stores provider-specific data (job IDs, session type, etc.) in a `map[string]string` |
| 14 | +3. **Report result** — after all flows and reports complete, the provider receives the full test result and reports pass/fail to the cloud API |
| 15 | + |
| 16 | +No extra flags needed — detection and reporting happen automatically. |
| 17 | + |
| 18 | +## Adding a new provider |
| 19 | + |
| 20 | +All provider code lives in `pkg/cloud/`. To add a new provider: |
| 21 | + |
| 22 | +### 1. Create the file |
| 23 | + |
| 24 | +Copy `pkg/cloud/example_provider.go` to `pkg/cloud/<yourprovider>.go`. |
| 25 | + |
| 26 | +### 2. Implement the Provider interface |
| 27 | + |
| 28 | +```go |
| 29 | +package cloud |
| 30 | + |
| 31 | +type Provider interface { |
| 32 | + // Name returns the human-readable provider name. |
| 33 | + Name() string |
| 34 | + |
| 35 | + // ExtractMeta is called once after the Appium session is created. |
| 36 | + // Read what you need from sessionID and caps, write to meta. |
| 37 | + ExtractMeta(sessionID string, caps map[string]interface{}, meta map[string]string) |
| 38 | + |
| 39 | + // ReportResult is called once after all flows and reports complete. |
| 40 | + // Use meta for provider-specific data, result for test outcome. |
| 41 | + ReportResult(appiumURL string, meta map[string]string, result *TestResult) error |
| 42 | +} |
| 43 | +``` |
| 44 | + |
| 45 | +### 3. Register via init() |
| 46 | + |
| 47 | +The factory function checks the URL and returns a provider or `nil`: |
| 48 | + |
| 49 | +```go |
| 50 | +func init() { |
| 51 | + Register(func(appiumURL string) Provider { |
| 52 | + if !strings.Contains(strings.ToLower(appiumURL), "yourprovider") { |
| 53 | + return nil |
| 54 | + } |
| 55 | + return &yourProvider{} |
| 56 | + }) |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +### 4. Example skeleton |
| 61 | + |
| 62 | +A complete skeleton is available at `pkg/cloud/example_provider.go`. Copy it, rename, and implement the TODOs. |
| 63 | + |
| 64 | +### 5. Add tests |
| 65 | + |
| 66 | +Create `pkg/cloud/<yourprovider>_test.go` with tests for: |
| 67 | +- URL detection (matches your provider, rejects others) |
| 68 | +- ExtractMeta (correct meta keys) |
| 69 | +- ReportResult (use `httptest.NewServer` to verify endpoint, auth, body) |
| 70 | + |
| 71 | +### 6. Add documentation |
| 72 | + |
| 73 | +Create `docs/cloud-providers/<yourprovider>.md` with: |
| 74 | +- Run command example |
| 75 | +- Example capabilities JSON |
| 76 | +- Any provider-specific notes |
| 77 | + |
| 78 | +Add a link in the main `README.md` under **Cloud Providers** and in this file under **Supported providers**. |
| 79 | + |
| 80 | +## TestResult fields |
| 81 | + |
| 82 | +`ReportResult` receives the full test outcome. Use what your provider's API supports: |
| 83 | + |
| 84 | +```go |
| 85 | +type TestResult struct { |
| 86 | + Passed bool // overall pass/fail |
| 87 | + Total int // total flow count |
| 88 | + PassedCount int // flows that passed |
| 89 | + FailedCount int // flows that failed |
| 90 | + Duration int64 // total duration in milliseconds |
| 91 | + OutputDir string // path to log, reports, screenshots |
| 92 | + Flows []FlowResult // per-flow details |
| 93 | +} |
| 94 | + |
| 95 | +type FlowResult struct { |
| 96 | + Name string // flow name |
| 97 | + Passed bool // this flow passed |
| 98 | + Duration int64 // milliseconds |
| 99 | + Error string // error message (empty if passed) |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +- Most providers only need `result.Passed` for a simple pass/fail update |
| 104 | +- `result.Flows` is available for providers that support per-test annotations |
| 105 | +- `result.OutputDir` contains `maestro-runner.log`, `report.html`, `report.json`, `junit-report.xml`, and screenshots — providers can upload these if their API supports artifacts |
| 106 | + |
| 107 | +## Meta map |
| 108 | + |
| 109 | +The `meta map[string]string` is owned by the caller and passed through `ExtractMeta` → `ReportResult`. Each provider writes its own keys. Examples: |
| 110 | + |
| 111 | +| Provider | Keys | Description | |
| 112 | +|----------|------|-------------| |
| 113 | +| Sauce Labs | `jobID`, `type` | `type` is "rdc" (real device) or "vms" (emulator/simulator) | |
| 114 | +| (new provider) | `jobID` | Typically the WebDriver session ID | |
| 115 | + |
| 116 | +No naming conflicts since only one provider is active per session. |
| 117 | + |
| 118 | +## Credentials |
| 119 | + |
| 120 | +Each provider handles credentials internally in `ReportResult`. The common pattern is: |
| 121 | + |
| 122 | +1. Extract from `--appium-url` userinfo (e.g., `https://USER:KEY@hub.example.com`) |
| 123 | +2. Fall back to provider-specific environment variables |
| 124 | + |
| 125 | +This keeps credential logic out of the shared interface. |
| 126 | + |
| 127 | +## Error handling |
| 128 | + |
| 129 | +`ReportResult` errors are logged as warnings — they never fail the test run. Local test results and reports are always generated regardless of cloud reporting success. |
0 commit comments