chore: publish

- appium@2.0.0-beta.66
 - @appium/doctor@2.0.14
 - @appium/docutils@0.3.9
 - @appium/strongbox@0.3.0

.github/workflows/build.yml

@@ -78,7 +78,3 @@ jobs:
           install-command: npm ci
       - name: ESLint
         run: npm run lint:ci
-      - name: Validate Renovate Config
-        uses: rinchsan/renovate-config-validator@1ea1e8514f6a33fdd71c40b0a5fa3512b9e7b936 # tag=v0
-        with:
-          pattern: '{.renovaterc.json,renovate/default.json}'

.github/workflows/docs.yml

@@ -1,7 +1,21 @@
 name: Build Docs
 
 on:
-  pull_request_target:
+  pull_request:
+    paths:
+      - '**/typedoc.json'
+      - '**/tsconfig*.json'
+      - '**/package*.json'
+      - '**/*mkdocs*.ya?ml'
+      - 'packages/docutils/requirements.txt'
+      - 'packages/*/README.md'
+      - 'packages/*/docs/**'
+      - 'packages/*/**/*.ts'
+      - 'packages/*/**/*.js'
+      - '.github/workflows/docs.yml' # this file
+      - '!**/test/**'
+      - '!**/sample-code/**'
+  push:
     paths:
       - '**/typedoc.json'
       - '**/tsconfig*.json'
@@ -15,10 +29,6 @@ on:
       - '.github/workflows/docs.yml' # this file
       - '!**/test/**'
       - '!**/sample-code/**'
-
-    branches: [master]
-
-concurrency: preview-${{ github.ref }}
 
 jobs:
   docs:
@@ -39,8 +49,3 @@ jobs:
           git config --local user.name "github-actions[bot]"
       - name: Build Docs
         run: npm run docs:preview
-      - name: Deploy Preview
-        uses: rossjrw/pr-preview-action@2a652922e9b9c53e7e5ea62fa38da744de09043c # v1
-        with:
-          source-dir: ./packages/appium/docs/site
-          custom-url: 'appium.github.io/appium'

.github/workflows/renovate.yml

@@ -0,0 +1,26 @@
+name: Validate Renovate Configs
+on:
+  push:
+    paths:
+      - '.github/workflows/renovate.yml' # this file
+      - '.renovaterc.json'
+      - 'renovate/default.json'
+  pull_request:
+    paths:
+      - '.github/workflows/renovate.yml' # this file
+      - '.renovaterc.json'
+      - 'renovate/default.json'
+
+permissions:
+  contents: read
+
+jobs:
+  renovate:
+    name: Check Renovate Configs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3
+      - name: Validate Renovate Config
+        uses: rinchsan/renovate-config-validator@1ea1e8514f6a33fdd71c40b0a5fa3512b9e7b936 # tag=v0
+        with:
+          pattern: '{.renovaterc.json,renovate/default.json}'

.wallaby.js

@@ -17,9 +17,12 @@ module.exports = (wallaby) => {
     },
     files: [
       './packages/*/build/**/*',
-      './packages/*/lib/**/*.{js,ts}',
-      './packages/*/test/**/*helper*.{js,ts}',
-      './packages/*/test/**/*mock*.{js,ts}',
+      './packages/*/lib/**/*.js',
+      './packages/*/lib/**/*.ts',
+      './packages/*/test/**/*helper*.js',
+      './packages/*/test/**/*helper*.ts',
+      './packages/*/test/**/*mock*.js',
+      './packages/*/test/**/*mock*.ts',
       './packages/*/package.json',
       './packages/*/tsconfig*.json',
       './packages/*/test/**/fixture?(s)/**/*',
@@ -43,12 +46,21 @@ module.exports = (wallaby) => {
         instrument: false,
         pattern: './packages/typedoc-plugin-appium/lib/theme/resources/**',
       },
+      {
+        instrument: false,
+        pattern: './packages/*/test/**/__snapshots__/**/*',
+      },
       '!./packages/*/test/**/*-specs.js',
-      '!./packages/*/test/**/*.e2e.spec.{js,ts}',
+      '!./packages/*/test/**/*.e2e.spec.js',
+      '!./packages/*/test/**/*.e2e.spec.ts',
       '!**/local_appium_home/**',
     ],
     testFramework: 'mocha',
-    tests: ['./packages/*/test/unit/**/*.spec.{js,ts}', '!**/local_appium_home/**'],
+    tests: [
+      './packages/*/test/unit/**/*.spec.js',
+      './packages/*/test/unit/**/*.spec.ts',
+      '!**/local_appium_home/**',
+    ],
     workers: {
       // restart: true,
     },

README.md

@@ -13,16 +13,16 @@ Appium is an open-source, cross-platform test automation tool for native,
 hybrid, mobile web and desktop apps. Initially created to automate iOS and Android mobile
 applications Appium has grown to a full-featured platform that provides [WebDriver](https://www.w3.org/TR/webdriver/)-based automation possibilities for the whole set of different mobile and desktop platforms.
 See the full list of
-[officially-supported](https://appium.github.io/appium/docs/en/latest/ecosystem/#drivers) and
-[third-party](https://appium.github.io/appium/docs/en/latest/ecosystem/#other-drivers) drivers for more details.
+[officially-supported](https://appium.io/docs/en/latest/ecosystem/#drivers) and
+[third-party](https://appium.io/docs/en/latest/ecosystem/#other-drivers) drivers for more details.
 
 :bangbang: Major documentation revision in progress
 
-:bangbang: Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. All recent versions of officially supported platform drivers are not compatible to Appium 1.x anymore, and require Appium 2 to run. [Please read the migration guide from 1.x to 2.0](https://appium.github.io/appium/docs/en/latest/guides/migrating-1-to-2/) to manage the Appium server.
+:bangbang: Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. All recent versions of officially supported platform drivers are not compatible to Appium 1.x anymore, and require Appium 2 to run. [Please read the migration guide from 1.x to 2.0](https://appium.io/docs/en/latest/guides/migrating-1-to-2/) to manage the Appium server.
 
 Appium is in the final stages of a major revision (to version 2.0). As such, the documentation
 found around the web may not be correct. The current Appium 2.0 documentation is very much in
-progress. Currently, it can be found [here](https://appium.github.io/appium/docs/en/latest/).
+progress. Currently, it can be found [here](https://appium.io/docs/en/latest/).
 
 ### Requirements
 
@@ -71,8 +71,8 @@ appium driver uninstall xcuitest
 ```
 
 You can find a full list of
-[officially-supported](https://appium.github.io/appium/docs/en/latest/ecosystem/#drivers) and
-[third-party](https://appium.github.io/appium/docs/en/latest/ecosystem/#other-drivers) drivers at
+[officially-supported](https://appium.io/docs/en/latest/ecosystem/#drivers) and
+[third-party](https://appium.io/docs/en/latest/ecosystem/#other-drivers) drivers at
 the current Appium 2.0 documentation.
 
 ### Plugins
@@ -104,8 +104,8 @@ appium server --use-plugins=device-farm,images
 ```
 
 You can find a full list of
-[officially-supported](https://appium.github.io/appium/docs/en/latest/ecosystem/#plugins) and
-[third-party](https://appium.github.io/appium/docs/en/latest/ecosystem/#other-plugins) plugins at
+[officially-supported](https://appium.io/docs/en/latest/ecosystem/#plugins) and
+[third-party](https://appium.io/docs/en/latest/ecosystem/#other-plugins) plugins at
 the current Appium 2.0 documentation.
 
 
@@ -169,11 +169,11 @@ Java/Kotlin. Appium opens up the possibility of true cross-platform native app
 automation, for mobile and beyond. Finally!
 
 If you're new to Appium or want a more comprehensive description of what this is all
-about, please read our [Intro to Appium](https://appium.github.io/appium/docs/en/latest/intro/).
+about, please read our [Intro to Appium](https://appium.io/docs/en/latest/intro/).
 
 ### Quickstart
 
-Check out our [Quickstart](https://appium.github.io/appium/docs/en/latest/quickstart/) guide
+Check out our [Quickstart](https://appium.io/docs/en/latest/quickstart/) guide
 to get going with Appium.
 
 There is also a sample code that contains [many examples of tests in a variety
@@ -181,7 +181,7 @@ of different languages](https://github.com/appium/appium/tree/1.x/sample-code)!
 
 ### Documentation
 
-For prettily-rendered docs, please visit [Appium Documentation](https://appium.github.io/appium).
+For prettily-rendered docs, please visit [Appium Documentation](https://appium.io).
 You can always find the full list of Appium doc pages at [Appium's GitHub
 Repo](https://github.com/appium/appium/tree/master/packages/appium/docs) as well.
 
@@ -196,7 +196,7 @@ Interested in where Appium is heading in the future? Check out the [Roadmap](ROA
 
 ### Project History, Credits & Inspiration
 
-* [History](https://appium.github.io/appium/docs/en/latest/intro/history/)
+* [History](https://appium.io/docs/en/latest/intro/history/)
 
 ### User Forums
 

package.json

@@ -85,8 +85,8 @@
   },
   "devDependencies": {
     "@colors/colors": "1.5.0",
-    "@commitlint/cli": "17.5.1",
-    "@commitlint/config-conventional": "17.4.4",
+    "@commitlint/cli": "17.6.1",
+    "@commitlint/config-conventional": "17.6.1",
     "@tsconfig/node14": "1.0.3",
     "@types/chai": "4.3.4",
     "@types/chai-as-promised": "7.1.5",
@@ -94,7 +94,7 @@
     "@types/mocha": "10.0.1",
     "@types/node": "18.15.11",
     "@types/semver": "7.3.13",
-    "@types/sinon": "10.0.13",
+    "@types/sinon": "10.0.14",
     "@types/sinon-chai": "3.2.9",
     "@types/teen_process": "2.0.0",
     "@types/ws": "8.5.4",
@@ -123,10 +123,11 @@
     "lerna": "6.6.1",
     "lint-staged": "13.2.1",
     "log-symbols": "4.1.0",
-    "midnight-smoker": "2.0.1",
+    "midnight-smoker": "2.0.3",
     "mjpeg-consumer": "2.0.0",
     "mjpeg-server": "0.3.1",
     "mocha": "10.2.0",
+    "mocha-chai-jest-snapshot": "1.1.4",
     "npm-run-all": "4.1.5",
     "prettier": "2.8.7",
     "rewiremock": "3.14.5",

packages/appium/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.0.0-beta.66](https://github.com/appium/appium/compare/appium@2.0.0-beta.65...appium@2.0.0-beta.66) (2023-04-20)
+
+**Note:** Version bump only for package appium
+
+
+
+
+
+## [2.0.0-beta.65](https://github.com/appium/appium/compare/appium@2.0.0-beta.64...appium@2.0.0-beta.65) (2023-04-18)
+
+**Note:** Version bump only for package appium
+
+
+
+
+
 ## [2.0.0-beta.64](https://github.com/appium/appium/compare/appium@2.0.0-beta.63...appium@2.0.0-beta.64) (2023-04-14)
 
 

packages/appium/README.md

@@ -13,16 +13,16 @@ Appium is an open-source, cross-platform test automation tool for native,
 hybrid, mobile web and desktop apps. Initially created to automate iOS and Android mobile
 applications Appium has grown to a full-featured platform that provides [WebDriver](https://www.w3.org/TR/webdriver/)-based automation possibilities for the whole set of different mobile and desktop platforms.
 See the full list of
-[officially-supported](https://appium.github.io/appium/docs/en/latest/ecosystem/#drivers) and
-[third-party](https://appium.github.io/appium/docs/en/latest/ecosystem/#other-drivers) drivers for more details.
+[officially-supported](https://appium.io/docs/en/latest/ecosystem/#drivers) and
+[third-party](https://appium.io/docs/en/latest/ecosystem/#other-drivers) drivers for more details.
 
 :bangbang: Major documentation revision in progress
 
-:bangbang: Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. All recent versions of officially supported platform drivers are not compatible to Appium 1.x anymore, and require Appium 2 to run. [Please read the migration guide from 1.x to 2.0](https://appium.github.io/appium/docs/en/latest/guides/migrating-1-to-2/) to manage the Appium server.
+:bangbang: Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. All recent versions of officially supported platform drivers are not compatible to Appium 1.x anymore, and require Appium 2 to run. [Please read the migration guide from 1.x to 2.0](https://appium.io/docs/en/latest/guides/migrating-1-to-2/) to manage the Appium server.
 
 Appium is in the final stages of a major revision (to version 2.0). As such, the documentation
 found around the web may not be correct. The current Appium 2.0 documentation is very much in
-progress. Currently, it can be found [here](https://appium.github.io/appium/docs/en/latest/).
+progress. Currently, it can be found [here](https://appium.io/docs/en/latest/).
 
 ### Requirements
 
@@ -71,8 +71,8 @@ appium driver uninstall xcuitest
 ```
 
 You can find a full list of
-[officially-supported](https://appium.github.io/appium/docs/en/latest/ecosystem/#drivers) and
-[third-party](https://appium.github.io/appium/docs/en/latest/ecosystem/#other-drivers) drivers at
+[officially-supported](https://appium.io/docs/en/latest/ecosystem/#drivers) and
+[third-party](https://appium.io/docs/en/latest/ecosystem/#other-drivers) drivers at
 the current Appium 2.0 documentation.
 
 ### Plugins
@@ -104,8 +104,8 @@ appium server --use-plugins=device-farm,images
 ```
 
 You can find a full list of
-[officially-supported](https://appium.github.io/appium/docs/en/latest/ecosystem/#plugins) and
-[third-party](https://appium.github.io/appium/docs/en/latest/ecosystem/#other-plugins) plugins at
+[officially-supported](https://appium.io/docs/en/latest/ecosystem/#plugins) and
+[third-party](https://appium.io/docs/en/latest/ecosystem/#other-plugins) plugins at
 the current Appium 2.0 documentation.
 
 
@@ -169,11 +169,11 @@ Java/Kotlin. Appium opens up the possibility of true cross-platform native app
 automation, for mobile and beyond. Finally!
 
 If you're new to Appium or want a more comprehensive description of what this is all
-about, please read our [Intro to Appium](https://appium.github.io/appium/docs/en/latest/intro/).
+about, please read our [Intro to Appium](https://appium.io/docs/en/latest/intro/).
 
 ### Quickstart
 
-Check out our [Quickstart](https://appium.github.io/appium/docs/en/latest/quickstart/) guide
+Check out our [Quickstart](https://appium.io/docs/en/latest/quickstart/) guide
 to get going with Appium.
 
 There is also a sample code that contains [many examples of tests in a variety
@@ -181,7 +181,7 @@ of different languages](https://github.com/appium/appium/tree/1.x/sample-code)!
 
 ### Documentation
 
-For prettily-rendered docs, please visit [Appium Documentation](https://appium.github.io/appium).
+For prettily-rendered docs, please visit [Appium Documentation](https://appium.io).
 You can always find the full list of Appium doc pages at [Appium's GitHub
 Repo](https://github.com/appium/appium/tree/master/packages/appium/docs) as well.
 
@@ -196,7 +196,7 @@ Interested in where Appium is heading in the future? Check out the [Roadmap](ROA
 
 ### Project History, Credits & Inspiration
 
-* [History](https://appium.github.io/appium/docs/en/latest/intro/history/)
+* [History](https://appium.io/docs/en/latest/intro/history/)
 
 ### User Forums
 

packages/appium/docs/base-mkdocs.yml

@@ -22,11 +22,11 @@ extra:
       link: https://twitter.com/AppiumDevs
   alternate:
     - name: English
-      link: /appium/docs/en/ 
+      link: /docs/en/ 
       lang: en
     - name: 日本
-      link: /appium/docs/ja/
+      link: /docs/ja/
       lang: ja
     - name: 中文简体
-      link: /appium/docs/zh/
+      link: /docs/zh/
       lang: zh

packages/appium/docs/en/ecosystem/index.md

@@ -64,7 +64,7 @@ the Appium client depends on) since that is what you will use as your primary in
 |[Appium Java client](https://github.com/appium/java-client)|Java|Appium Team|
 |[Appium Python client](https://github.com/appium/python-client)|Python|Appium Team|
 |[Appium Ruby Core client](https://github.com/appium/ruby_lib_core) (Recommended)<br>[Appium Ruby client](https://github.com/appium/ruby_lib)|Ruby|Appium Team|
-|[WebDriverIO](https://webdriver.io)|Node.js|Community|
+|[WebDriverIO](https://webdriver.io)<br>[Nightwatch](https://nightwatchjs.org/)|Node.js|Community|
 |[Appium .NET client](https://github.com/appium/dotnet-client)|C#|Appium Team*|
 |[RobotFramework](https://github.com/serhatbolsu/robotframework-appiumlibrary)|DSL|Community|
 

packages/appium/docs/mkdocs-en.yml

@@ -1,5 +1,5 @@
 INHERIT: ./base-mkdocs.yml
-site_url: https://appium.github.io/appium/docs/en
+site_url: https://appium.io/docs/en
 edit_uri: edit/master/packages/appium/docs/en
 site_description: The Appium automation project documentation
 docs_dir: en

packages/appium/docs/mkdocs-ja.yml

@@ -1,5 +1,5 @@
 INHERIT: ./base-mkdocs.yml
-site_url: https://appium.github.io/appium/docs/ja
+site_url: https://appium.io/docs/ja
 edit_uri: edit/master/packages/appium/docs/ja
 site_description: The Appium automation project documentation
 docs_dir: ja

packages/appium/docs/mkdocs-zh.yml

@@ -1,5 +1,5 @@
 INHERIT: ./base-mkdocs.yml
-site_url: https://appium.github.io/appium/docs/zh
+site_url: https://appium.io/docs/zh
 edit_uri: edit/master/packages/appium/docs/zh
 site_description: The Appium automation project documentation
 docs_dir: zh

packages/appium/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.64",
+  "version": "2.0.0-beta.66",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -62,7 +62,7 @@
   "dependencies": {
     "@appium/base-driver": "^9.3.7",
     "@appium/base-plugin": "^2.2.7",
-    "@appium/docutils": "^0.3.7",
+    "@appium/docutils": "^0.3.9",
     "@appium/schema": "^0.2.6",
     "@appium/support": "^3.1.11",
     "@appium/types": "^0.11.0",

packages/base-plugin/README.md

@@ -1,3 +1,3 @@
 # Appium Base Plugin
 
-The base class used to create Appium plugins. This plugin should not be installed directly as it does nothing. Instead, you extend this plugin when creating your *own* Appium plugins. Check out the [Building Plugins](https://appium.github.io/appium/docs/en/latest/ecosystem/build-plugins/) to learn how to make use of this base class to develop Appium plugins.
+The base class used to create Appium plugins. This plugin should not be installed directly as it does nothing. Instead, you extend this plugin when creating your *own* Appium plugins. Check out the [Building Plugins](https://appium.io/docs/en/latest/ecosystem/build-plugins/) to learn how to make use of this base class to develop Appium plugins.

packages/doctor/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.0.14](https://github.com/appium/appium/compare/@appium/doctor@2.0.13...@appium/doctor@2.0.14) (2023-04-20)
+
+
+### Bug Fixes
+
+* **doctor:** update dependency appium-adb to v9.11.1 ([45cd434](https://github.com/appium/appium/commit/45cd43488ce3e7a3c32864912d8fb104934f90d8))
+
+
+
 ## [2.0.13](https://github.com/appium/appium/compare/@appium/doctor@2.0.12...@appium/doctor@2.0.13) (2023-04-14)
 
 **Note:** Version bump only for package @appium/doctor

packages/doctor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/doctor",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "description": "Test environment for fitness to run Appium",
   "keywords": [
     "automation",
@@ -48,7 +48,7 @@
     "@colors/colors": "1.5.0",
     "@types/bluebird": "3.5.38",
     "@types/teen_process": "2.0.0",
-    "appium-adb": "9.11.0",
+    "appium-adb": "9.11.1",
     "bluebird": "3.7.2",
     "inquirer": "8.2.5",
     "lodash": "4.17.21",

packages/docutils/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.3.9](https://github.com/appium/appium/compare/@appium/docutils@0.3.8...@appium/docutils@0.3.9) (2023-04-20)
+
+
+### Bug Fixes
+
+* **docutils:** do not bail when no site_dir found ([c85b89e](https://github.com/appium/appium/commit/c85b89ecbe28f2fd720d73fca7cd11f283eb9a0a))
+
+
+
+## [0.3.8](https://github.com/appium/appium/compare/@appium/docutils@0.3.7...@appium/docutils@0.3.8) (2023-04-18)
+
+**Note:** Version bump only for package @appium/docutils
+
+
+
+
+
 ## [0.3.7](https://github.com/appium/appium/compare/@appium/docutils@0.3.6...@appium/docutils@0.3.7) (2023-04-14)
 
 

packages/docutils/lib/builder/site.ts

@@ -7,7 +7,7 @@
 
 import path from 'node:path';
 import {exec, TeenProcessExecOptions} from 'teen_process';
-import {NAME_BIN, NAME_MKDOCS_YML, NAME_THEME} from '../constants';
+import {DEFAULT_SITE_DIR, NAME_BIN, NAME_MKDOCS_YML, NAME_THEME} from '../constants';
 import {DocutilsError} from '../error';
 import {findMkDocsYml, readMkDocsYml, whichMkDocs} from '../fs';
 import {getLogger} from '../logger';
@@ -80,17 +80,26 @@ export async function buildSite({
     // unsure about how SIGHUP is handled here
     await doServe(mkdocsArgs, serveOpts);
   } else {
-    log.info('Building site into %s (%dms)');
+    log.info('Building site...');
     await doBuild(mkdocsArgs, execOpts);
     let relSiteDir;
     if (siteDir) {
       relSiteDir = relative(cwd, siteDir);
     } else {
       ({site_dir: siteDir} = await readMkDocsYml(mkDocsYmlPath));
-      log.debug('Found site_dir %s', siteDir);
-      relSiteDir = relative(path.dirname(mkDocsYmlPath), siteDir!);
+      if (siteDir) {
+        log.debug('Found site_dir %s', siteDir);
+        relSiteDir = relative(path.dirname(mkDocsYmlPath), siteDir);
+      } else {
+        log.warn(
+          'No site_dir specified in args or %s; using default site_dir: %s',
+          NAME_MKDOCS_YML,
+          DEFAULT_SITE_DIR
+        );
+        relSiteDir = relative(cwd, DEFAULT_SITE_DIR);
+      }
     }
-    log.success('Finnished building site into %s (%dms)', relSiteDir, stop());
+    log.success('Finished building site into %s (%dms)', relSiteDir, stop());
   }
 }
 

packages/docutils/lib/constants.ts

@@ -153,3 +153,8 @@ export const LogLevelMap = {
  * Default site nav header text
  */
 export const DEFAULT_NAV_HEADER = 'Reference';
+
+/**
+ * If the user does not specify a site directory _and_ the `mkdocs.yml` doesn't either, use this dir.
+ */
+export const DEFAULT_SITE_DIR = 'site';

packages/docutils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@appium/support": "^3.1.11",
     "@appium/tsconfig": "^0.3.0",
-    "@appium/typedoc-plugin-appium": "^0.6.2",
+    "@appium/typedoc-plugin-appium": "^0.6.3",
     "@sliphua/lilconfig-ts-loader": "3.2.2",
     "chalk": "4.1.2",
     "consola": "2.15.3",

packages/strongbox/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.3.0](https://github.com/appium/appium/compare/@appium/strongbox@0.2.0...@appium/strongbox@0.3.0) (2023-04-20)
+
+
+### ⚠ BREAKING CHANGES
+
+* **strongbox:** The signature for an `ItemCtor` has changed. The second parameter is now a type extending `Strongbox` instead of a `container` string.  This allows for deeper integration between a custom `Item` implementation and a custom `Strongbox` implementation. Further, a custom `container` now must be an absolute path after it's been slugified.
+
+- The `Strongbox.clearAll()` method now accepts a `force` param which, if `true`, will rimraf the entire container.
+- Added two methods to the `Strongbox` class which can be overridden to accept custom options, apply defaults to those options, then validate and/or transform them.
+- Added nearly-complete unit test coverage and added E2E coverage of the `BaseItem` implementation.
+
+### Features
+
+* **strongbox:** allow rimraf of entire container ([93bddb4](https://github.com/appium/appium/commit/93bddb4c73ab16fffda09909786074b9e5f2b7e5))
+
+
+
 # 0.2.0 (2023-04-10)
 
 

packages/strongbox/lib/base-item.ts

@@ -1,6 +1,6 @@
 import {mkdir, readFile, unlink, writeFile} from 'node:fs/promises';
 import path from 'node:path';
-import type {Item, ItemEncoding, Value} from '.';
+import type {Item, ItemEncoding, Strongbox, Value} from '.';
 import {slugify} from './util';
 
 /**
@@ -9,17 +9,20 @@ import {slugify} from './util';
  * @remarks This class is not intended to be instantiated directly
  * @typeParam T - Type of data stored in the `Item`
  */
-export class BaseItem<T extends Value> implements Item<T> {
+export class BaseItem<T extends Value, U extends Strongbox = Strongbox> implements Item<T> {
   /**
    * {@inheritdoc Item.value}
    */
   protected _value?: T | undefined;
 
+  /**
+   * Parent Strongbox instance
+   */
+  public readonly container: string;
   /**
    * Unique slugified identifier
    */
   public readonly id: string;
-
   /**
    * {@inheritdoc Item.value}
    */
@@ -28,16 +31,16 @@ export class BaseItem<T extends Value> implements Item<T> {
   /**
    * Slugifies the name
    * @param name Name of instance
-   * @param container Slugified name of container
+   * @param parent Parent Strongbox
    * @param encoding Defaults to `utf8`
    */
   constructor(
     public readonly name: string,
-    public readonly container: string,
+    parent: U,
     public readonly encoding: ItemEncoding = 'utf8'
   ) {
-    this.id = path.join(container, slugify(name));
-
+    this.container = parent.container;
+    this.id = path.join(this.container, slugify(name));
     Object.defineProperties(this, {
       value: {
         get() {
@@ -52,6 +55,20 @@ export class BaseItem<T extends Value> implements Item<T> {
     });
   }
 
+  /**
+   * {@inheritdoc Item.clear}
+   */
+  public async clear(): Promise<void> {
+    try {
+      await unlink(this.id);
+      this._value = undefined;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw e;
+      }
+    }
+  }
+
   /**
    * {@inheritdoc Item.read}
    */
@@ -78,18 +95,4 @@ export class BaseItem<T extends Value> implements Item<T> {
       this._value = value;
     }
   }
-
-  /**
-   * {@inheritdoc Item.clear}
-   */
-  public async clear(): Promise<void> {
-    try {
-      await unlink(this.id);
-      this._value = undefined;
-    } catch (e) {
-      if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
-        throw e;
-      }
-    }
-  }
 }

packages/strongbox/lib/index.ts

@@ -1,7 +1,8 @@
 import envPaths from 'env-paths';
+import {rm} from 'node:fs/promises';
 import path from 'node:path';
 import {BaseItem} from './base-item';
-import {slugify, slugifyPath} from './util';
+import {slugify} from './util';
 
 /**
  * Valid file encodings.
@@ -34,7 +35,17 @@ export interface Item<T extends Value> {
    * Name of item
    */
   name: string;
+  /**
+   * Last known value (stored in memory)
+   *
+   * @remarks A custom {@linkcode Item} meant to handle very large files should probably not implement this.
+   */
+  value?: T | undefined;
 
+  /**
+   * Deletes the item.
+   */
+  clear(): Promise<void>;
   /**
    * Reads value
    */
@@ -44,18 +55,6 @@ export interface Item<T extends Value> {
    * @param value New value
    */
   write(value: T): Promise<void>;
-
-  /**
-   * Deletes the item.
-   */
-  clear(): Promise<void>;
-
-  /**
-   * Last known value (stored in memory)
-   *
-   * @remarks A custom {@linkcode Item} meant to handle very large files should probably not implement this.
-   */
-  value?: T | undefined;
 }
 
 /**
@@ -87,6 +86,8 @@ function isEncoding(value: any): value is ItemEncoding {
 }
 
 /**
+ * Default container suffix if no explicit container is provided.
+ *
  * @see {@linkcode StrongboxOpts}
  */
 export const DEFAULT_SUFFIX = 'strongbox';
@@ -94,62 +95,58 @@ export const DEFAULT_SUFFIX = 'strongbox';
 /**
  * A constructor function which instantiates a {@linkcode Item}.
  */
-export type ItemCtor<T extends Value> = new (
-  name: string,
-  container: string,
-  encoding?: ItemEncoding
-) => Item<T>;
+export type ItemCtor<
+  T extends Value,
+  U extends StrongboxOpts = StrongboxOpts,
+  V extends Strongbox<U> = Strongbox<U>
+> = new (name: string, parent: V, encoding?: ItemEncoding) => Item<T>;
 
 /**
  * Main entry point for use of this module
  *
  * Manages multiple {@linkcode Item}s.
  */
-export class Strongbox {
+export class Strongbox<Options extends StrongboxOpts = StrongboxOpts> {
   /**
    * Default {@linkcode ItemCtor} to use when creating new {@linkcode Item}s
    */
   protected defaultItemCtor: ItemCtor<any>;
-  /**
-   * Slugified name of this instance; corresponds to the directory name.
-   *
-   * If `dir` is provided, this value is unused.
-   * If `suffix` is provided, then this will be the parent directory of `suffix`.
-   */
-  public readonly id: string;
-
-  /**
-   * Override the directory of this container.
-   *
-   * If this is present, both `suffix` and `containerId` are unused.
-   */
-  public readonly container: string;
-
   /**
    * Store of known {@linkcode Item}s
    * @internal
    */
   protected items: Map<string, WeakRef<Item<any>>>;
 
+  /**
+   * Override the directory of this container.
+   *
+   * If this is present, `suffix` is ignored.
+   */
+  public readonly container: string;
+  /**
+   * Slugified name of this instance; corresponds to the directory name.
+   *
+   * If `dir` is provided, this value is unused.
+   * If `suffix` is provided, then this will be the parent directory of `suffix`.
+   */
+  public readonly id: string;
+  public readonly suffix: string;
+
   /**
    * Slugifies the name & determines the directory
    * @param name Name of instance
    * @param opts Options
    */
-  protected constructor(
-    public readonly name: string,
-    {
-      container,
-      suffix = DEFAULT_SUFFIX,
-      defaultItemCtor: defaultCtor = BaseItem,
-    }: StrongboxOpts = {}
-  ) {
+  protected constructor(public readonly name: string, opts: Partial<Options> = {}) {
     this.id = slugify(name);
-    this.defaultItemCtor = defaultCtor;
+
+    let newOpts = this.setDefaultOptions(opts);
+    newOpts = this.checkOptions(newOpts);
+
+    this.defaultItemCtor = newOpts.defaultItemCtor;
+    this.container = newOpts.container;
+    this.suffix = newOpts.suffix;
     this.items = new Map();
-    this.container = container
-      ? slugifyPath(container)
-      : path.join(envPaths(this.id).data, slugify(suffix));
   }
 
   /**
@@ -158,10 +155,26 @@ export class Strongbox {
    * @param opts Options
    * @returns New instance
    */
-  public static create(name: string, opts?: StrongboxOpts) {
+  public static create<Options extends StrongboxOpts = StrongboxOpts>(
+    name: string,
+    opts?: Partial<Options>
+  ) {
     return new Strongbox(name, opts);
   }
 
+  /**
+   * Clears _all_ items.
+   *
+   * @param force - If `true`, will rimraf the container. Otherwise, will only delete individual items.
+   */
+  public async clearAll(force = false): Promise<void> {
+    const items = [...this.items.values()].map((ref) => ref.deref()).filter(Boolean) as Item<any>[];
+    await Promise.all(items.map((item) => item.clear()));
+    if (force) {
+      await rm(this.container, {recursive: true});
+    }
+  }
+
   /**
    * Create a new {@linkcode Item}.
    *
@@ -188,7 +201,7 @@ export class Strongbox {
     }
     const item = new (encodingOrCtor ?? (this.defaultItemCtor as ItemCtor<T>))(
       name,
-      this.container,
+      this,
       encoding
     );
     if (this.items.has(item.id)) {
@@ -250,11 +263,40 @@ export class Strongbox {
   }
 
   /**
-   * Clears _all_ items, as well as the container.
+   * Performs runtime validation (and optionally transformation) of options.
+   *
+   * Should not set defaults.
+   *
+   * The default implementation slugifies any custom container name and suffix.
+   *
+   * Subclasses should override this method to perform additional validation as needed.
+   * @param opts - Options
    */
-  public async clearAll(): Promise<void> {
-    const items = [...this.items.values()].map((ref) => ref.deref()).filter(Boolean) as Item<any>[];
-    await Promise.all(items.map((item) => item.clear()));
+  protected checkOptions(opts: Options): Options {
+    opts.suffix = slugify(opts.suffix);
+    if (opts.container) {
+      opts.container = opts.container.split(path.sep).map(slugify).join(path.sep);
+      if (!path.isAbsolute(opts.container)) {
+        throw new TypeError(`container slug ${opts.container} must be an absolute path`);
+      }
+    } else {
+      opts.container = path.join(envPaths(this.id).data, opts.suffix);
+    }
+    return opts;
+  }
+
+  /**
+   * Sets defaults for options.
+   *
+   * Subclasses should override as necessary.
+   * @param opts Options
+   * @returns Options with defaults applied
+   */
+  protected setDefaultOptions(opts: Partial<Options> = {}): Options {
+    const newOpts = opts as Options;
+    newOpts.suffix = opts.suffix ?? DEFAULT_SUFFIX;
+    newOpts.defaultItemCtor = opts.defaultItemCtor ?? BaseItem;
+    return newOpts;
   }
 }
 
@@ -262,24 +304,26 @@ export class Strongbox {
  * Options for {@linkcode strongbox}
  */
 export interface StrongboxOpts {
+  /**
+   * Override default container, which is chosen according to environment.
+   *
+   * This must be a writable path.
+   */
+  container: string;
   /**
    * Default {@linkcode Item} constructor.
    *
    * Unless a constructor is specified when calling {@linkcode Strongbox.createItem} or {@linkcode Strongbox.createItemWithValue}, this will be used.
    * @defaultValue BaseItem
    */
-  defaultItemCtor?: ItemCtor<any>;
-  /**
-   * Override default container, which is chosen according to environment
-   */
-  container?: string;
+  defaultItemCtor: ItemCtor<any>;
   /**
    * Extra subdir to append to the auto-generated file directory hierarchy.
    *
    * This is ignored if `container` is provided.
    * @defaultValue 'strongbox'
    */
-  suffix?: string;
+  suffix: string;
 }
 
 /**

packages/strongbox/lib/util.ts

@@ -4,7 +4,3 @@ import slug from 'slugify';
 export function slugify(value: string) {
   return slug(value, {lower: true});
 }
-
-export function slugifyPath(filepath: string) {
-  return filepath.split(path.sep).map(slugify).join(path.sep);
-}

packages/strongbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/strongbox",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Persistent storage for Appium extensions",
   "keywords": [
     "automation",
@@ -37,7 +37,8 @@
     "test": "run-p test:unit test:types",
     "test:smoke": "node .",
     "test:unit": "mocha \"test/unit/**/*.spec.ts\"",
-    "test:types": "tsd"
+    "test:types": "tsd",
+    "test:e2e": "mocha -t 20s \"test/e2e/**/*.e2e.spec.ts\""
   },
   "dependencies": {
     "env-paths": "2.2.1",

packages/strongbox/test/e2e/strongbox.e2e.spec.ts

@@ -0,0 +1,72 @@
+import {readFile} from 'node:fs/promises';
+import {Item, Strongbox, strongbox} from '../../lib';
+
+const {expect} = chai;
+
+describe('@appium/strongbox', function () {
+  describe('default behavior', function () {
+    let box: Strongbox;
+
+    beforeEach(function () {
+      box = strongbox('test');
+    });
+
+    afterEach(async function () {
+      await box.clearAll(true);
+    });
+
+    describe('when creating an Item with a value', function () {
+      let item: Item<string>;
+
+      beforeEach(async function () {
+        item = await box.createItemWithValue('test', 'value');
+      });
+
+      it('should write the value to the filesystem', async function () {
+        await expect(readFile(item.id, 'utf8')).to.eventually.equal('value');
+      });
+
+      it('should set the value property', async function () {
+        expect(item.value).to.equal('value');
+      });
+
+      describe('when writing a new value', function () {
+        beforeEach(async function () {
+          await item.write('new value');
+        });
+
+        it('should write the value to the filesystem', async function () {
+          await expect(readFile(item.id, 'utf8')).to.eventually.equal('new value');
+        });
+
+        it('should set the value property', async function () {
+          expect(item.value).to.equal('new value');
+        });
+      });
+
+      describe('when clearing the item', function () {
+        beforeEach(async function () {
+          await item.clear();
+        });
+
+        it('should remove the item from the filesystem', async function () {
+          await expect(readFile(item.id, 'utf8')).to.be.rejectedWith('ENOENT');
+        });
+
+        it('should set the value property to undefined', async function () {
+          expect(item.value).to.be.undefined;
+        });
+
+        describe('when attempting to read it again', function () {
+          it('should resolve w/ undefined', async function () {
+            await expect(item.read()).to.eventually.be.undefined;
+          });
+
+          it('should set the value property to undefined', async function () {
+            expect(item.value).to.be.undefined;
+          });
+        });
+      });
+    });
+  });
+});

packages/strongbox/test/types/strongbox.test-d.ts

@@ -1,7 +1,7 @@
 import {expectAssignable, expectNotAssignable} from 'tsd';
-import {Item, BaseItem, Value} from '../..';
+import {Item, BaseItem, Value, strongbox} from '../..';
 
-expectAssignable<Item<string>>(new BaseItem('foo', 'some-container'));
+expectAssignable<Item<string>>(new BaseItem('foo', strongbox('foo')));
 
 expectNotAssignable<Value>(1);
 expectAssignable<Value>('foo');

packages/strongbox/test/unit/base-item.spec.ts

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import rewiremock from 'rewiremock/node';
+import {createSandbox, SinonSandbox, SinonStubbedMember} from 'sinon';
+import type fs from 'node:fs/promises';
+import {Item, Strongbox} from '../../lib';
+
+const {expect} = chai;
+type MockFs = {
+  [K in keyof typeof fs]: SinonStubbedMember<(typeof fs)[K]>;
+};
+
+describe('Strongbox', function () {
+  let sandbox: SinonSandbox;
+  let MockFs: MockFs = {} as any;
+  const DATA_DIR = '/some/dir';
+  // note to self: looks like this is safe to do before the rewiremock.proxy call
+  let BaseItem: typeof import('../../lib/base-item').BaseItem;
+
+  beforeEach(function () {
+    sandbox = createSandbox();
+    ({BaseItem} = rewiremock.proxy(
+      () => require('../../lib'),
+      (r) => ({
+        // all of these props are async functions
+        'node:fs/promises': r
+          .mockThrough((prop) => {
+            MockFs = {...MockFs, [prop]: sandbox.stub().resolves()};
+            return MockFs[prop as keyof typeof fs];
+          })
+          .dynamic(), // this allows us to change the mock behavior on-the-fly
+        'env-paths': sandbox.stub().returns({data: DATA_DIR}),
+      })
+    ));
+  });
+
+  describe('BaseItem', function () {
+    describe('constructor', function () {
+      it('should set the id property based on the parent container', function () {
+        const item = new BaseItem('foo', {container: DATA_DIR} as Strongbox);
+        expect(item.id).to.equal(path.join(DATA_DIR, 'foo'));
+      });
+    });
+
+    describe('method', function () {
+      let item: Item<string>;
+
+      beforeEach(function () {
+        item = new BaseItem('foo', {container: DATA_DIR} as Strongbox);
+      });
+      describe('clear()', function () {
+        it('should remove the item from the filesystem', async function () {
+          await item.clear();
+          expect(MockFs.unlink).to.have.been.calledWith(item.id);
+        });
+
+        describe('if the item does not exist', function () {
+          beforeEach(function () {
+            MockFs.unlink.rejects({code: 'ENOENT'});
+          });
+          it('should not reject', async function () {
+            await expect(item.clear()).to.not.be.rejected;
+          });
+        });
+
+        describe('if something else goes wrong', function () {
+          beforeEach(function () {
+            MockFs.unlink.rejects(new Error('ugh'));
+          });
+          it('should reject', async function () {
+            await expect(item.clear()).to.be.rejectedWith(Error, 'ugh');
+          });
+        });
+      });
+
+      describe('read()', function () {
+        beforeEach(function () {
+          MockFs.readFile.resolves('skunk');
+        });
+        it('should read the item from the fileystem', function () {
+          expect(item.read()).to.eventually.equal('skunk');
+        });
+
+        it('should set the item value to the read value', async function () {
+          await item.read();
+          expect(item.value).to.equal('skunk');
+        });
+      });
+
+      describe('write()', function () {
+        beforeEach(async function () {
+          await item.write('bar');
+        });
+
+        it('should write the new item value to the filesystem', async function () {
+          expect(MockFs.writeFile).to.have.been.calledWith(item.id, 'bar');
+        });
+
+        it('should create the container', function () {
+          expect(MockFs.mkdir).to.have.been.calledWith(path.dirname(item.id), {recursive: true});
+        });
+      });
+    });
+  });
+});

packages/strongbox/test/unit/strongbox.spec.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import rewiremock from 'rewiremock/node';
-import type {Strongbox as TStrongbox, StrongboxOpts} from '../../lib';
+import type {Strongbox as TStrongbox, StrongboxOpts, Item, Value} from '../../lib';
 import {createSandbox, SinonSandbox, SinonStubbedMember} from 'sinon';
 import type fs from 'node:fs/promises';
 
@@ -10,7 +10,7 @@ type MockFs = {
 };
 
 describe('Strongbox', function () {
-  let strongbox: (name: string, opts?: StrongboxOpts) => TStrongbox;
+  let strongbox: (name: string, opts?: Partial<StrongboxOpts>) => TStrongbox;
   let Strongbox: new (name: string, opts?: StrongboxOpts) => TStrongbox;
   let sandbox: SinonSandbox;
   let DEFAULT_SUFFIX: string;
@@ -20,16 +20,19 @@ describe('Strongbox', function () {
 
   beforeEach(function () {
     sandbox = createSandbox();
-    ({strongbox, DEFAULT_SUFFIX, Strongbox} = rewiremock.proxy(() => require('../../lib'), (r) => ({
-      // all of these props are async functions
-      'node:fs/promises': r
-        .mockThrough((prop) => {
-          MockFs = {...MockFs, [prop]: sandbox.stub().resolves()};
-          return MockFs[prop as keyof typeof fs];
-        })
-        .dynamic(), // this allows us to change the mock behavior on-the-fly
-      'env-paths': sandbox.stub().returns({data: DATA_DIR}),
-    })));
+    ({strongbox, DEFAULT_SUFFIX, Strongbox} = rewiremock.proxy(
+      () => require('../../lib'),
+      (r) => ({
+        // all of these props are async functions
+        'node:fs/promises': r
+          .mockThrough((prop) => {
+            MockFs = {...MockFs, [prop]: sandbox.stub().resolves()};
+            return MockFs[prop as keyof typeof fs];
+          })
+          .dynamic(), // this allows us to change the mock behavior on-the-fly
+        'env-paths': sandbox.stub().returns({data: DATA_DIR}),
+      })
+    ));
   });
 
   describe('static method', function () {
@@ -38,6 +41,29 @@ describe('Strongbox', function () {
         const box = strongbox('test');
         expect(box).to.be.an.instanceOf(Strongbox);
       });
+
+      describe('when provided an absolute container path', function () {
+        it('should use the provided container path', function () {
+          expect(strongbox('test', {container: '/somewhere/else'}).container).to.equal(
+            '/somewhere/else'
+          );
+        });
+      });
+
+      describe('when provided a relative container path', function () {
+        it('should throw an error', function () {
+          expect(() => strongbox('test', {container: 'somewhere/else'})).to.throw(
+            TypeError,
+            'container slug somewhere/else must be an absolute path'
+          );
+        });
+      });
+
+      describe('when provided a suffix', function () {
+        it('should use the provided suffix', function () {
+          expect(strongbox('test', {suffix: 'mooo'}).suffix).to.equal('mooo');
+        });
+      });
     });
   });
 
@@ -51,8 +77,13 @@ describe('Strongbox', function () {
     describe('createItem()', function () {
       describe('when a Item with the same id does not exist', function () {
         describe('when the file does not exist', function () {
+          let item: Item<Value>;
+
+          beforeEach(async function () {
+            item = await box.createItem('SLUG test');
+          });
+
           it('should create an empty Item', async function () {
-            const item = await box.createItem('SLUG test');
             expect(item).to.eql({
               id: '/some/dir/strongbox/slug-test',
               name: 'SLUG test',
@@ -61,6 +92,10 @@ describe('Strongbox', function () {
               container: '/some/dir/strongbox',
             });
           });
+
+          it('should slugify the id', function () {
+            expect(item.id).to.equal('/some/dir/strongbox/slug-test');
+          });
         });
 
         describe('when the file exists', function () {
@@ -79,6 +114,15 @@ describe('Strongbox', function () {
           });
         });
 
+        describe('when attempting to read the file throws a non-ENOENT error', function () {
+          beforeEach(function () {
+            MockFs.readFile.rejects(new Error('ETOOMANYGOATS'));
+          });
+          it('should reject', async function () {
+            await expect(box.createItem('SLUG test')).to.be.rejectedWith(Error, 'ETOOMANYGOATS');
+          });
+        });
+
         describe('when a value is written to the Item', function () {
           it('should write a string value to the underlying file', async function () {
             const item = await box.createItem('test');
@@ -108,6 +152,13 @@ describe('Strongbox', function () {
           );
         });
       });
+
+      describe('when the second parameter is a valid encoding', function () {
+        it('should create the empty Item with the proper encoding', async function () {
+          const item = await box.createItem('test', 'base64');
+          expect(item.encoding).to.equal('base64');
+        });
+      });
     });
 
     describe('clearAll()', function () {
@@ -147,6 +198,28 @@ describe('Strongbox', function () {
           'value'
         );
       });
+
+      describe('when the third parameter is a valid encoding', function () {
+        it('should create the Item with the given value and proper encoding', async function () {
+          const item = await box.createItemWithValue('test', 'value', 'base64');
+          expect(item.encoding).to.equal('base64');
+        });
+      });
+    });
+
+    describe('getItem()', function () {
+      describe('when there is no known Item with the given id', function () {
+        it('should return undefined', function () {
+          expect(box.getItem('test')).to.be.undefined;
+        });
+      });
+
+      describe('when there is a known Item with the given id', function () {
+        it('should return the Item', async function () {
+          const item = await box.createItem('test');
+          expect(box.getItem(item.id)).to.equal(item);
+        });
+      });
     });
   });
 

packages/support/test/e2e/net.e2e.spec.js

@@ -16,7 +16,10 @@ describe('#net', function () {
   describe('downloadFile()', function () {
     it('should download file into the target folder', async function () {
       const dstPath = path.join(tmpRoot, 'download.tmp');
-      await downloadFile('https://appium.io/ico/apple-touch-icon-114x114-precomposed.png', dstPath);
+      await downloadFile(
+        'https://appium.io/docs/en/2.0/assets/images/appium-logo-white.png',
+        dstPath
+      );
       await fs.exists(dstPath).should.eventually.be.true;
     });
   });

packages/typedoc-plugin-appium/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.6.3](https://github.com/appium/appium/compare/@appium/typedoc-plugin-appium@0.6.2...@appium/typedoc-plugin-appium@0.6.3) (2023-04-18)
+
+
+### Bug Fixes
+
+* **typedoc-plugin-appium:** fix parameter display for execute methods ([5a70d7c](https://github.com/appium/appium/commit/5a70d7ce78ce12ef8b9209a2a17c52b02ac0fc80))
+
+
+
 ## [0.6.2](https://github.com/appium/appium/compare/@appium/typedoc-plugin-appium@0.6.1...@appium/typedoc-plugin-appium@0.6.2) (2023-04-12)
 
 

packages/typedoc-plugin-appium/lib/converter/method-map.ts

@@ -2,8 +2,8 @@ import _ from 'lodash';
 import {Context, DeclarationReflection, ReflectionKind} from 'typedoc';
 import {
   isCommandPropDeclarationReflection,
-  isExecMethodDefParamsPropDeclarationReflection,
   isHTTPMethodDeclarationReflection,
+  isMethodDefParamsPropDeclarationReflection,
   isRoutePropDeclarationReflection,
 } from '../guards';
 import {AppiumPluginLogger} from '../logger';
@@ -134,7 +134,7 @@ export function convertMethodMap({
 
       const payloadParamsProp = findChildByGuard(
         httpMethodProp,
-        isExecMethodDefParamsPropDeclarationReflection
+        isMethodDefParamsPropDeclarationReflection
       );
 
       const requiredParams = convertRequiredCommandParams(payloadParamsProp);

packages/typedoc-plugin-appium/lib/guards.ts

@@ -238,7 +238,7 @@ export function isExecMethodData(value: any): value is ExecMethodData {
 export function isMethodDefParamsPropDeclarationReflection(
   value: any
 ): value is MethodDefParamsPropDeclarationReflection {
-  return isReflectionWithReflectedType(value) && value.name === NAME_PARAMS;
+  return isReflectionWithReflectedType(value) && value.name === NAME_PAYLOAD_PARAMS;
 }
 
 /**
@@ -248,7 +248,7 @@ export function isMethodDefParamsPropDeclarationReflection(
 export function isExecMethodDefParamsPropDeclarationReflection(
   value: any
 ): value is ExecMethodDefParamsPropDeclarationReflection {
-  return isReflectionWithReflectedType(value) && value.name === NAME_PAYLOAD_PARAMS;
+  return isReflectionWithReflectedType(value) && value.name === NAME_PARAMS;
 }
 
 /**

packages/typedoc-plugin-appium/lib/theme/resources/partials/command.hbs

@@ -20,6 +20,7 @@
 {{/with}}
 
 {{else}}
+{{! the required/optional parameters bits are fallbacks }}
 {{#if hasRequiredParams}}
 
 ##### Required Parameters
@@ -53,8 +54,8 @@
 
 <!-- END:EXAMPLE -->
 {{/each}}
-{{/if}}
 <!-- END:EXAMPLES -->
+{{/if}}
 {{#if signature}}
 
 #### Response

packages/typedoc-plugin-appium/lib/theme/resources/partials/execute-method.hbs

@@ -3,35 +3,93 @@
 ### {{#ifNamedAnchors}} <a id="{{anchor}}" name="{{this.anchor}}"></a> {{/ifNamedAnchors}}Script: `{{name}}`
 
 {{#if hasComment}}
-
 {{> comment}}
-
+<!-- comment source: {{commentSource}} -->
 {{/if}}
 
 #### Route
 
 `{{httpMethod}} {{route}}`
 
-{{#if hasRequiredParams}}  
+{{#if parameters}}
 
-#### Required Parameters
+#### Parameters
+
+{{#with parameters}}
+
+{{{parameterTable}}}
+
+{{/with}}
+
+{{else}}
+{{! the required/optional parameters bits are fallbacks }}
+{{#if hasRequiredParams}}
+
+##### Required Parameters
 
 {{#each requiredParams}}
-
 - `{{this}}`
-
 {{/each}}
 
 {{/if}}
 
 {{#if hasOptionalParams}}
 
-#### Optional Parameters
+##### Optional Parameters
 
 {{#each optionalParams}}
 - `{{this}}`
 {{/each}}
 
 {{/if}}
-  
+{{/if}}
+
+{{#if hasExample}}
+#### {{pluralize 'Example' examples.length}}
+
+<!-- BEGIN:EXAMPLES -->
+{{#each examples}}
+##### {{lang}}
+<!-- BEGIN:EXAMPLE lang={{lang}} -->
+
+{{{text}}}
+
+<!-- END:EXAMPLE -->
+{{/each}}
+<!-- END:EXAMPLES -->
+{{/if}}
+{{#if signature}}
+
+#### Response
+
+{{#with signature}}
+
+{{#with type}}
+
+{{{type 'all'}}}
+
+{{/with}}
+
+{{#with comment}}
+
+{{{returns this}}}
+
+{{/with}}
+
+{{#with type}}
+
+{{#if declaration.signatures}}
+
+{{#each declaration.signatures}}
+
+{{> member.signature showSources=false }}
+
+{{/each}}
+
+{{/if}}
+
+{{/with}}
+
+{{/with}}
+{{/if}}
 {{/unless}}

packages/typedoc-plugin-appium/lib/utils.ts

@@ -5,12 +5,17 @@
 
 import _ from 'lodash';
 import {DeclarationReflection} from 'typedoc';
-import {isCallSignatureReflection} from './guards';
+import {isCallSignatureReflection, isReflectionWithReflectedType} from './guards';
 
 /**
  * Loops through signatures of the command's method declaration and returns the first that is a
  * `CallSignatureReflection` (if any).  This is what we think of when we think "function signature"
+ * This also works on DeclarationReflections that have a reflected type; in other words, some value that is the type of a function, but is not a function itself (such as a property assigned to a function).
  */
-export const findCallSignature = _.memoize((refl?: DeclarationReflection) =>
-  refl?.getAllSignatures()?.find(isCallSignatureReflection)
+export const findCallSignature = _.memoize(
+  (refl?: DeclarationReflection) =>
+    refl?.getAllSignatures()?.find(isCallSignatureReflection) ??
+    (isReflectionWithReflectedType(refl)
+      ? refl.type.declaration.getAllSignatures()?.find(isCallSignatureReflection)
+      : undefined)
 );

packages/typedoc-plugin-appium/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/typedoc-plugin-appium",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "TypeDoc plugin for Appium & its extensions",
   "homepage": "https://appium.io",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
     "build": "cpy lib/theme/resources build",
     "clean": "npx rimraf build",
     "test": "run-s test:unit",
-    "test:e2e": "mocha --timeout 20s \"test/e2e/index.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/builtin-external-driver.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/builtin-method-map.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/converter.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/external.e2e.spec.ts\"",
+    "test:e2e": "mocha --timeout 20s \"test/e2e/index.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/builtin-external-driver.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/builtin-method-map.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/converter.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/converter/external.e2e.spec.ts\" && mocha --timeout 20s \"test/e2e/theme/output.e2e.spec.ts\"",
     "test:smoke": "node ./index.js",
     "test:unit": "mocha --timeout 2s \"test/unit/**/*.spec.ts\""
   },

packages/typedoc-plugin-appium/test/e2e/helpers.ts

@@ -10,8 +10,8 @@ import {
   TSConfigReader,
   TypeDocOptions,
 } from 'typedoc';
-import {THEME_NAME} from '../../lib';
-import {BaseConverter} from '../../lib/converter';
+import {THEME_NAME, setup} from '../../lib';
+import {BaseConverter, NAME_BUILTIN_COMMAND_MODULE, NAME_TYPES_MODULE} from '../../lib/converter';
 import {AppiumPluginLogger} from '../../lib/logger';
 
 const {expect} = chai;
@@ -175,3 +175,13 @@ export interface InitConverterOptions<Args extends readonly any[] = any[]>
 type ConverterConstructor<T, C extends BaseConverter<T>, Args extends readonly any[] = any[]> =
   | Constructor<C, [Context, AppiumPluginLogger, ...Args]>
   | Constructor<C, [Context, AppiumPluginLogger]>;
+
+/**
+ * Creates a new TypeDoc application and/or resets it
+ */
+export function reset({
+  entryPoints = [NAME_TYPES_MODULE, NAME_FAKE_DRIVER_MODULE, NAME_BUILTIN_COMMAND_MODULE],
+  ...opts
+}: Partial<TypeDocOptions> = {}): Application {
+  return setup(initAppForPkgs({entryPoints, ...opts}));
+}

packages/typedoc-plugin-appium/test/e2e/index.e2e.spec.ts

@@ -1,16 +1,9 @@
 import _ from 'lodash';
-import {
-  Application,
-  Context,
-  DeclarationReflection,
-  ProjectReflection,
-  ReflectionKind,
-  TypeDocOptions,
-} from 'typedoc';
-import {convert, ConvertResult, postProcess, PostProcessResult, setup} from '../../lib';
+import {Context, DeclarationReflection, ProjectReflection, ReflectionKind} from 'typedoc';
+import {convert, ConvertResult, postProcess, PostProcessResult} from '../../lib';
 import {NAME_BUILTIN_COMMAND_MODULE, NAME_TYPES_MODULE} from '../../lib/converter';
 import {AppiumPluginReflectionKind, CommandReflection, ExtensionReflection} from '../../lib/model';
-import {initAppForPkgs, NAME_FAKE_DRIVER_MODULE} from './helpers';
+import {reset} from './helpers';
 
 const {expect} = chai;
 
@@ -34,16 +27,6 @@ describe('@appium/typedoc-plugin-appium', function () {
    */
   let extensionReflections!: ExtensionReflection[];
 
-  /**
-   * Creates a new TypeDoc application and/or resets it
-   */
-  function reset({
-    entryPoints = [NAME_TYPES_MODULE, NAME_FAKE_DRIVER_MODULE, NAME_BUILTIN_COMMAND_MODULE],
-    ...opts
-  }: Partial<TypeDocOptions> = {}): Application {
-    return setup(initAppForPkgs({entryPoints, ...opts}));
-  }
-
   describe('convert()', function () {
     describe('when "theme" is not "markdown" or "appium"', function () {
       it('should do nothing', async function () {

packages/typedoc-plugin-appium/test/e2e/theme/output.e2e.spec.ts

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import {tempDir, fs} from 'appium/support';
+import {jestSnapshotPlugin} from 'mocha-chai-jest-snapshot';
+import {convert} from '../../../lib';
+import {reset} from '../helpers';
+
+chai.use(jestSnapshotPlugin());
+
+const {expect} = chai;
+
+describe('@appium/typedoc-plugin-appium', function () {
+  let tmpDir: string;
+  before(async function () {
+    const app = reset({
+      plugin: ['typedoc-plugin-markdown', 'typedoc-plugin-crossmodule-references'],
+    });
+    const promise = convert(app);
+    const project = app.convert();
+    await promise;
+    expect(project).to.exist;
+    tmpDir = await tempDir.openDir();
+    await app.generateDocs(project!, tmpDir);
+  });
+
+  after(async function () {
+    await fs.rimraf(tmpDir);
+  });
+
+  describe('theme', function () {
+    describe('command output', function () {
+      it('should generate expected markdown', async function () {
+        const baseDriverMd = await fs.readFile(
+          path.join(tmpDir, 'commands', 'base-driver.md'),
+          'utf8'
+        );
+        expect(baseDriverMd).toMatchSnapshot();
+      });
+    });
+    describe('execute method output', function () {
+      it('should generate expected markdown', async function () {
+        const fakeDriverMd = await fs.readFile(
+          path.join(tmpDir, 'commands', 'fake-driver.md'),
+          'utf8'
+        );
+        expect(fakeDriverMd).toMatchSnapshot();
+      });
+    });
+  });
+});

renovate/default.json

@@ -47,7 +47,7 @@
     },
     {
       "extends": ["packages:eslint"],
-      "matchPackageNames": ["@appium/eslint-config-appium"],
+      "matchPackagePrefixes": ["@appium/eslint-config-appium"],
       "groupName": "ESLint-related packages",
       "groupSlug": "eslint"
     },
@@ -58,7 +58,8 @@
     },
     {
       "matchPackagePrefixes": ["@appium/"],
-      "excludePackageNames": ["@appium/eslint-config-appium"],
+      "excludePackageNames": ["@appium/eslint-config-appium", "@appium/eslint-config-appium-ts"],
+      "matchPackageNames": "appium",
       "groupName": "Appium-related packages",
       "groupSlug": "appium"
     }