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
I'm not sure _what_ happened here other than "the types weren't strict enough" otherwise I would have noticed this earlier. Anyway; the check to see if we should dig into the config object to normalize the keys was getting passed _something_ but that _something_ wasn't anything it expected.
As a result, I needed to update some tests which assumed `readConfigFile()` resolved w/ an identity w/r/t the config file itself. It doesn't give the config file back verbatim any longer; the result will be normalized to camel-case keys (or whatever the `appiumCliDest` property is, if it exists)
* docs(appium): reorganize migration doc info so that appropriate bits are in their own docs
* Update packages/appium/docs/en/ecosystem/build-drivers.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/ecosystem/build-drivers.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/caps.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/caps.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/config.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/config.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/config.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/config.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/config.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* Update packages/appium/docs/en/guides/migrating-1-to-2.md
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* add header for extensions
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
This adds a test (which currently only runs automatically in CI) which installs the uiautomator2 driver. This will ensure that driver installation does not only work in a dev environment!
Due to needing to support Windows and not wishing to befoul the default `APPIUM_HOME`, we need `cross-env` as a production dependency (otherwise the smoke test would fail) to set a temporary `APPIUM_HOME` (`local_appium_home`) which is relative to the temp dir used by the smoke test (see https://github.com/boneskull/nodejs-production-test-action)
Also fix duplication of error messages about engines.
Unfortunately this adds another startup delay, but I'm unsure of a better way around it. I guess bundling our own npm might work!
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 removes the symlink we were creating to avoid an extra install of `appium` in `APPIUM_HOME`. Using a symlink obviously breaks stuff, because (for whatever reason) `npm` wants to run lthe `prepare` lifecycle script in the symlinked `appium`, which will not work outside of a dev environment due to missing dev depenencies.
Because npm v7+'s behavior is to install peer dependencies automatically, this will cause `appium` to be installed alongside any extensions in `APPIUM_HOME`. Each extension will have its own `appium`. This may just be the price we have to pay for using `APPIUM_HOME`, or there may be another solution to avoid the extra install (I'm not sure what it is). I think it _also_ exposes us to future bugs where the running Appium differs from whatever the peer dependency is set to... which sort of defeats the purpose of peer dependencies. Either way, the user will get a warning if the currently-running Appium is too new for an extension.
- `@appium/test-support` now exports the e2e setup for plugins, and e2e/unit suites for drivers from base-driver. it also generates declarations.
- `appium` exports this as `appium/test`.
- The `capability.spec.js` unit test for basedriver now avoids spying on the "global" logger, due to test flake. It now spies directly on the function which calls the global logger. (@mykola_mokhnach)
- removed homebrew ansi-stripping code from `test-support` and replaced with `@colors/colors`
- type fixes and refactors for `@appium/test-support`
- type fixes for `appium`
- simplify `lib/index.js` of `@appium/base-driver`
Ref: #17073
this change uses --legacy-peer-deps for newer versions of npm to
avoid installation of appium when installing extensions in ~/.appium. this does not work if the extension contains a shrinkwrap with appium in it, though.
in that case, an extra copy of appium will always be installed.
it creates a symlink, e.g., ~/.appium/node_modules/appium to the currently-running appium, wherever that is. could not abuse NODE_PATH to do this.
this is rather naive and does not check that the symlink is actually the same as the running appium if it already exists. that might cause some weird problems with multiple installs of appium on the same machine, but if it does, we can fix them as they arise.
I think, perhaps, having `.ts` files hanging around so that we can make declarations out of them is bad news. I got this idea from wdio. Anyway, the TS alias `appium` (often used as `appium/types`) points to the `types` dir -- not the `build/types` dir. It can't point to that, because recursion. That means an import from `../lib/constants` imports from the _ESM_ `../lib/constants`, which apparently is not understandable by the compiler since there is no `.d.ts` flie living there (even if `constants.js` is typed via docstrings, which it is). I don't know. It was easier just to do this for now. At some point later I'll look at using plain `.d.ts` files for this sort of thing, since it seems like it should work.
When any package here is consumed as a library, the production deps installed alongside it _must_ also include depenencies related to type information. If these packages _aren't_ included, consumers will not have the requisite declarations installed and will get incomplete type information--at best--or worse; compilation errors.
Putting the onus on the consumer to install these requisite types is both user-hostile _and_ can result in the incorrect versions of type declarations being installed.
To that end, I've moved the various type declaration deps to production deps of the packages in which they are used. Sometimes this is multiple packages (in the case of, say, `@types/teen_process`). This results in many types being removed from the monorepo root. Those that remain are for _dev dependencies only_. If a packages uses, say, `ws`, but only in its tests, then the types can remain in the monorepo root along with the rest of the common dev deps.
I also saw an unused `supports-color` in `appium` and removed it.
This makes a small handful of fixes related to type consumption:
- `@appium/types` is now a direct dep of `appium`. Without this, types leveraging `@appium/types`--e.g., `BaseDriver`, which is based on a `Driver` interface defined in `@appium/types`--fail to be understood fully by a consumer (such as an extension). Extension authors would need to install `@appium/types` as their own dev dependency. This change makes addition of `@appium/types` unneeded when consuming types exposed by `appium`, `appium/driver`, `appium/support`, etc.
- At this time, consumers will still need to add `@appium/types` if they wish to directly reference types defined in here (such as `W3CCapabilities`).
- In manual testing of the exported types, I found two issues in `appium/lib/schema/arg-spec.js` and `appium/lib/schema/schema.js` which were relative type imports and only worked in the context of the monorepo. I fixed these.
- `@appium/types` previously re-exported types defined within `axios` (`HTTPMethod`); I just copied and pasted what we needed to avoid the production dependency on `axios`.
- `@types/express`, `@types/npmlog`, `type-fest` and `@wdio/types` were added as production deps to `@appium/types`, as these are needed. However, these are packages _only_ containing types, unlike `axios`. There's a lesson to be learned here, but I don't know what it is.
* #16817 2.0 Chinese mkdocs-zh.yml
Rebase the code for mkdocs-zh
* #16817 2.0 Chinese mkdocs-zh.yml
Change the folder from cn to zh as mkdocs required
* #16817 2.0 Chinese mkdocs-zh.yml
Change the relative link from en to zh
* #16817 2.0 Chinese mkdocs-zh.yml
Translate some titles to trigger the build
This uses the [boneskull/nodejs-production-test-action](https://github.com/boneskull/nodejs-production-test-action) GH action to run a smoke test across all packages.
The action does the following:
1. Runs `npm pack` on each package, writing the tarball to a temp dir. This tarball contains the package as a user would `npm install` it.
2. Changes into the temp dir and runs `npm install <tarball>` on each
3. Runs a specified script (in our case, `test:smoke`) in each installed package's dir in `<tmp_dir>/node_modules`
Because `devDependencies` will not be present, this should avoid a class of issues where production deps are miscategorized as dev deps.
The action should probably use a separate temp dir for each--in the case of a dependency being present but only because some other package depends on it--but it's not smart enough to figure out peer dependencies yet.
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.
Jonathan Lipps