Feature: natural language query functions for links and form elements

I’d like to see Cypress add natural language query functions for links and standard form elements.

One of the nicest things about the capybara API is that it has a few tricks that make selecting links and form elements (the element types an integration test will interact with most frequently) queryable with the same natural language text that users will see.

Here are a few examples from Capybara:

• click_link('Link Text'), click_button('Button Text'), click_on('a link or a button')
• fill_in('First Name', with: 'John')
• check('A Checkbox'), uncheck('A Checkbox')

And so on. None of these matchers are particularly challenging to implement, but they can dramatically improve the UX of a browser automation API, especially to people in non-typical developer roles. Additionally, selecting on text can improve the durability of a test suite against subsequent implementation changes, since you’re coupling to text users can see and not markup.

This style has been found to have a few benefits over the years:

• The intent of the test is more apparent, especially in cases where the markup is obtuse or unclear (and where making the markup cleaner is outside the control of the tester)
• The test is less likely to break due to implementation changes that are unimportant to the user. If the label of a form element changes, however, that’s almost always meaningful to somebody, since it’s visible to the users. This has the effect of decreasing the occurrence of false negatives (tests that fail but for which nothing is broken)
• It encourages better a11y, in particular for form elements, which sadly still often fail to have proper for & id attribute matching. If the test can select a form element correctly based on given label text, so can a screen reader

[searls]

Okay, I just published cypress-capybara, which implements the three most relevant and useful Capybara finder methods for the purposes outlined in the opening issue.

I scanned the rest of the Capybara DSL but didn’t see anything else that’d provide much value that isn’t (a) already implemented in Cypress’s built-in API, or (b) wouldn’t undercut the chaining API in the way @brian-mann described earlier.

Would love if you’d add this to your docs! 💚

[patcon]

For anyone reading along after, I just want to acknowledge that the philosophy espoused in the Cypress docs (using data-testid etc) is not the only philosophy, and some tools seem to have an opposite one. e.g., testing-library maintained by kentcdodds, used for react components https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change

so if you’re reading along feeling confused for feeling differently, you’re not alone – there are lots of different ways! Cypress just has opinions, like everyone 😃

EDIT: I do think the docs could do a better job of hinting at other philosophies, as I was hardcore data-testid for awhile (on blind faith in cypress docs) and am now realizing the wisdom of other ways, and kinda wondering why Cypress didn’t acknowledge this valid choice, and just kinda made it for me in the documentation 🙏