chore: Add extra chainer types for auto-complete

[NicholasBoll]

This adds the 4th item in #1040.

This change only adds auto-complete and help. Cypress supports strings for cy.shoud and cy.and. This PR adds a lot of happy-path assertions that help guide to what's available instead of just should: (assertion: string, value?: any, matcher:? any): Chainable<Subject>. If an assertion type isn't listed in the types, it will fall back to a simple string assertion. This does not actually add any type safety, just a nicer developer experience.

Here's a video of the auto-complete support in VS-Code with this change:

[NicholasBoll]

value: any is more accurate here. The first argument isn't always a string for 2-argument assertions.

[brian-mann]

Is there any way we can add a user description for each of the assertions? That would be an even better experience.

[brian-mann]

I'm really excited about this btw, this is huge!

[brian-mann]

Another question - since we know the type already, can we have the assertions be filtered by this?

Example:

// at this point we know mostly just jquery attertions matter here
// so we should't show assertions related to sinon, chai that are not applicable
cy.get('element').should(...)

[brian-mann]

Another question - can we get autocompletion for explict assertions like this:

cy.wrap('foo').should((str) => {
  expect(str).to.eq('foo')
})

[NicholasBoll]

Is there any way we can add a user description for each of the assertions? That would be an even better experience.

Yes! We can add JSDoc to each chainer type.

I'm really excited about this btw, this is huge!

I forgot to mention VSCode uses the TypeScript language service for JavaScript as well, so these helpers will show up when using JavaScript as well. Theoretically any IDE or editor using TypeScript language services (I know many do)!

Another question - since we know the type already, can we have the assertions be filtered by this?

I have types here that can do this: https://gist.github.com/NicholasBoll/57605bfd2176603dd75ea0e54afb2ce0#file-cypress-d-ts-L1427. Further down in the file are ChainerElements that only include jquery-chai assertions.

That does require breaking up the Chainer interface into separate interfaces. Possible interfaces are ParentCommand, ElementCommand, Command and ArrayCommand. (Not sure if "Command" is a preferred name). Or at least Command and ElementCommand (ParentCommand would just limit the cy.* methods exposed off of cy)

Another question - can we get autocompletion for explict assertions like this:

This is already supported by #1048. It added chai, chai-jquery and sinon-chai. So expect is already typed by those external definitions. The auto-complete is limited by one-at-a-time though. Like if I type expect(subject).to.be.a('string'), to, be and a are separate chained methods rather than it suggesting .to.be.a like how Cypress defines the chainer strings.

[NicholasBoll]

Is there any way we can add a user description for each of the assertions? That would be an even better experience.

@brian-mann I used https://docs.cypress.io/guides/references/assertions.html#Chai as a template for what chainers should be included, but there isn't descriptions there. Do you think the docs and the types should both contain descriptions? I think Chai's own API might be a good starting point: http://chaijs.com/api/bdd/

[brian-mann]

I would consider that we do have descriptions in the docs because we show an example of each assertion usage. That's likely enough for most users.

However the chai-jquery assertions could use more than just an example - they could use an explanation as well. So for those I would write something user specific.

[NicholasBoll]

Sure. I know VSCode supports examples with markdown which can be helpful in the tooltip. I would assume other editors can do that as well. I'll add those comments to the chainer methods and show what that looks like on a video.

I should be able to get to that later today

[NicholasBoll]

I've been working on it a bit. Here's a screenshot of what I have so far. This is from:

cy.wrap(4).should('be.below', 5)

[brian-mann]

Liking what I'm seeing 👍

[bahmutov]

that is great @NicholasBoll

[NicholasBoll]

😀 There must be a rush on this. This PR has the auto-complete, but not the extra docs in the last screenshot. I'll continue to add JSDocs to the auto-complete and open another PR.

[brian-mann]

Sure. When a PR is opened and it passes it's hard to keep up with it if its partially done. I thought this might be the case but we are doing a release tonight so just wanted to get it in. Each PR needs an associated issue so I can track the milestones and use it to generate the changelog.

[NicholasBoll]

Good call. The docs don't add any features, just improve it. Better to get incrementally better UX to people.

[daveerwin1]

This looks great, but I'm using intellij and I do have autocomplete working for things like .should, but autocomplete is not working for these string assertions, any idea why?

edit: I got this working after setting up typescript support via webpack, I made many changes but I believe the change that allowed the auto completion to work was adding:
"types": ["cypress"]
to tsconfig.json in the root dir (the docs mention putting this file in cypress folder, but that didn't work for me)
Also I need to ctrl + space to see the autocomplete, it doesn't happen automatically.

[Niceplace]

@daveerwin1 Care to share your tsconfig.json ? :) I'm having the same issue right now and I can't get autocomplete to work with should. Using cypress 3.2.0 and the following tsconfig.json (https://docs.cypress.io/guides/tooling/typescript-support.html#Configure-tsconfig-json) :

{
  "compilerOptions": {
    "strict": true,
    "baseUrl": "./node_modules",
    "target": "es5",
    "lib": [
      "es5",
      "dom"
    ],
    "types": [
      "cypress"
    ]
  },
  "include": [
    "**/*.ts"
  ]
}

[daveerwin1]

@Niceplace That is what I have in tsconfig.json
I found this blog post which helped me get it working:
https://glebbahmutov.com/blog/use-typescript-with-cypress/

[bahmutov]

Ohhh that guy’s blog posts...

…

Sent from my iPhone

On Mar 22, 2019, at 16:09, daveerwin1 ***@***.***> wrote: @Niceplace That is what I have in tsconfig.json I found this blog post which helped me get it working: https://glebbahmutov.com/blog/use-typescript-with-cypress/ — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.