In Selenium's PageFactory, how do @FindBys and @FindAll differ when they annotate the same page-object field?

## What each annotation actually builds Selenium's `PageFactory` never stores your annotation. When `PageFactory.initElements` reaches a field, `Annotations.buildBy()` looks at which of the three locator annotations is present and turns it into a single `By` object, which the field's proxy then uses for every lookup. - `@FindBy` builds one plain `By`, such as `By.className("track-row")`. - `@FindBys({...})` builds a **`ByChained`** over the nested `@FindBy` entries, in the order written. - `@FindAll({...})` builds a **`ByAll`** over the nested entries, again in the order written. Both `ByChained` and `ByAll` live in `org.openqa.selenium.support.pagefactory` and are ordinary `By` subclasses, so nothing about them is specific to page objects — the annotations are just a declarative way to construct them. ## How ByChained walks the page `@FindBys` is a **descendant chain**, not a conjunction. On a radio-station playlist editor, `@FindBys({@FindBy(id = "on-air-queue"), @FindBy(className = "track-row")})` resolves like this: 1. Find every element matching the first locator — here the element whose id is `on-air-queue`. 2. For each element found, search **inside it** with the next locator, flattening all the results into one list. 3. Repeat for every remaining locator. If any stage returns nothing, the chain short-circuits and the whole result is empty. So the field ends up holding the `track-row` elements that sit **under** the on-air queue, and rows elsewhere on the page are excluded. `ByChained.findElement` returns the first survivor and throws `NoSuchElementException` when the list is empty. ## How ByAll collects `@FindAll` is a **union**. Every nested locator is run against the same search context and the result lists are concatenated in annotation order. - An element matched by two of the nested locators appears **twice** in the list. - The results are grouped by locator, so the list is **not in document order** — `ByAll` documents this explicitly. - On a `WebElement` field rather than a list, `ByAll.findElement` returns the first hit of the first nested locator that matched anything at all. That makes `@FindAll` a genuine ordered fallback: a save control spelled `#save-playlist` on the new station skin and `button[name='savePlaylist']` on the old one can be bound once. ## The two side by side | | `@FindBys` | `@FindAll` | |---|---|---| | Builds | `ByChained` | `ByAll` | | Meaning | each locator searched inside the previous match | every locator searched against the same context | | Result | narrowing by containment | union of all matches | | Ordering | document order within the final stage | grouped per locator, not document order | | Duplicates | not produced | produced when locators overlap | | One stage matches nothing | whole result is empty | the other locators still contribute | | Single-element use | first element under the chain | first match of the first locator that hit | ## Rules that bind both forms - Each nested `@FindBy` is validated on its own: **at most one location strategy per entry**, so `@FindBy(id = "on-air-queue", className = "track-row")` inside a `@FindBys` still throws `IllegalArgumentException`. - A field may carry only **one** of `@FindBy`, `@FindBys` and `@FindAll`. Combining them throws `IllegalArgumentException` with a message such as "If you use a '@FindBys' annotation, you must not also use a '@FindBy' annotation". - Both annotations work on a `WebElement` field and on a `List<WebElement>` field; the same `By` is resolved with `findElement` or `findElements` according to the field's type. - Validation is **eager**: the `By` is built while `PageFactory.initElements` decorates the field, so a malformed annotation fails immediately rather than at first use. ## Choosing one on a real page Reach for `@FindBys` when the second locator is only unique **inside** a container — the playlist editor's `.track-row` class appears in the on-air queue, in the archive drawer and in the sponsor scheduler, and only containment tells them apart. Reach for `@FindAll` when one logical control has two markup spellings you must tolerate at once, or when you deliberately want every jingle cart and every sponsor slot collected into a single list. Reaching for `@FindAll` because it sounds like "find all matching elements" is the usual mistake: a plain `@FindBy` on a `List<WebElement>` field already returns every match of one locator, and `@FindAll` only adds the union over several. Neither annotation changes when the lookup happens: like a plain `@FindBy`, the composed `By` is resolved against the live page each time the field is used, and the annotation itself only describes it.