@vostride/agent-qa-plugin-browserstack 0.0.0-stage → 0.3.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Pranshu Chittora
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/NOTICE.md

@@ -0,0 +1,11 @@
+# agent-qa Notice
+
+agent-qa is provided by Pranshu Chittora.
+
+Copyright 2026 Pranshu Chittora
+
+agent-qa is licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2). See `LICENSE.md` for the full license terms.
+
+Under the Grant of Future License in `LICENSE.md`, each version of the Software is also granted under the Apache License, Version 2.0 effective on the second anniversary of the date that version was made available.
+
+Third-party dependencies are distributed under their own license terms. This notice covers agent-qa itself and does not replace or modify notices required by third-party dependency owners.

package/README.md

@@ -1,3 +1,250 @@
-# Temporary Holding Version
+# @vostride/agent-qa-plugin-browserstack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The agent-qa plugin for [BrowserStack](https://www.browserstack.com). It runs agent-qa web tests on
+BrowserStack browsers over the Playwright protocol, and device tests on BrowserStack Android and
+iOS devices over Appium. It uploads a target's app once per content, returns each session's
+dashboard link and marks each session with the test's outcome.
+
+## Install
+
+Install the plugin at exactly the version of agent-qa the project runs:
+
+```bash
+npm install --save-dev --save-exact @vostride/agent-qa-plugin-browserstack@<agent-qa version>
+```
+
+`agent-qa plugins list` prints this line, with the version filled in, when the package is missing
+or its version differs from agent-qa's.
+
+## Configure
+
+```yaml
+plugins:
+  - name: browserstack
+    package: "@vostride/agent-qa-plugin-browserstack"
+    options:
+      username: "{{secret:BROWSERSTACK_USERNAME}}"
+      accessKey: "{{secret:BROWSERSTACK_ACCESS_KEY}}"
+
+registry:
+  remotes:
+    - name: browserstack
+      plugin: browserstack
+      settings:
+        os: Windows
+        osVersion: "11"
+    - name: browserstack-devices
+      plugin: browserstack
+  devices:
+    bs-pixel:
+      platform: android
+      remote: browserstack-devices
+      model: Google Pixel 9
+      os: "15"
+```
+
+A web test runs on BrowserStack with `use.browser.remote: browserstack` in the config, a suite or
+the test. A device test runs there when its target's `device` is a device whose `remote` is a
+BrowserStack remote.
+
+### Options
+
+Options belong to the `plugins` entry and describe the account.
+
+| Option            | Default                                 | Meaning                                                              |
+| ----------------- | --------------------------------------- | -------------------------------------------------------------------- |
+| `username`        | required                                | The BrowserStack username, a credential.                             |
+| `accessKey`       | required                                | The BrowserStack access key, a credential.                           |
+| `apiUrl`          | `https://api.browserstack.com`          | The Automate API: web session lookups, marks and the plan.           |
+| `appApiUrl`       | `https://api-cloud.browserstack.com`    | The App Automate API: uploads, device sessions, the plan.            |
+| `hubUrl`          | `https://hub.browserstack.com/wd/hub`   | The Appium hub device sessions connect to.                           |
+| `playwrightUrl`   | `wss://cdp.browserstack.com/playwright` | The Playwright endpoint web sessions connect to.                     |
+| `local`           | `false`                                 | Start a BrowserStack Local tunnel for the run.                       |
+| `localIdentifier` | -                                       | The tunnel's identifier; without `local`, a tunnel already running.  |
+| `localBinary`     | -                                       | The BrowserStackLocal binary `local` runs, instead of the wrapper's. |
+
+Write the credentials as `{{secret:<name>}}` references. The endpoints must use `https://`
+(`wss://` for `playwrightUrl`) and carry no user or password, unless they point at this machine;
+otherwise the entry is refused at the option's path. The credentials travel only in the masked
+Playwright URL, in the `bstack:options` agent-qa masks and in the basic auth header of REST calls.
+They never appear in a message, a log or an answer.
+
+### Settings
+
+Settings belong to each remote and describe one place.
+
+| Setting          | Default    | Meaning                                                                               |
+| ---------------- | ---------- | ------------------------------------------------------------------------------------- |
+| `os`             | `OS X`     | The web session's operating system, for example `Windows`.                            |
+| `osVersion`      | `Sequoia`  | The operating system version, for example `11` or `Sequoia`.                          |
+| `browser`        | by engine  | `chrome`, `edge`, `playwright-chromium`, `playwright-firefox` or `playwright-webkit`. |
+| `browserVersion` | -          | The Chrome or Edge version, for example `latest` or `latest-1`.                       |
+| `project`        | `agent-qa` | The BrowserStack project sessions are filed under.                                    |
+| `build`          | the run id | The BrowserStack build name.                                                          |
+| `appiumVersion`  | `3.5.2`    | The Appium version device sessions ask for.                                           |
+| `extra`          | -          | Capabilities merged last, overriding the ones above.                                  |
+
+`agent-qa plugins describe browserstack` prints the same tables from the schemas the package
+ships, and `--json` prints them as JSON.
+
+## Web tests
+
+A web acquire answers the Playwright URL with a `caps` query holding JSON capabilities:
+
+- `browserstack.username` and `browserstack.accessKey`;
+- `browser`: `settings.browser`, or by the test's engine, `chrome` for Chromium,
+  `playwright-firefox` for Firefox and `playwright-webkit` for WebKit. A browser that cannot run
+  the test's engine is refused at `settings.browser`;
+- `os`, `os_version` and, when set, `browser_version`;
+- `client.playwrightVersion`: agent-qa's Playwright version;
+- `project`, `build` (the run id unless `settings.build` is set) and `name` (the test's name);
+- `settings.extra`, merged last.
+
+The query carries the access key, so agent-qa masks the whole URL.
+
+### Playwright versions
+
+BrowserStack runs a web session with the Playwright version its client asks for, and only versions
+BrowserStack lists. No API lists them, so the plugin carries BrowserStack's list: today Playwright
+1.59 to 1.63. When agent-qa's Playwright major.minor is not on the list, every web test on
+BrowserStack is refused with kind `version`:
+
+```text
+BrowserStack lists Playwright 1.59 to 1.63, not 1.64, so web tests cannot run there yet; run this test here or on another remote.
+```
+
+The list moves with each plugin release, which follows agent-qa's version. When BrowserStack adds
+a version, a plugin release adds it, and `agent-qa doctor` stops warning.
+
+## Device tests
+
+A device acquire answers `hubUrl` with `bstack:options` holding:
+
+- `userName` and `accessKey`;
+- `appiumVersion`: the device's own `bstack:options.appiumVersion`, then `settings.appiumVersion`,
+  then the plugin's default, `3.5.2`;
+- `projectName`, `buildName` (the run id unless `settings.build` is set) and `sessionName` (the
+  test's name);
+- `settings.extra`, merged last.
+
+agent-qa adds the device's identity: `model` as `appium:deviceName` and `os` as
+`appium:platformVersion`. The device's own `capabilities` are merged over the answer.
+
+## Uploads and reuse
+
+When a target sets `app.ref` (a `bs://` id or an `https` URL), BrowserStack installs that app and
+the plugin uploads nothing.
+
+The plugin's `uploadApp` takes the target's `app.path`:
+
+1. it names the content with the custom id `agent-qa-<first 32 hex of the file's SHA-256>`;
+2. it asks `GET app-automate/recent_apps/<custom id>` and reuses the newest upload listed there;
+3. when nothing is listed, it checks that the file still has the size and SHA-256 agent-qa sent,
+   refusing it at path `path` when it changed, then posts the file once to
+   `POST app-automate/upload` with that custom id, reporting `uploading app (<n> MB)` and then
+   `app uploaded` as progress.
+
+It answers the `bs://` ref the session installs. The same file uploads once, and later runs reuse
+it while BrowserStack keeps it, which is 30 days. A cancel stops the upload.
+
+## Links and marks
+
+When a session starts, the plugin returns its dashboard link, BrowserStack's `browser_url`. It needs
+a BrowserStack login. The shareable `public_url` is never returned.
+
+- A device session is read by its WebDriver session id from
+  `GET app-automate/sessions/<id>.json`.
+- A web session is found through the Automate REST API. The plugin lists running builds
+  (`GET automate/builds.json`), keeps the build named for the run, lists its running sessions and
+  keeps those with the test's name. It then reads each one's details and keeps those whose
+  `created_at` is no more than 5 seconds before agent-qa asked for the session. When exactly one
+  is left, that is the session. When none or several are left, the test gets no link and the
+  session stays unmarked, with one line on the plugin's stderr. A guessed session is never marked.
+
+When the test ends, the plugin marks the session:
+
+| Outcome          | Mark                                             |
+| ---------------- | ------------------------------------------------ |
+| passed           | `passed`                                         |
+| failed           | `failed`, with the reason, cut to 255 characters |
+| agent-qa's error | `failed`, with agent-qa's sentence               |
+| cancelled        | none                                             |
+
+Marks go to `PUT automate/sessions/<id>.json` for web and `PUT app-automate/sessions/<id>.json`
+for devices. A lookup or a mark that fails is one stderr line and never fails the test.
+
+## Failures
+
+| BrowserStack answer   | Kind          |
+| --------------------- | ------------- |
+| `401`                 | `auth`        |
+| `429`                 | `capacity`    |
+| no answer             | `unreachable` |
+| any other non-success | `refused`     |
+
+Each failure is one line naming the status, the request and BrowserStack's message, with
+`retry after` on a `429`. A Playwright version BrowserStack does not list is kind `version`. A
+setting or option that is wrong is kind `refused` with its path. A BrowserStack Local tunnel that
+cannot start is kind `unreachable` at path `options.local`, or `options.localBinary` when that is
+set.
+
+## Account check
+
+`agent-qa doctor` runs the plugin's `check`, which opens no session:
+
+- `GET automate/plan.json` and `GET app-automate/plan.json` report each product's sessions, for
+  example `Automate: 1 of 5 parallel sessions running, 0 queued`.
+- A `401` on either warns `the username or access key was refused`.
+- A `404` warns that the product is not on the account, for example
+  `App Automate is not on this account`.
+- When BrowserStack does not list agent-qa's Playwright version, it warns
+  `BrowserStack lists Playwright 1.59 to 1.63, not 1.64; web tests on BrowserStack are refused until it does.`
+
+## BrowserStack Local
+
+BrowserStack Local is a tunnel that lets BrowserStack's browsers and devices reach a target only
+this machine can reach, such as `localhost` or a staging host behind a VPN.
+
+- `local: true` makes the plugin start its own tunnel on the run's first acquire, with a fresh
+  identifier, `agent-qa-<16 hex>`, or with `localIdentifier` when that is set too. The start
+  counts against the acquire's deadline, and acquires that arrive while it starts wait for the
+  same tunnel. Every web and device session of the run then asks for that tunnel:
+  `browserstack.local` and `browserstack.localIdentifier` in the web capabilities, `local` and
+  `localIdentifier` in `bstack:options`.
+- `localIdentifier` without `local` asks every session for a tunnel that is already running
+  under that identifier, and the plugin starts nothing.
+- The tunnel comes from BrowserStack's `browserstack-local` package, pinned at `1.5.16`. It finds
+  BrowserStack's binary in `~/.browserstack`, the working directory or the temp directory, and
+  downloads it from BrowserStack over `https` when none is there. `localBinary` names a binary
+  to run instead; it needs `local: true`. When a binary fails, the plugin never deletes it or
+  downloads another one; the next acquire runs the same binary again.
+- The tunnel logs to a fresh file under the temp directory,
+  `agent-qa-browserstack-local-<pid>-<random>.log`, readable only by you. Nothing is written to
+  the project. When the tunnel cannot start, the refusal has kind `unreachable` at path
+  `options.local`, or `options.localBinary` when that is set, and names that log.
+- Before it starts the tunnel, the plugin runs the binary once with `--version` to check that
+  this machine can run it. A binary this machine cannot run refuses the session the same way,
+  with kind `unreachable` at the same path, naming the binary, the cause and the fix. The tunnel
+  never ran, so the line names no log and no log file is created. The fix follows the cause:
+  - A Mac binary built for another CPU (`EBADARCH`): install Rosetta
+    (`softwareupdate --install-rosetta --agree-to-license`) or set `localBinary` to a binary
+    built for this Mac. `browserstack-local` downloads BrowserStack's Intel build on every Mac,
+    which an Apple Silicon Mac runs only under Rosetta.
+  - A path that does not exist (`ENOENT`): set `localBinary` to the path of a BrowserStackLocal
+    binary.
+  - A file that is not executable (`EACCES`): make it executable, or set `localBinary` to one that
+    is.
+  - Any other failure: set `localBinary` to a binary this machine can run.
+- The tunnel runs as a daemon outside the plugin's process group, so the plugin stops it itself:
+  on `shutdown`, when agent-qa closes the plugin's stdin and on `SIGTERM`. A tunnel still starting
+  then is aborted: the plugin kills the launch and runs the binary's `--daemon stop` for the
+  tunnel's identifier, and stops the tunnel too if it connects meanwhile.
+- The wrapper's own console output goes to the plugin's stderr, never to the protocol stream.
+
+BrowserStack's tunnel binary takes the access key as `--key` on its command line. That is
+BrowserStack's design, and it means other users of the same machine can read the key with `ps`
+while the tunnel runs.
+
+## License
+
+FSL-1.1-ALv2. See `LICENSE.md` and `NOTICE.md` in the package.

package/dist/main.js

@@ -0,0 +1,7 @@
+import { n as plugin_default } from "./plugin-fBvi25yB.js";
+import { runPlugin } from "@vostride/agent-qa-plugin-kit";
+// src/main.ts
+runPlugin(plugin_default);
+export {};
+
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","names":["plugin"],"sources":["../src/main.ts"],"sourcesContent":["import { runPlugin } from '@vostride/agent-qa-plugin-kit'\nimport plugin from './plugin.js'\n\nrunPlugin(plugin)\n"],"mappings":";;;AAGA,UAAUA,cAAM"}

package/dist/options.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string",
+      "credential": true,
+      "description": "The BrowserStack username"
+    },
+    "accessKey": {
+      "type": "string",
+      "credential": true,
+      "description": "The BrowserStack access key"
+    },
+    "apiUrl": {
+      "default": "https://api.browserstack.com",
+      "description": "BrowserStack's Automate API, https:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    },
+    "appApiUrl": {
+      "default": "https://api-cloud.browserstack.com",
+      "description": "BrowserStack's App Automate API, https:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    },
+    "hubUrl": {
+      "default": "https://hub.browserstack.com/wd/hub",
+      "description": "BrowserStack's Appium hub, https:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    },
+    "playwrightUrl": {
+      "default": "wss://cdp.browserstack.com/playwright",
+      "description": "BrowserStack's Playwright endpoint, wss:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    },
+    "local": {
+      "default": false,
+      "description": "Start a BrowserStack Local tunnel for this run, named by localIdentifier or a fresh one",
+      "type": "boolean"
+    },
+    "localIdentifier": {
+      "description": "The identifier of a BrowserStack Local tunnel; without local, a tunnel already running",
+      "type": "string",
+      "minLength": 1
+    },
+    "localBinary": {
+      "description": "The BrowserStackLocal binary to run instead of the one the wrapper downloads",
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "username",
+    "accessKey"
+  ],
+  "additionalProperties": false
+}