In Selenium's PageFactory, how do you bind a List<WebElement> field, and what happens to a field left unannotated?

## What PageFactory will and will not bind When `PageFactory.initElements` walks a page object it inspects each declared field and decides whether to assign it a lazy proxy. Only two shapes qualify: - a field whose type is `WebElement` (or a subtype of it), and - a field declared exactly as `List<WebElement>` **that carries** `@FindBy`, `@FindBys` or `@FindAll`. Everything else is skipped in silence. No exception is thrown, no warning is logged, and the field keeps whatever value it already had — which for an uninitialised field is `null`. ## The asymmetry that catches people The annotation is **optional on a `WebElement` field and mandatory on a list field**. - An unannotated `WebElement` field is still bound. Its locator is built from the **field's own name**, as `ByIdOrName("playlistTitle")`, which tries `By.id` first and falls back to `By.name`. That is why a page object whose fields are named after the markup's ids can work with no annotations at all — and why renaming such a field quietly changes the locator. - An unannotated `List<WebElement>` field is **not** bound. It stays `null`, and the first call on it — `trackRows.size()` — throws `NullPointerException`, far from the declaration that caused it. ## Declaring a list field `@FindBy(className = "track-row") List<WebElement> trackRows;` uses exactly the same `By` a single element field would use; the field's type decides how it is resolved. Points that follow from that: 1. The generic type must be `WebElement` itself. A raw `List`, a `List<String>` or a `List<TrackRowComponent>` is not bound even with an annotation. 2. Because the lookup resolves through `findElements`, a locator matching nothing yields an **empty list** rather than an error, so `trackRows.isEmpty()` is a legitimate assertion about an empty playlist. 3. `@FindBys` and `@FindAll` bind list fields too, so a list can be the rows inside one container or the union of several locators. ## A quick reference | Declaration | Bound? | Locator used | |---|---|---| | `@FindBy(id = "track-search") WebElement trackSearch;` | yes | `By.id("track-search")` | | `WebElement playlistTitle;` | yes | `ByIdOrName("playlistTitle")` | | `@FindBy(className = "track-row") List<WebElement> trackRows;` | yes | `By.className("track-row")` | | `List<WebElement> jingleCarts;` | no | none — field stays `null` | | `@FindBy(id = "genre") Select genreSelect;` | no | none — `Select` is not a `WebElement` | | `@FindBy(css = ".track-row") List<String> titles;` | no | none — wrong element type | The `Select` row is worth dwelling on, because wrapping a dropdown is a natural thing to want on a playlist editor's genre filter. `Select` is a helper class that wraps a `WebElement`; it is not one, so the field is skipped and stays `null`. The working shape is an annotated `WebElement` field that the page object wraps where it is used. ## Other rules the declaration must respect - The fields are assigned **reflectively**, so they may be `private` — that is the normal style — but they must not be `final`, because a final field cannot be assigned this way. - `@CacheLookup` is a **marker**: it takes no members, targets fields only, and is read alongside the locator annotation on the same field. It cannot be put on a class. - `@FindBy`, `@FindBys` and `@FindAll` may be written on a type as well as a field, but the Java client documents that a type-level annotation **is not processed by default** — putting one on the page class compiles and does nothing. - Fields declared on superclasses are bound too, because the factory walks the class hierarchy, so an annotated field on a shared base page is decorated on every subclass. ## Why the defaults are shaped this way The `ByIdOrName` fallback exists so a trivial page object needs no annotations at all, and the list rule exists because the factory cannot guess a sensible default for a collection: a field name is a plausible id for one element and a poor locator for many. The practical consequence for a page layer is that annotations are worth writing even where they are optional — they let the field be named for the domain (`playlistTitle`) while the locator keeps whatever the markup actually ships (`id="playlist_title_input"`), and they stop a rename from silently retargeting a lookup. The rule of thumb that follows: annotate every bound field, and treat an unannotated one as an accident rather than as a deliberate use of the fallback.