In the case of `appium-xcuitest-driver`, each command (or execute) method is declared like so:
```ts
import {someMixin} from './some-mixins';
class XCUITestDriver {
foo = someMixin.foo;
}
```
The docstring exists on `someMixin.foo`, but not on the `foo` prop of an `XCUITestDriver` instance.
This change makes `@appium/typedoc-plugin-appium` dig into such references and derive the comments.
These can now return `T` and `T[]`, respectively. `T` defaults to `string`, but in `appium-xcuitest-driver`, `T` is either `string` or an object, depending on the settings.
- Doc gen for:
- `@appium/driver-test-support`
- `@appium/opencv`
- `@appium/plugin-test-support`
- `@appium/test-support`
- Added a `dev:docs` script in the root monorepo. The file watcher does _not_ presently rebuild reference docs upon changes to sources (which is a limitation of `@appium/docutils`).
- Changed the `dev:docs:*` scripts in `appium` to use `appium-docs` (so it rebuilds reference docs at least once [because it runs typedoc!!])
This seems to fix the bug in #18379. There must be some sort of bug in TypeScript w/r/t `@implements` or maybe even it was not treating `@typedef` as a proper alias. Perhaps it's user error--omitting optional type args in alias-style typedefs may end up making a new type entirely. idk, but this was easier to deal with.
Closes#18379.
Another handful of fixes.
- remove second "extra" parameter from `Capabilities`, `NSCapabilities` `W3CCapabilities`. we were not using it anywhere to my knowledge. it was an escape hatch anyway.
- never assign `BaseDriverCapConstraints` as the default constraints, because this is confusing as hell. instead, drivers should use the `*DriverCaps` types which automatically pulls the base constraints in. applied across several workspaces
- renamed `DeviceSettings` => `IDeviceSettings` because `DeviceSettings` is a class.
- the session ID param of `Core`'s `sessionExists()` is actually optional (per the implementation)
- allow some modicum of type narrowing at the class level around settings and values returned by `ISessionHandler`'s methods. also, not all values in the raw settings object are of the same type `T`, so fix that
- `server`, `serverHost`, `serverPort` and `serverPath` are not members of `Core` (using `AppiumDriver` as a litmus test--it interacts with `Driver` types but does not have these properties itself)
- changed a few types to interfaces where possible
- moved a lost comment
- further dumbed-down the logdef stuff
- `Driver.driverData` is _always_ defined, since `Core` makes it an empty array.
- `DriverOpts` no longer contains "partial" caps; this it not quite right as the caps are not assigned until a session is created, but there's a conflict between some props which are _both_ server args and defined in constraints. anyway, this is what `initialOpts` is for
- fix some type disagreements in basedriver's "capabilities" module
The first arg of `PluginCommand` is a `NextPluginCallback` which now returns `Promise<unknown>` instead of `Promise<void>`, which was incorrect.
We use `unknown` rather than `any` because it forces us to be explicit about the return value of `await next()` if we are to call it.
Added a type `DriverCommandToPluginCommand` which essentially converts a `DriverCommand` to a `PluginCommand`. It's probably best used as a type guard or decorator, but it can "fill in the blanks" when overloading commands in a plugin.
Also normalized some of the `TArgs`/`TReturn` stuff.
mainly because a "command" is a thing in drivers/plugins, and these classes refer to something else completely unrelated. renamed to `*CliCommand` to avoid confusion.
This removes `longjohn` and replaces it with a statement which increases the stack trace limit from the default (10) to 100.
I believe setting this overrides whatever was passed to the runtime `--stack-trace-limit` option. If someone complains, we can try a different strategy.
Closes#18357
- `PostProcessOptions` moved into `@appium/types`
- `shutdownUnexpectedly` cannot be marked `@protected` as anything used this way is inaccessible in mixins
- suppress a `@typescript-eslint` warning. this probably needs to happen in a few other files
This change removes types for methods in `ExternalDriver` (or rather the interfaces that build it) that were marked `@deprecated` and consumed by `appium-xcuitest-driver`. I salvaged what I could from the descriptions in these docstrings, and have moved them into `appium-xcuitest-driver` (obviously not in this repo).
Also:
- created some new files to group types logically
- created a `HTTPHeaders` type
- created a type `ConfigureAppOptions` for `DriverHelpers.configureApp`, and a `PostProcessOptions` type within it.
- added a couple other types
- fixed some signatures to look more like reality
- modified the return value of `queryAppState()` to return `0|1|2|3|4` instead of `0|1|3|4` since `appium-xcuitest-driver` returns the former
- made the `LogDef` and related types even _more_ loose. tbh these are very awkward to type properly; I cannot figure out a good way to narrowly type the `self` param to a log `getter`.
- noted which of the remaining `@deprecated` methods in `ExternalDriver` were _not_ in use by `appium-xcuitest-driver`, so I can later remove them once I've salvaged the docstrings to put into `appium-uiautomator2-driver`.
This PR does a handful of things:
1. It adds a `--verbose` flag to `appium <driver|plugin> list` which just dumps a big object (via Node's `util.inspect()`), which contains the underlying manifest file data
2. It creates a new manifest schema revision where the "install type" can be `dev`. Added a migration.
3. Displays a warning if trying to uninstall an extension in dev mode
4. Displays `[installed (dev mode)]` instead of `[installed (npm)]` when running `appium <driver|plugin> list` w/o `--verbose` flag
5. Attempted to simplify the return type of `ExtensionCommand.list()`
Closes#18277
In certain situations in `.ts` sources, class definition lines can get very long. Prettier will split these into multiple lines, and add a final line with `{` at position 0. This conflicts with the `brace-style` rule in ESLint. I am not sure why the ESLint prettier config doesn't already handle this, but I am going to guess it's because that config doesn't work on `.ts` sources.
BREAKING CHANGE: This makes `@appium/eslint-config-appium-ts` also apply to JS sources _and_ requires a new peer dependency (`eslint-import-resolver-typescript`). The `main` file is now a `.js` file. The module is expected to _extend_ `@appium/eslint-config-appium`, not replace it; consumers needn't extend both in their ESLint config.
In the not-too-distant past, `@typescript-eslint/parser` was unable to understand docstrings in `.js` files. Evidently this is no longer true.
I've rewritten and heavily commented the configuration explaining the intent behind everything.
Christopher Hiller