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
apparently the "files" prop does not take into account what the ".npmignore" file says, so these were still getting published.
hopefully this will fix it.
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
- `@appium/gulp-plugins` does not use `tsc` and continues to use...whatever it uses.
- `@appium/doctor` now has generated declarations, though I didn't bother to do anything with the types
- rewrote swaths of build scripts:
- removed the `fix` and `lint` scripts from each workspace (package) since I don't think they get used and they are of limited value
- for tests and autoinstallation of extensions, added `ts-node` for on-the-fly compilation
- workspaces _can_ define their own `build` and `clean` scripts (both should be required if either is used). these do not currently get run when running `npm run dev`, but they do occur on a bare `npm install` from the monorepo root or a `npm run reinstall`.
- `npm run rebuild` does a fresh rebuild, but does not clean any `node_modules` dirs nor does it reinstall anything.
- removed `prepublishOnly` since `preversion` does the same thing
- `npm test` now runs `build`/`lint` in parallel
- postinstall script of `appium` ("autoinstall") script now must call `npm run build` if in a fresh dev environment. this is because a) lifecycle scripts of packages run before lifecycle scripts in the monorepo root, and b) `postinstall` runs before `prepare`. so there's really no way around it; even using `ts-node` fails because other modules depend on `@appium/support/index.js` which expects the pkg to be built.
Closes#17746Closes#17807
Run `npm run typedoc` to generate docs in `typedoc-docs` dir.
I thought I'd take a few mins and set this up. It was _mostly_ straightforward, except:
1. Figuring out the "entry point" for each package was difficult until I realized `.js` entry points are assumed to be compiled, and thus require a `sourceMappingUrl` reference. IMO this is probably a bug in TypeDoc
2. The `sourceMappingUrl` must reference an external sourcemap file; not an inline source map. If it's an inline source map, the system tries to `fs.open` a large data-url.
3. The babel config does not control whether external sourcemaps are created; `@babel/cli` does. So I needed to change those.
4. Practically speaking, I don't see any drawback to external sourcemaps _yet_
5. TypeDoc has poor support for cross-package type references in monorepos, and I had to add a plugin which implements a workaround
6. Per some suggestions in the docs, I modified the order of references in the root `tsconfig.json` to start with "the biggest one first"
I didn't modify any types or docstrings anywhere.
Jonathan Lipps