Improve types for cy.its() with property paths

[CypressJoseph]

• Provides type signatures for using cy.its() and cy.invoke() with property paths
• Adds kitchen-sink examples for path-based property access for these methods
• Provides more robust typing for cy.invoke()

• Closes .its command with compound properties failing TypeScript check #6431

User facing changelog

• Provide more robust type signature for cy.its() and cy.invoke() (overloads for property-path arguments; strongly-type invoke using ReturnType)

Additional details

• cy.its() is a wrapper around lodash's _.get, and so accepts a property path to glom into nested structures (my.nested.property), but this form wasn't given a signature
• Note we can't really infer the type through the its when given a nested property. But no red squiggly anymore...
• cy.invoke() uses the same strategy under the hood, so we provide property-path signatures for it as well

How has the user experience changed?

PR Tasks

• Have tests been added/updated?
• Has the original issue been tagged with a release in ZenHub?
• Has a PR for user-facing changes been opened in cypress-documentation?
• Have API changes been updated in the type definitions?
• Have new configuration options been added to the cypress.schema.json?

[cypress-bot]

Thanks for the contribution! Below are some guidelines Cypress uses when doing PR reviews.

• Please write [WIP] in the title of your Pull Request if your PR is not ready for review - someone will review your PR as soon as the [WIP] is removed.
• Please familiarize yourself with the PR Review Checklist and feel free to make updates on your PR based on these guidelines.

PR Review Checklist

If any of the following requirements can't be met, leave a comment in the review selecting 'Request changes', otherwise 'Approve'.

User Experience

• The feature/bugfix is self-documenting from within the product.
• The change provides the end user with a way to fix their problem (no dead ends).

Functionality

• The code works and performs its intended function with the correct logic.
• Performance has been factored in (for example, the code cleans up after itself to not cause memory leaks).
• The code guards against edge cases and invalid input and has tests to cover it.

Maintainability

• The code is readable (too many nested 'if's are a bad sign).
• Names used for variables, methods, etc, clearly describe their function.
• The code is easy to understood and there are relevant comments explaining.
• New algorithms are documented in the code with link(s) to external docs (flowcharts, w3c, chrome, firefox).
• There are comments containing link(s) to the addressed issue (in tests and code).

Quality

• The change does not reimplement code.
• There's not a module from the ecosystem that should be used instead.
• There is no redundant or duplicate code.
• There are no irrelevant comments left in the code.
• Tests are testing the code’s intended functionality in the best way possible.

Internal

• The original issue has been tagged with a release in ZenHub.

[flotwig]

This might also need to be added to cy.invoke, since its and invoke use the same code path for finding properties.

[cypress]

---

Test summary

6966 • 0 • 97 • 0

---

Run details

Project	cypress
Status	Passed
Commit	bd88020
Started	Mar 10, 2020 7:43 PM
Ended	Mar 10, 2020 7:48 PM
Duration	05:14 💡
OS	Linux Debian - 10.0
Browser	Multiple

View run in Cypress Dashboard ➡️

---

This comment has been generated by cypress-bot as a result of this project's GitHub integration settings. You can manage this integration in this project's settings in the Cypress Dashboard

Added better signatures for cy.invoke here too, curious what you think! 🤔

[bahmutov]

Like it, I think this works just fine

[flotwig]

these are redundant now, right?

[CypressJoseph]

I believe these signatures are capturing a slightly different case than the others (i.e., index-access into array of functions, which lets us type the return value somewhat more narrowly; note we're specifying that Subject extends T[] which isn't quite like the other forms?)

[NicholasBoll]

The changelog said the typings of its is now more robust. This solution returns any for a deep path, and worse yet, loses all type safety. If you misspell a property, there is no longer an error. The subject will silently become an any. That's less robust.

Would the Cypress team be open to allowing an array of keys for a path? Doing that would allow type safe deeply nested paths.

cy.wrap({ a: { b: 2 }}).it's(['a', 'b']) // number
cy.wrap({ a: { b: 2 }}).it's('b') // error
cy.wrap({ a: { b: 2 }}).it's(['a', 'c']) // error

[CypressJoseph]

I love this idea! 👍 We initially explored something like this because it could be strongly-typed, but the core problem is that under the hood we're still using lodash's `_.get`. If and when we have more control over the shape of this method I'd definitely be in favor of moving forward with this more path-oriented approach!

…

On Tue, Mar 17, 2020 at 11:28 AM Nicholas Boll ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In cli/types/index.d.ts <#6667 (comment)>: > @@ -1099,6 +1111,7 @@ declare namespace Cypress { * cy.wrap({foo: {bar: {baz: 1}}}).its('foo.bar.baz') */ its<K extends keyof Subject>(propertyName: K, options?: Loggable): Chainable<Subject[K]> + its(propertyPath: string, options?: Loggable): Chainable The changelog said the typings of its is now more robust. This solution returns any for a deep path, and worse yet, loses all type safety. If you misspell a property, there is no longer an error. The subject will silently become an any. That's less robust. Would the Cypress team be open to allowing an array of keys for a path? Doing that would allow type safe deeply nested paths. cy.wrap({ a: { b: 2 }}).it's(['a', 'b']) // numbercy.wrap({ a: { b: 2 }}).it's('b') // errorcy.wrap({ a: { b: 2 }}).it's(['a', 'c']) // error — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#6667 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOVVUCSZD7F4ZPGXD2MY3CLRH6JKHANCNFSM4LDDAO4Q> .

[CypressJoseph]

Thanks for pointing this out, by the way. We still want to be able to type simple property paths through (i.e., `cy.wrap({ a: 1 }).its('a')`), as there's a fallback that still permits `'a.nested.property'` with a weaker type.

…

On Tue, Mar 17, 2020 at 11:53 AM Joseph Weissman ***@***.***> wrote: I love this idea! 👍 We initially explored something like this because it could be strongly-typed, but the core problem is that under the hood we're still using lodash's `_.get`. If and when we have more control over the shape of this method I'd definitely be in favor of moving forward with this more path-oriented approach! On Tue, Mar 17, 2020 at 11:28 AM Nicholas Boll ***@***.***> wrote: > ***@***.**** commented on this pull request. > ------------------------------ > > In cli/types/index.d.ts > <#6667 (comment)>: > > > @@ -1099,6 +1111,7 @@ declare namespace Cypress { > * cy.wrap({foo: {bar: {baz: 1}}}).its('foo.bar.baz') > */ > its<K extends keyof Subject>(propertyName: K, options?: Loggable): Chainable<Subject[K]> > + its(propertyPath: string, options?: Loggable): Chainable > > The changelog said the typings of its is now more robust. This solution > returns any for a deep path, and worse yet, loses all type safety. If > you misspell a property, there is no longer an error. The subject will > silently become an any. That's less robust. > > Would the Cypress team be open to allowing an array of keys for a path? > Doing that would allow type safe deeply nested paths. > > cy.wrap({ a: { b: 2 }}).it's(['a', 'b']) // numbercy.wrap({ a: { b: 2 }}).it's('b') // errorcy.wrap({ a: { b: 2 }}).it's(['a', 'c']) // error > > — > You are receiving this because you modified the open/close state. > Reply to this email directly, view it on GitHub > <#6667 (review)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AOVVUCSZD7F4ZPGXD2MY3CLRH6JKHANCNFSM4LDDAO4Q> > . >

[NicholasBoll]

I love this idea! 👍 We initially explored something like this because it could be strongly-typed, but the core problem is that under the hood we're still using lodash's _.get. If and when we have more control over the shape of this method I'd definitely be in favor of moving forward with this more path-oriented approach!

Lodash's get method supports arrays for paths: https://lodash.com/docs/4.17.15#get. The type definitions support paths, too. I'd have to test it, but probably no code would have to change.

Thanks for pointing this out, by the way. We still want to be able to type simple property paths through (i.e., cy.wrap({ a: 1 }).its('a')), as there's a fallback that still permits 'a.nested.property' with a weaker type.

I guess that's fair... Lodash supports it as well. As soon as you put a . in there, lodash's types fall back to any. This loses type safety on the path. I'd say "with no type safety" vs "with a weaker type".

The tradeoff is 100% compatibility with Javascript code or stronger type checking. I lean toward stronger type checking, but I can understand the position. Lodash falls back to any. I just like when Typescript saves me from simple typos. The error is explicit. I'd rather have an error than silently losing all type safety with an any. I don't even have a local way to prevent the any fallback.

[NicholasBoll]

I've added an issue: #6758

I verified that array of keys is not allowed by Cypress (it does runtime type checks), but internally path traversal turns the string into an array anyway:

cypress/packages/driver/src/cy/commands/connectors.coffee

Lines 335 to 338 in 36866da

	if _.isString(str)
	paths = str.split(".")
	else
	paths = [str]