In Selenium's @FindBy annotation, what is the difference between the shorthand attributes and the how/using pair?

## Two spellings, one annotation `@FindBy` in `org.openqa.selenium.support` accepts a locator in either of two forms, and the Java client's own documentation states the two are equivalent: - the **shorthand** form, one named attribute per strategy — `@FindBy(id = "track-search")`; - the **`how`/`using` pair**, a strategy constant plus its value — `@FindBy(how = How.ID, using = "track-search")`. Both are read by the same builder and both end up as `By.id("track-search")`. There is no runtime, performance or caching difference; the choice is a readability convention. ## The shorthand attributes and their How constants | Shorthand attribute | `How` constant | `By` built | |---|---|---| | `id` | `How.ID` | `By.id` | | `name` | `How.NAME` | `By.name` | | `className` | `How.CLASS_NAME` | `By.className` | | `css` | `How.CSS` | `By.cssSelector` | | `tagName` | `How.TAG_NAME` | `By.tagName` | | `linkText` | `How.LINK_TEXT` | `By.linkText` | | `partialLinkText` | `How.PARTIAL_LINK_TEXT` | `By.partialLinkText` | | `xpath` | `How.XPATH` | `By.xpath` | | *(none)* | `How.ID_OR_NAME` | `ByIdOrName` | | *(none)* | `How.UNSET` | delegates to `By.id` | Two rows in that table are the reason the long form still exists. `How.ID_OR_NAME` builds a `ByIdOrName`, which tries the value as an id and then as a name — and **there is no `idOrName` shorthand attribute**, so the pair is the only way to ask for it. `How.UNSET` is the default value of `how()`, and it delegates to `How.ID`; that is why `@FindBy(using = "now-playing")` with no `how` at all resolves to `By.id("now-playing")` rather than failing. Note the spelling of the CSS attribute: it is `css`, not `cssSelector`. The `By` factory method is `By.cssSelector`, the annotation attribute is not, and guessing wrong is a compile error rather than a test failure. ## How the builder resolves a field 1. `Annotations.buildBy()` finds which locator annotation the field carries and hands it to that annotation's `AbstractFindByBuilder`. 2. The builder validates the annotation: it collects every attribute that has been set to a non-empty value, counting a non-empty `using` as one of them. 3. It tries the shorthand attributes first, in a fixed order, and returns the first `By` it can build. 4. Only if no shorthand was set does it fall back to `how().buildBy(using())`. Step 4 is why you cannot mix the forms as a fallback pair: the shorthand always wins outright, so an annotation carrying both would silently ignore one — which is exactly why step 2 forbids it. ## The one-strategy rule If more than one strategy is set, the builder throws `IllegalArgumentException` reading "You must specify at most one location strategy", with the count and the offending values. That covers the combinations people reach for on a playlist editor: - `@FindBy(id = "track-search", name = "trackSearch")` — two shorthands, rejected. - `@FindBy(how = How.ID, using = "track-search", id = "track-search")` — the pair plus a shorthand, also rejected, because a non-empty `using` counts as a strategy. - Setting neither is legal and means "no shorthand", which then resolves through `How.UNSET`. The exception is raised while `PageFactory.initElements` decorates the page object, so a malformed annotation fails on construction of the page rather than on the first click. ## Where the annotation may be written `@FindBy` targets both fields and types. A type-level annotation compiles, but the Java client documents that it **is not processed by default**, so writing `@FindBy` on the `TrackSearchPanel` class itself changes nothing — the locator has to sit on the field that will hold the element. The same applies to `@FindBys` and `@FindAll`. `@CacheLookup` targets fields only, so the compiler stops that particular mistake for you. And whichever spelling you use, the annotation on its own does nothing at all: the locator is read, validated and turned into a `By` only when the page object is passed to `PageFactory.initElements`, which is what installs the value in the field. ## Which form to write - The shorthand is shorter, and on the eight everyday strategies it says exactly the same thing. - The pair is required for `How.ID_OR_NAME`. - The pair keeps the strategy in a uniform position, which helps when a base class or a code generator produces annotations mechanically. - Whichever you pick, the value is an annotation member and therefore a compile-time constant: a station id or a row index read at run time cannot be interpolated into either form. None of this changes which locator is a good idea for the markup in front of you — `@FindBy` only decides how the locator is spelled on the field.