Add vitest-provider-browserstack documentation

chialab · Mar 6, 2024 · 1a248c2 · 1a248c2
1 parent ff2e84e
commit 1a248c2
Show file tree

Hide file tree

Showing 4 changed files with 161 additions and 5 deletions.
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -101,6 +101,10 @@ export default defineConfig({
                         text: 'postcss-url-rebase',
                         link: '/guide/postcss-url-rebase',
                     },
+                    {
+                        text: 'vitest-provider-browserstack',
+                        link: '/guide/vitest-provider-browserstack',
+                    },
                     // {
                     //     text: 'Write a plugin',
                     //     link: '/guide/write-a-plugin',

diff --git a/docs/guide/vitest-provider-browserstack.md b/docs/guide/vitest-provider-browserstack.md
@@ -0,0 +1,88 @@
+# Browserstack provider for Vitest
+
+A browser provider for [Vitest](https://vitest.dev/) that runs tests on [Browserstack](https://www.browserstack.com/).
+
+### Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/vitest-provider-browserstack
+```
+
+```sh[yarn]
+yarn add -D @chialab/vitest-provider-browserstack
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/vitest-provider-browserstack
+```
+
+:::
+
+### Requirements
+
+In order to use this provider, you need to have a Browserstack account and a valid access key.
+
+### Usage
+
+Use this module as provider for Vitest browser runner:
+
+```ts
+/// <reference types="@chialab/vitest-provider-browserstack" />
+
+export default {
+    test: {
+        browser: {
+            name: 'browserstack:chrome-latest',
+            // Use the browserstack provider.
+            provider: '@chialab/vitest-provider-browserstack',
+            // We need to expose the server to the network in order to let Browserstack access it.
+            api: {
+                host: '0.0.0.0',
+                port: 5176,
+            },
+            // Hijack ESM imports is unstable on older browsers.
+            slowHijackESM: false,
+        },
+    },
+    browserstack: {
+        options: {
+            user: 'YOUR_BROWSERSTACK_USERNAME',
+            key: 'YOUR_BROWSERSTACK_ACCESS_KEY',
+        },
+        capabilities: {
+            'chrome-latest': {
+                'browserName': 'Chrome',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+            'firefox-latest': {
+                'browserName': 'Firefox',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+            'safari-latest': {
+                'browserName': 'Safari',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+            'edge-latest': {
+                'browserName': 'MicrosoftEdge',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+        },
+    },
+};
+```
+
+### Options
+
+`user` and `key` options can be omitted if you have a `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` environment variables set.
+
+Read more about the capabilities configuration at [Browserstack documentation](https://www.browserstack.com/docs/automate/capabilities) and Webdriverio [capabilities](https://webdriver.io/docs/capabilities/).
diff --git a/packages/vitest-provider-browserstack/README.md b/packages/vitest-provider-browserstack/README.md
@@ -1,5 +1,5 @@
 <p align="center">
-    <strong>vitest-provider-browserstack</strong> • A BrowserStack provider for vitest browser runner.
+    <strong>Browserstack provider for Vitest</strong> • A BrowserStack provider for Vitest browser runner.
 </p>
 
 <p align="center">
@@ -18,13 +18,73 @@ npm i @chialab/vitest-provider-browserstack -D
 yarn add @chialab/vitest-provider-browserstack -D
 ```
 
+## Requirements
+
+In order to use this provider, you need to have a Browserstack account and a valid access key.
+
 ## Usage
 
-```js
-import '@chialab/vitest-provider-browserstack';
+Use this module as provider for Vitest browser runner:
+
+```ts
+/// <reference types="@chialab/vitest-provider-browserstack" />
 
+export default {
+    test: {
+        browser: {
+            name: 'browserstack:chrome-latest',
+            // Use the browserstack provider.
+            provider: '@chialab/vitest-provider-browserstack',
+            // We need to expose the server to the network in order to let Browserstack access it.
+            api: {
+                host: '0.0.0.0',
+                port: 5176,
+            },
+            // Hijack ESM imports is unstable on older browsers.
+            slowHijackESM: false,
+        },
+    },
+    browserstack: {
+        options: {
+            user: 'YOUR_BROWSERSTACK_USERNAME',
+            key: 'YOUR_BROWSERSTACK_ACCESS_KEY',
+        },
+        capabilities: {
+            'chrome-latest': {
+                'browserName': 'Chrome',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+            'firefox-latest': {
+                'browserName': 'Firefox',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+            'safari-latest': {
+                'browserName': 'Safari',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+            'edge-latest': {
+                'browserName': 'MicrosoftEdge',
+                'bstack:options': {
+                    browserVersion: 'latest',
+                },
+            },
+        },
+    },
+};
 ```
 
+## Options
+
+`user` and `key` options can be omitted if you have a `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` environment variables set.
+
+Read more about the capabilities configuration at [Browserstack documentation](https://www.browserstack.com/docs/automate/capabilities) and Webdriverio [capabilities](https://webdriver.io/docs/capabilities/).
+
 ---
 
 ## License

diff --git a/packages/vitest-provider-browserstack/package.json b/packages/vitest-provider-browserstack/package.json
@@ -2,7 +2,7 @@
   "name": "@chialab/vitest-provider-browserstack",
   "type": "module",
   "version": "0.18.0",
-  "description": "A BrowserStack provider for vitest browser runner.",
+  "description": "A BrowserStack provider for Vitest browser runner.",
   "main": "lib/index.js",
   "typings": "./types/index.d.ts",
   "author": "Chialab <[email protected]> (https://www.chialab.it)",
@@ -12,7 +12,11 @@
     "url": "https://github.com/chialab/rna",
     "directory": "packages/vitest-provider-browserstack"
   },
-  "keywords": [],
+  "keywords": [
+    "vitest",
+    "browserstack",
+    "webdriver"
+  ],
   "files": [
     "lib",
     "types",