A thing we know about the `opts` object passed in to a driver constructor is that it does _not_ contain caps. This value is retained in `this.initialOpts`. Upon session creation, it _does_ contain caps.
This adds a new type, `InitialOpts`, which is the first parameter to a driver. In the future, it may accept a type argument, as currently any extension-specific options (defined via schema in `package.json`) are not typed.
Because `DriverOpts` is a superset of `InitialOpts`, this should not be a breaking change.
- because BaseDriver implements `findElOrEls` (technically), any subclasses must not inherit an interface containing a non-identical `findElOrEls` -- not even narrowing. so to avoid this, we will need to make it as broad as possible; no more generic `Ctx`
- likewise with `getLog`
- fix return type of `setGeoLocation`
- fix return type of `getPerformanceData`
- fix return type of `removeApp`
- fix return type of `hideKeyboard`
- fix return type of `getSystemBars`
- fix signature of various `touch*` methods
- fix return type of `setNetworkConnection`
alternatively, the deprecated methods mentioned here should be removed.
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
This change makes it so when running an extension script (e.g., `appium driver foo run some-script`), unless the `--json` flag is present, the child process will do no buffering whatsoever and will inherit `process.stdin`, `process.stdout` and `process.stderr` from Appium.
This means that extension scripts can do stuff like prompt the user for input. It _also_ means they can do stuff like display progress bars and spinners.
If the user wants JSON data, we revert to the old behavior, which is to buffer the output and dump it once the script has completed.
This changes the `fake-driver` implementation to use declaration merging instead of other alternatives to mixins.
History:
The original code simply assigned the mixin methods to `FakeDriver.prototype` after the `class` definition. In TS, this doesn't fly; you need to be explicit about what class members exist.
To get around this, we've tried multiple different approaches:
1. Use a "mixin pattern" as explained in the official TypeScript documentation, which involves _class factories_. This is tedious and difficult to reason about; each mixin must be passed to the next in-line, and we must be explicit about the base class and which _previous_ mixins any given mixin expects.
2. Use public class fields (a recent addition to JS). Basically, these do not work the way you want them to; if a subclass overrides a public field, a method in the superclass which refers to this public field _will use the field as defined in the superclass_--not the subclass. This is different than how methods and accessors work. This inhibits use of inheritance.
3. Add a method _for each method in each mixin_ to the base class, which simply calls `Function.prototype.apply` on the mixin with the context as the base class' `this`. This is too verbose.
There may be a better way to do this, but where we've landed is using _declaration merging_ in TypeScript. It allows us to add (but not remove, and I'm not sure about "modify") properties to the "FakeDriver interface", which seems to be the implicit TS interface created by the `class` keyword. Since the declaration merging syntax is not expressible in JavaScript, this requires a `.ts` file. To avoid creating _n_ extra files, it was easier to just make the mixins `.ts` files (you may note that we can mix-and-match JS and TS in our projects at will).
The implementation of each mixin uses `Object.assign()` to put new methods on the prototype, which are previously defined in the merged declaration above. Finally, a `satisfies` clause (which is a transient type-check; it does not change any types but it _will_ generate a compiler error) ensures the props being added to the prototype match what we've defined.
You'll also note that each method has a `this` parameter, which is not a "real" parameter--it's just an annotation for TS which tells the method what the context is. If we hate that, an alternative is to use `FakeDriver.prototype.method = <method>` instead of the `Object.assign` call. This feels marginally more tedious, but I could go either way.
If a command is not documented with a `@returns` tag, but a builtin method _does_ have this tag (e.g., `ExternalDriver.createSession()`), then the plugin will use the tag from the builtin.
If a command _does_ have a `@returns` tag, but it provides no description, then the plugin will use the original `@returns` tag (which may have a type) and combine it with the content/description from the builtin (if any).
This requires further inspection of `SignatureReflection` data, which needed a new set of "comment finders", which prompted me to refactor the comment finders into their own files (because it was becoming unwieldy). The call to `deriveComment` happens in the static `BaseCommandData.rewriteSignature()` method (whereas before it was just a straightforward clone operation).
- Fixed the block tag aggregation to prefer contentful over contentless tags in all cases.
- Modified the `@returns` tag of `FakeDriver.createSession()` for testing
- Moved some types around that were used outside of their sibling modules (e.g. `CommentSource` which used to be called `CommentSourceType`)
- pruned dead imports
This is getting pretty close, but:
- Commands from a driver will show even w/o a `newMethodMap` or `execMethodMap`; it is able to understand that it's overriding `BaseDriver`
- It's also able to understand the associated routes
- And it's able to understand the routes even if `BaseDriver` does not implement it
Still working on the parameters display, but we have the name override working at least.
Added some docstrings in `fake-driver`, `base-driver` for testing
This PR passes a `cliArgs` parameter to the static method `updateServer` of drivers and plugins so they can take action on the server configuration based on the content of the arguments.
Note that `cliArgs` is a misnomer, because these args can also come from configuration files.
Closes#17304
Resolves#17250
This change passes any extra unknown arguments to extension scripts _if and only if_ `appium <extension> <name> run` is executed. In all other cases, unknown arguments result in an error and the `appium` CLI will abort as before.
Example:
```bash
appium driver fake run fake-success --foo --bar`
```
In the `fake-success` script of the `fake` driver, `process.argv.slice(2)` will be `['--foo', '--bar']`. Extra arguments can appear anywhere after the `appium` executable in the command and do not need to appear after the script name.
- In addition, added some missing arguments for extension subcommands to the types (`json`, `suppressOutput`). Extra arguments are stored in property `extraArgs`.
- Fixed a type problem surfaced by the previous item
- Changed help text for the `run` subcommand to hopefully read more clearly
- Reorganized E2E tests for the `run` subcommand
- Slightly changed error output when unknown argument is provided (given that we now need to DIY this)
This PR removes Gulp from `@appium/fake-driver` as already done in a couple other packages.
Also: moved `screen.png` into `lib/` since `@babel/cli` can just copy it over into `build/`.
This now consumes Ajv directly to validate CLI args. Since a JSON schema is made of JSON schemas, we can simply validate an argument against _the schema for that argument_.
- Replaced parser transformation functions (`parseSecurityFeatures()`, `parseJsonStringOrFile()`) with custom transforms which are bound to keyword `appiumCliTransformer`. e.g., any option that can now accept a JSON string or filepath on the command line may use `appiumCliTransformer: 'json'`. This is the default behavior for `array` and `object` -type options, which cannot easily be expressed on the CLI. The config file does _not_ support this behavior, so the value must be whatever the schema `type` says (e.g., an `object` instead of a JSON string or filepath). To this end, removed `parser-helpers.js`
- Further, we now disallow union types in the schema. A prop must have a single type.
- Added custom keywords `appiumCliDest`, `appiumCliDescription`, and `appiumCliTransformer`. Previously (if existed), this could have been any value--these are now typed by the schema--e.g., a number for `appiumCliDest` will fail.
- Added more types and TS checks around
- Fixed misspelling of "successfully" in various places
- Removed `@oclifg/errors` because we can now use `better-ajv-errors` to display them, as intended. It looks great!
- Moved all schema-related stuff to `lib/schema/` because I had too many modules
- Added more constants to please @mykola-mokhnach 😄
- Handles untyped properties or `null`-typed properties
- `getSchema()`, `validate()` etc now accept a schema ID. The schema ID is derived from the argument name. This is how we handle validation for each argument individually. The config file is still validated against the entire schema at once.
- Fixed problem where only `driverConfigs` were ever used to call extension commands!
- Added some semaphore-like things to `ExtConfigIO` to avoid multiple reads/writes at once
- Fixed display of metavars in `--help`
- More tests; removed tests for removed code
* feat: add ability for drivers and plugins to recieve cli args
* chore: fix typo
* fix: make changes based on feedback
* feat: remove driver-specific server args from appium
* fix: resolve merge conflict
* fix: make changes based on feedback
* feat: add support for driver cli args in base driver
* feat: add support for testing driver args in fake-driver
* refactor: remove support for -custom locator strategy(should be handled by plugins instead)
* fix: makes changes based on feedback
* fix: remove outdated/unused args
* fix: fix docs
* fix: make changes based on feedback
* fix: make changes based on feedback
* fix: make changes based on feedback
* fix: make changes based on feedback
* fix: make tests pass
* test: tests are passing locally but not in CI, try something different to get them to pass
* test: try uninstalling fake-driver and reinstalling fake driver from packages
* fix: revert driver-e2e-specs.js and update node.js.yml
* fix: update package.json
* fix: add special case to npm
* fix: add todo
* fix: how relative paths are resolved in linkPackage
* chore: update @appium/fake-driver to use @appium/base-driver
BREAKING CHANGE: `fake-driver` now depends upon `@appium/base-driver@8.x`
## `@appium/fake-driver`
- need to use w3c capabilities only
- fix: find `app.xml` fixture properly when running tests via `mocha --require=@babel/register`
## `@appium/base-driver`
- fixed a dead URL in a comment
- updated the "logging" tests to manually supply w3c capabilities. `createSession()` does it for you, but `executeCommand('createSession')` does not.
- display the name of the driver under test when executing base driver's test suite with other drivers
Ref: #15425
* fix(fake-driver): add naive css selector support
* fix(fake-driver): helpers now use wdio instead of wd
- exported more constants as base-driver helpers do
- `deleteSession()` now expects a wdio `browser` (`driver`) object; removed closure
* fix(fake-driver): find-element-tests and driver-e2e-specs members passing
- alert-tests, context-tests, element-interaction-tests, general-tests all failing still
* fix(fake-driver): update interaction tests
replace unsupported `getLocation` with `getElementRect`
* fix(fake-driver): update alert tests
* fix(fake-driver): udpate context tests
* fix(fake-driver): update unit tests
* fix(base-driver): implement missing route for releaseActions
is the call to `this.proxyReleaseActions` even necessary?
* fix(fake-driver): update generic actions tests
also add a stub implementation of `releaseActions`, which wdio calls
* chore(fake-driver): remove redundant tests from find-element-tests
covered by other strategies
* fix(fake-driver): update generic actions tests
also fix path to screenshot (`screen.png`) when running tests outside of `build`
* chore(fake-driver): use fs module from @appium/support
* chore(base-driver): update hash in protocol consistency test
* fix(base-driver): update e2e test fn to prefer provided address/port over default
* chore: formatting
- all tests changed were needed because of path issues. I was unable to get the tests working in their entirety _without_ adding `@appium/fake-driver` to the monorepo--it would have required a separate `npm install` step in `appium-fake-driver` due to the lack of its `devDependencies` and `prepare` script--so I figured I might as well pull it in now.
- deduped `package.json` scripts somewhat
- updated ESLint configuration to include `@appium/fake-driver`'s rule override
- sorted the root `package.json` because fussy
- added `wd` as a dev dep because `@appium/fake-driver` needs it
Jonathan Lipps