removal of the chainable promise types

[erwinheitzman]

Proposed changes

Based on a talk I had with Christian and my current team I decided to update our types to reflect that you do not need to await the $ and $$ commands.

I have replaced the types with TypeScript's Awaited utility type: https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype

Types of changes

• Polish (an improvement for an existing feature)
• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (improvements to the project's docs)
• Specification changes (updates to WebDriver command specifications)
• Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)
• I have added proper type definitions for new commands (if appropriate)

Reviewers: @webdriverio/project-committers

[christian-bromann]

I was thinking of only removing the Promise<T> part. I am not sure if removing ChainablePromiseElement would be a good idea.

[erwinheitzman]

I find that my colleagues have no clue what ChainablePromiseElement is and therefore just await it anyway and I cannot blame them. I think having WebdriverIO.Element as type makes much more sense, what do you think?

[christian-bromann]

I think the noticeable difference is that:

const chainablePromiseElement = $('elem')
console.log(chainablePromiseElement.selector) // outputs: "Promise<string>"

whereas:

const wdioElement = await $('elem')
console.log(wdioElement.selector) // outputs: "elem"

So I am not sure if we can merge this into one single type since the chainable element is not resolved and accessing properties requires to use await. I can see that ChainablePromiseElement is confusing and I am in favor to consolidate this. Any suggestion how we can overcome the type difference?

[erwinheitzman]

Interesting, does this mean that you need to await the $ command when accessing any properties but not when you want to execute an action later or chain it with another $ or $$ directly?

[christian-bromann]

Correct. You can do $('elem').$('elem').$('elem').$('elem') as our proxy command wrapper allows to chain these promises.

[erwinheitzman]

I believe you can extend the type to check if it has the elementId and if not you can assign it a Promise like type. I knowledge of Typescript is not where I want it to be so I might get a course on it to learn about more complex types 👍