skip to content

In Selenium's PageFactory, why do component classes use initElements(SearchContext, Object) rather than the Class-taking overload?

level: middleimportance: should knowfreq 31%

answer

  1. One overload builds the object for you
  2. Four entry points, two different jobs
  3. It only knows one constructor shape
  4. A root is not a driver
  5. Construct first, decorate second

basics

~20 s

The Class overload constructs the object itself, using a WebDriver constructor if one exists and otherwise a no-arg one, so it can never hand a component its root element. You build the component with its root, then decorate it.

solid answer

~40 s

`initElements(SearchContext, Class<T>)` instantiates the class for you: it looks for a constructor taking `WebDriver`, invokes it with whatever context you passed, and otherwise falls back to the no-arg constructor. Neither path can give a component the root `WebElement` that defines it — a component with a `LotCard(WebElement)` constructor has no matching path at all, and one with a `WebDriver` constructor gets an argument-type mismatch when a `WebElement` arrives. Even when instantiation succeeds, the object holds no reference to its root, so it cannot do ad-hoc lookups inside its own widget. In Selenium 4 the working shape is `new LotCard(root)` followed by `PageFactory.initElements(root, this)` inside that constructor.

code

java · 14 lines
java
WebElement root =
    driver.findElement(By.cssSelector("div.lot-card[data-lot='B-4417']"));

// Works: construct the component with its root, then decorate its fields.
LotCard card = new LotCard(root);
PageFactory.initElements(root, card);

// The same call, with the locator factory wired explicitly.
LotCard explicitCard = new LotCard(root);
PageFactory.initElements(new DefaultElementLocatorFactory(root), explicitCard);

// Does not work: this overload builds the object itself and
// can only feed a WebDriver-typed or no-arg constructor.
LotCard broken = PageFactory.initElements(root, LotCard.class);

go deeper

for a junior

Remember the practical rule: construct the component yourself with its root, then call initElements with that root and the object. Do not reach for the overload that takes a class.

for a middle

Be able to describe what the Class overload does internally — a WebDriver constructor if present, otherwise the no-arg one — and why neither can deliver a root element to a component.

for a senior

Show the design reasoning: the object-taking overloads exist so construction stays yours, which is what lets a component receive its boundary and pass child roots to nested components.

for a principal

Own the convention for a harness: whether components construct and decorate themselves, and whether the team supplies a shared ElementLocatorFactory rather than calling PageFactory ad hoc across the codebase.

## Four overloads, two jobs `PageFactory` in the Selenium 4 Java bindings exposes four `initElements` entry points, and they split into two jobs: *make me an object and decorate it*, or *decorate this object I already have*. | overload | what it does | fits a component object | |---|---|---| | `initElements(SearchContext, Class<T>)` | instantiates the class, then decorates it | no — it has no way to pass a root | | `initElements(SearchContext, Object)` | decorates an object you constructed | yes, the normal choice | | `initElements(ElementLocatorFactory, Object)` | decorates using a factory you supply | yes, when you wire the context yourself | | `initElements(FieldDecorator, Object)` | decorates using a decorator you supply | yes, for custom field handling | A page object per URL is usually happy with the first: it needs no constructor argument beyond the driver. A **component object** is defined by the argument it must receive, and that is exactly what the first overload cannot give it. ## What the `Class` overload does when it instantiates Its private `instantiatePage` step is short and specific: 1. Look for a constructor whose single parameter type is `WebDriver`. 2. If there is one, invoke it with the `SearchContext` that was passed in. 3. If there is no such constructor (`NoSuchMethodException`), fall back to the **no-arg** constructor. 4. Wrap reflective failures in a `RuntimeException`. Two consequences follow, and both bite component classes: - If your component declares `LotCard(WebElement root)`, step 1 finds nothing — the parameter type is `WebElement`, not `WebDriver` — so step 3 runs and demands a no-arg constructor you did not write. Instantiation fails. - If your component declares a `WebDriver` constructor to satisfy step 1 and you pass a root element, `newInstance` is handed a `WebElement` for a `WebDriver` parameter and raises an `IllegalArgumentException` for the argument type mismatch. That is not a `ReflectiveOperationException`, so the surrounding catch does not translate it and it escapes as-is. There is a third, quieter consequence. Even in the case where a no-arg constructor exists and the call succeeds, the object you get back has **no reference to its root**. Its `@FindBy` fields are correctly scoped, because the locator factory holds the context, but the object itself cannot do `root.findElement(...)` for anything the annotations did not anticipate, cannot read the widget's own attributes, and cannot hand its root to a nested component. ## The shape that works ```java WebElement root = driver.findElement( By.cssSelector("div.lot-card[data-lot='B-4417']")); LotCard card = new LotCard(root); // you pass the root PageFactory.initElements(root, card); // then decorate against it ``` Most component classes fold the second line into the constructor, so the caller only writes `new LotCard(root)`. The constructor stores the root and calls `PageFactory.initElements(root, this)` — the object receives its boundary and its fields are decorated against the same context in one step. ## Wiring the factory yourself `initElements(SearchContext, Object)` is a convenience over the factory overload: - `PageFactory.initElements(root, card)` is exactly `PageFactory.initElements(new DefaultElementLocatorFactory(root), card)`. - `DefaultElementLocatorFactory` is a `final` class holding one `SearchContext` and creating a `DefaultElementLocator` per field. - Constructing the factory explicitly is worth it when you want to pass the same factory to several objects, or when you swap in a different `ElementLocatorFactory` implementation while keeping the element as its context. - If an `ElementLocatorFactory` returns `null` for a field, that field is simply not decorated — a supported way to opt fields out. ## Practical rules for a component class - Take the root in the constructor and keep it in a field; do not rely on the proxies alone for your boundary. - Call `PageFactory.initElements(root, this)` from that constructor, never the `Class` overload. - Do not give a component a `WebDriver`-typed constructor. It is the one shape that turns a scoping mistake into a confusing reflection error instead of a compile-time one. - Construct nested components from the parent's root, passing the child root down the same way. The underlying point is that the `Class` overload was written for the page-per-URL case, where the only thing an object needs to be built with is the driver. A component object's identity **is** its root, so it belongs to the family of overloads that decorate an object you have already built, with the root supplied by you and used as the search context for every annotated field.

  • What exactly does the Class overload do when it instantiates the page?
    It calls `getConstructor(WebDriver.class)` and invokes it with the search context that was passed; if no such constructor exists it falls back to the declared no-arg constructor, and reflective failures become a RuntimeException. Neither route accepts a WebElement parameter, which is why a component cannot be built this way.
  • If the proxied fields are already scoped to the root, why keep the root in a field too?
    Because the annotations cannot anticipate everything. Holding the root lets the component read the widget's own attributes, run ad-hoc lookups inside its subtree, and pass a child root to a nested component. Without it the object has fields but no handle on its own boundary.
  • When would you construct the DefaultElementLocatorFactory yourself instead of passing the element?
    When several objects should share one configured factory, or when you want to substitute a different ElementLocatorFactory while keeping the element as the context. `initElements(root, card)` is simply shorthand for `initElements(new DefaultElementLocatorFactory(root), card)`.

saying these in an interview costs you the question

  • Calls initElements with the root and a Class, expecting the root to reach the constructor.
  • Thinks the Class overload passes the context to any single-argument constructor.
  • Believes DefaultElementLocatorFactory must be constructed with a WebDriver.
  • Assumes every initElements overload returns a newly created object.
  • Gives a component class a WebDriver constructor and initialises it from an element.