feat!: provide additional selectors to ElementQuery

[joelpop]

Description

Fixes #662 & #1183 (partially)

Adds some selectors to ElementQuery (integration testing) to parallel those provided by ComponentQuery (unit testing). The selectors added in this change are limited to the ones that are "attribute" based.

• ElementQuery<T> withAttribute(String attribute)
• ElementQuery<T> withAttribute(String attribute, String value)
• ElementQuery<T> withAttributeContaining(String attribute, String value)
• ElementQuery<T> withoutAttribute(String attribute)
• ElementQuery<T> withoutAttribute(String attribute, String value)
• ElementQuery<T> withoutAttributeContaining(String attribute, String value)
• ElementQuery<T> withId(String id)
• ElementQuery<T> withClassName(String... className)
• ElementQuery<T> withoutClassName(String... className)
• ElementQuery<T> withTheme(String theme)
• ElementQuery<T> withoutTheme(String theme)
• T single()

In addition, three existing selectors that did not match the naming convention of the ComponentQuery (unit testing) selectors were deprecated in lieu of the new ones.

• ElementQuery<T> hasAttribute(String name) → ElementQuery<T> withAttribute(String attribute)
• ElementQuery<T> attribute(String name, String value) → ElementQuery<T> withAttribute(String attribute, String value)
• ElementQuery<T> attributeContains(String name, String token) → ElementQuery<T> withAttributeContaining(String attribute, String value)

Added both unit and integration tests for the new selectors and for others that were missing.

Updated the README.md file with instructions for configuring and running integration tests in the IntelliJ IDEA IDE.

Type of change

• Bugfix
• Feature

Checklist

• I have read the contribution guide: https://vaadin.com/docs/latest/guide/contributing/overview/
• I have added a description following the guideline.
• The issue is created in the corresponding repository and I have referenced it.
• I have added tests to ensure my change is effective and works as intended.
• New and existing tests are passing locally with my change.
• I have performed self-review and corrected misspellings.

Additional for Feature type of change

• Enhancement / new feature was discussed in a corresponding GitHub issue and Acceptance Criteria were created.

Additional missing selectors are currently being considered, such as:

• ElementQuery<T> withCondition(Predicate<T> condition)
• ElementQuery<T> withCaption(String caption)
• ElementQuery<T> withCaptionContaining(String text)
• ElementQuery<T> withText(String text)
• ElementQuery<T> withTextContaining(String text)
• <V> ElementQuery<T> withValue(V value)

[CLAassistant]

All committers have signed the CLA.

[joelpop]

@mshabarov

I want to point out one thing I changed in the implementation of ElementQuery::id that deserves some discussion.

Up until now there was no ElementQuery::single method or ElementQuery::withId method. Because of that, ElementQuery::id used ElementQuery::first. However, in one of the test cases (searchShadowDomBeforeLight) there were intentionally two ids to be found, so ElementQuery::first returned just the first one, and all was happy. However, I have implemented ElementQuery::single and ElementQuery::withId and then reimplemented ElementQuery::id to use them

public T id(String id) {
    return withId(id).single();
}

to mirror how ComponentQuery::id is implemented for unit tests. That change subsequently caused the searchShadowDomBeforeLight integration test to fail. I have changed the test from selecting on .id(id) to selecting on .withId(id).first() so its behavior is now as before.

What I want to make sure of is that this is not breaking anything in valid Vaadin light/shadow DOM HTML. It would be simple enough to switch ComponentQuery::id's implementation back to .withId().first(), but that seems wrong, because ids should be unique on a page.

However, this could potentially break some customers' tests, but that might be a valuable discovery for them—that they have duplicate ids.

I have added a note to ComponentQuery::id's Javadoc explaining the new behavior and how to revert to the previous behavior, if desired. My guess is that this change will have extremely low abrasion, and the silver lining is if the change does break something, it will break it for the good.

[mcollovati]

Good job and great that you updated the README!
However, once all the comments will be addressed, I propose to squash the change into two separated commits, one for the README update and the other for the code changes.

[mshabarov]

I want to point out one thing I changed in the implementation of ElementQuery::id that deserves some discussion.

First of all, I agree that fail fast if IDs are duplicated is an expected behaviour for ElementQuery::id and also it's better to keep it in sync with ComponentQuery::id, so I think we can change that.

I recommend to update ElementQuery::id javadoc to highlight this and tell how to get an element with duplicated ID if one wants this for any reason. Also, it probably makes sense to recommend the same in the error message that is thrown by ElementQuery::id, if it finds more than one element with the same ID.

[joelpop]

I want to point out one thing I changed in the implementation of ElementQuery::id that deserves some discussion.

First of all, I agree that fail fast if IDs are duplicated is an expected behaviour for ElementQuery::id and also it's better to keep it in sync with ComponentQuery::id, so I think we can change that.

I recommend to update ElementQuery::id javadoc to highlight this and tell how to get an element with duplicated ID if one wants this for any reason. Also, it probably makes sense to recommend the same in the error message that is thrown by ElementQuery::id, if it finds more than one element with the same ID.

Yes, this commenting has already been done.

[mcollovati]

LGTM.
I would just squash into two commits, one for README and the other for Java changes before merging into main

[mcollovati]

@mshabarov it looks like "Rebase and merge" is not enabled on this repo.
I'll create a new PR with the README updates commit only, and once that is merged we can rebase this one on top of main.