Support running commands against the previous yielded subject

[tlrobinson]

What:

Changes the custom Cypress commands to respect the previously yielded subject, for example, with the following document:

    <button>Button Text 1</button>
    <div id="nested">
      <button>Button Text 2</button>
    </div>

this

cy.get('#nested').findByText('Button Text 1').should('not.exist')

would previously fail because findByText was not passed the result of cy.get('#nested') as its container (defaulting to document)

Why:

It's a convenient way to scope commands to the result of a previous command, and for users of builtin Cypress commands it's surprising that @testing-library/cypress doesn't currently behave like this.

How:

The prevSubject option is now passed to Cypress.Commands.add() (with a value of ['optional', 'document', 'element', 'window'] which matches builtin commands like contains. This causes the subject (if any) to be passed as the first argument to the command. The subject is given lower precedence than the testing-library's container option, but higher precedence than the document itself.

Checklist:

• Documentation N/A
• Tests
• Ready to be merged
  

[kentcdodds]

This is fantastic. Thank you so much!

Would this mean this also works: cy.findByRole('dialog').findByText('submit')?

That would be stellar. Thanks again!

[kentcdodds]

We should probably disable the jest plugin for these tests. But we can do that in another PR :)

[kentcdodds]

Sorry about all these. Don't know how those slipped through in the first place

[kentcdodds]

Love this

[kentcdodds]

@all-contributors please add @tlrobinson for code and tests

[allcontributors]

@kentcdodds

I've put up a pull request to add @tlrobinson! 🎉

[kentcdodds]

Thanks so much for your help! I've added you as a collaborator on the project. Please make sure that you review the other/MAINTAINING.md and CONTRIBUTING.md files (specifically the bit about the commit messages and the git hooks) and familiarize yourself with the code of conduct (we're using the contributor covenant). You might also want to watch the repo to be notified when someone files an issue/PR. Please continue to make PRs as you feel the need (you can make your branches directly on the repo rather than your fork if you want). Thanks! And welcome to the team :)

[kentcdodds]

🎉 This PR is included in version 5.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[twgraham]

FYI this was a breaking change - all my tests that assumed findByText used the document broke after upgrading. It might be worth mentioning this in the releases, or bumping the major version if your doing semver.

[tlrobinson]

@twgraham out of curiosity, what did your tests that broke look like? This change shouldn’t break queries like cy.findByText(...). It would break some chained queries like cy.get(...).findByText(...), but IMHO the old behavior was broken.

[twgraham]

@tlrobinson kind of like the latter... cy.get(...).click(...).findBy*(...).click. E.g. Get this form field and type, then this field and type, then submit, all chained together.

I suppose we were treating a bit like 'get' because we realised early on that the previous subject wasn't yielded, so we had to do something like cy.get(...).then(el => cy.findByText(..., { container: el }).should(...)) if we wanted to scope it.

I think this PR is definitely a great idea - just didn't want people to get bitten unnecessarily.

[kentcdodds]

More discussion on this in #109. Please comment when you're able :)

[adamtay]

Great update and definitely prefer this style but as mentioned above, this has introduced a breaking change.

Example usage: cy.findByText(...).click().findByText('BREAK')

[kentcdodds]

Thanks @adamtay,

We are aware of this. Please see issue #109 where we're discussing what to do about it.