chore: add option to get specific query suggestions

[smeijer]

1 - Add support for getting specific query method suggestions

What:
I've added an option to specify the desired method to the getSuggestedQuery method.

Why:
To enable tools (such as https://testing-playground.com) to show specific suggestions instead of only the most recommended one.

How:
getSuggestedQuery accepted the arguments element, variant, I've extended that to element, variant, method.

Method defaults to "best", but if specified, only the requested query will be suggested, or none at all.

This enables us to use it like:

getSuggestedQuery(input, 'get', 'PlaceholderText'));

If that call results in a valid suggestion, the suggestion is returned otherwise it will return undefined. It will not fall back to alternative methods!

The default behavior of the method has been left unchanged. A call like:

getSuggestedQuery(input, 'get'));

Still returns either the best query available, or undefined.

2 - added getByTestId suggestion

Sorry, I should learn to limit the scope of pull-requests. Even when they are tiny.

While working on the above, I noticed that a suggestion for getByTestId wasn't implemented. Testing-playground will render it red! But when there are really no other options, this query should still be suggested. It is part of the library after all.

So, I've also added the getByTestId suggestion, as last option available.

Checklist:

• Documentation added to the
  docs site
• Tests
• Typescript definitions updated
• Ready to be merged
  

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit ae31e42:

Sandbox	Source
agitated-margulis-giomk	Configuration

[codecov]

Codecov Report

Merging #627 into master will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master      #627   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           24        24           
  Lines          559       565    +6     
  Branches       140       142    +2     
=========================================
+ Hits           559       565    +6     

Impacted Files	Coverage Δ
src/suggestions.js	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b9900f8...ae31e42. Read the comment docs.

[kentcdodds]

Looks good to me! Thanks!

[kentcdodds]

🎉 This PR is included in version 7.14.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[nickmccurdy]

Great idea, thank you! I'm interested if there's any followup work we can do to provide more suggestions to users, especially in the linter plugins.

[smeijer]

especially in the linter plugins.

I'm not entirely the right person to answer that question. But as far as I understand linters and understood from a Twitter thread, that will be a hard thing to do. Which is why @testing-library/dom can now throw when it detects better query options.

The thing is, linters verify on a line-by-line basis. They don't eval the code. And @testing-library/dom doesn't show the user all the options, it only suggests the best. Which I believe is a good thing.

So, that's entirely why we have testing-playground (soon to be official! ❤️)

But maybe @benmonro has an idea on how to get more out of the suggestions?

[marcosvega91]

Maybe we can add a new method that will return a list of suggestions ordered by relevance ?

[smeijer]

Do you have a specific use case in mind?

I'm not sure if a function like this belongs to @testing-library/dom. As this project only suggests the best query available, and not all queries that are possible.

The base functionality that you describe is also quite trivial for other libraries to build themselves, by just using getSuggestedQuery. The more advanced case (that takes the entire dom context into account) is a bit harder, but also moves more out of the scope of this project.

[marcosvega91]

I wrote that but I agree with you, testing library shouldn't do this

[benmonro]

@nickmccurdy what did you have in mind? As Stephan mentioned the lint plugin can only analyze code statically. In order to make a suggestion you need to inspect a live dom.

I am still curious though because I do love writing lint rules. 🙂

[benmonro]

@kentcdodds @smeijer if we're adding test id to this shouldn't it check config to rather than hard coding to data-testid attribute? Not that big of a deal but our team uses an alternate attribute

[smeijer]

@benmonro, you're right. We should use the config for that.