Currently, failing to `require()` an extension and access its "main class" can result in a rather cryptic `TypeError`.
This adds two specific errors when:
- The path to the extension cannot be found. This could happen if someone, say, deletes the extension using `rm -rf`, but leaves `extensions.yaml` intact.
- The extension can be found, but its main class cannot be found. This would be due to an invalid extension and is generally not "user error"
Added some tests for it.
Lerna won't manage this for us. Further, `peerDependencies` should be as broad as possible. We can narrow this range later, if necessary. Narrowing the range will be a breaking change in the plugin.
This PR changes a few things:
- Extension problems are now displayed correctly at `appium server` startup. This was done by changing the default `npmlog` level, then reesetting it to `silent` when `winston` takes over (in `logsink.init()`)
- Extension problems are also displayed at install time.
- Improved performance of `appium <driver|plugin> install` in many cases by actually checking if the thing is installed _before_ installing it.
- `ExtensionCommand` uses a new console logging mechanism (`console` in `@appium/support`) tailored to CLI usage, since it is intended to be run via the CLI. Using this, we handle the result of extension checks both at server runtime and during CLI tool usage in the appropriate manner. The implementation is just a dumb wrapper around `console.log` and should eventually be removed when we revisit the logging architecture.
- Separated extension checks further into "errors" ("Problems") and "warnings". As these demand distinct log levels, `ExtensionConfig` no longer accepts a `logFn` in its constructor (since this restricted to a single level ("error"))
- Generally improved specificity, helpfulness, and reduced extraneous verbosity (like this sentence) of warnings
- Removed `strip-colors`, as this functionality is present in `@colors/colors`. The E2E test helper now automatically strips colors from child processes.
- More tests
- Change `e2e-helpers` to use `CliConsole` for command logging output during tests
- Change the "uninstall" command to use `npm uninstall`, since `rm -rf` will hose `node_modules` if the current project has a dependency on `appium` (in other words, if they are otherwise using a package manager to manage extensions). This is slower but safer.
This changes how plugins handle CLI args:
- The `cliArgs` instance prop of a `Plugin` will never be `undefined`. If there are no args, the prop will be an empty object.
- The `cliArgs` instance prop of a `Plugin` will now contain default values, if any were provided by the `Plugin`'s schema.
This differs from how the same property is handled in drivers. To that end, I split `AppiumDriver#getCliArgsForExtension()` (previously `assignCliArgsToExtension()`) into two separate methods for clarity.
This change also contains a few associated improvements to tests and types.
This PR changes the shape of plugin classes as well as how CLI args get assigned.
- The `pluginName` static property has been removed. `name` is now assigned via the `BasePlugin` constructor, and is derived from the plugin name in the manifest. This means that an implementor only needs to provide a `pluginName` in the manifest, and the data is not duplicated. The value in this map (the plugin name) is used to instantiate the plugin, instead of passing static `pluginName` property into the constructor.
- CLI args are now passed in through the constructor instead of assigned to the plugin instance after the fact.
Implementation details:
`getActivePlugins()` and `getActiveDrivers()` now return a `Map` of an extension _class_ to an extension name. The key is _not_ an instance, and is effectively a singleton, so we are not at risk of a memory leak.
This change does not otherwise affect drivers.
Resolves#16924
Because the `postinstall` script of `appium` needs functions in `@appium/support`, that module must be compiled _before_ its `postinstall` script runs. Prior to this PR, only the monorepo root would run a `postinstall` script to build the subpackages. Now, each package has a `prepare` script which runs its own build; this happens prior to any `postinstall`. This way, the `postinstall` script in `appium` can run successfully.
- Some types in `appium` were renamed
- Others avoid errors
- Some are minor tweaks to `tsconfig.json` files
# Conflicts:
# packages/appium/lib/extension/extension-config.js
# packages/appium/types/extension-manifest.ts
# packages/appium/types/extension.ts
# packages/base-driver/lib/jsonwp-proxy/proxy.js
# packages/support/lib/logging.js
# packages/support/test/unit/logger/logger-force.spec.js
- Also split out types into more files, since they were getting hefty
- The `Plugin` type conflicts with the [Plugin API](https://developer.mozilla.org/en-US/docs/Web/API/Plugin), which is detailed in TypeScript's DOM library. This changes makes `@appium/types` _avoid_ this library entirely, and only use the basic JS/Node.js types.
# Conflicts:
# packages/appium/types/extension.ts
# packages/types/lib/index.ts
The peer dependency value is stored in the `extensions.yaml` manifest for each extension as `appiumVersion` (if present).
If the peer dependency is _not_ present, the user will be warned, but Appium will still try to load the extension (I have a feeling that most of the time, this will be fine). When warned, the user will receive information about available extension upgrades, if any.
This required some refactors in the `lib/extension/` dir. Extension validation was previously a synchronous process, but because we now (potentially) display information to the user about upgrades (which is async), validation must also be async. This means that the `ExtensionConfig` constructor (and the constructors of its subclasses) cannot run validation. Validation must happen after the config object is instantiated, which is handled in `loadExtensions()` of `lib/extension/index.js`. The constructor signatures have changed accordingly.
While extensions now soft-require a `peerDependencies.appium` field, in the monorepo, the value of this dependency is `file:../appium`. This is treated as a special case, and acts as if the dependency is just the current version of `appium` (as in its `package.json`). This is handled in `Manifest#addExtension()`.
To further support this, `appium` now exports `@appium/base-driver` as `driver`, `@appium/base-plugin` as `plugin`, and `@appium/support` as `support`. `tsconfig.json` files have changed in these affected packages.
In addition, a new reusable TS config file has been added for use with basic plugins.
# Conflicts:
# .eslintrc
# packages/appium/lib/extension/extension-config.js
# packages/appium/lib/extension/index.js
# packages/appium/lib/extension/manifest.js
# packages/appium/test/unit/extension/manifest.spec.js
# packages/appium/test/unit/extension/mocks.js
`import` in jsdoc types previously using relative paths to reference the `types` folder can now be referenced via `appium/types`; e.g., `import('../types').Foo`, `import('./types').Foo`, `import('../../../types/bar').Foo` are now just `import('appium/types').Foo`
Also add some missing descriptions
This is a "fix" but only for the dev environment.
Further:
- add install of `mjpeg-consumer` to CI, since it may have disappeared from the environment
- remove `overrides` from `@appium/support`'s `package.json` since it no longer seems needed
Due to the way which drivers currently include `@appium/base-driver`, it's possible for a driver to become out-of-date with respect to `AppiumDriver` and fail to implement the expected interface. This change partially reverts the addition of `Driver.assignServer()`, which is a new function that old versions of `@appium/base-driver` do not implement.
Jonathan Lipps