[java] Fix: Convert By.className to css selector for Firefox inside Shadow DOM

[nityanandbb]

User description

🔗 Related Issues

Fixes #15961
(Handles InvalidSelectorException when using By.className inside Shadow DOM in Firefox)

💥 What does this PR do?

This PR fixes a known bug where By.className fails with InvalidSelectorException in Firefox when used to find elements inside a Shadow DOM.

• Adds a Firefox-specific workaround: By.className("foo") ➝ By.cssSelector(".foo") if Shadow DOM context is detected
• Leaves other browsers (e.g., Chrome, Edge) unchanged
• Ensures compound class names are rejected with a clear message
• Applies only within the ShadowRoot handling methods

🔧 Implementation Notes

• Introduced FirefoxClassNameWorkaround (package-private) in org.openqa.selenium.remote.shadow
• Updated ShadowRoot to resolve the selector before calling findElement or findElements
• Added logic to extract and convert className to a valid .cssSelector
• Wrote unit tests for Firefox and non-Firefox behavior in FirefoxClassNameWorkaroundTest

💡 Additional Considerations

• Compound class names (e.g., btn primary) will be rejected with a helpful error message
• Future improvement could generalize this conversion logic beyond just ShadowRoot
• No breaking change introduced

🔄 Types of changes

• Bug fix (backwards compatible)
• Tests added
• New feature
• Breaking change
• Cleanup only

---

Thank you Selenium maintainers for your time and review!

---

PR Type

Bug fix

---

Description

• Fix By.className failing with InvalidSelectorException in Firefox Shadow DOM

• Add Firefox-specific workaround converting className to CSS selector

• Implement compound class name validation with clear error messages

• Add comprehensive unit tests for Firefox and non-Firefox behavior

---

Diagram Walkthrough

flowchart LR
  A["By.className"] --> B["FirefoxClassNameWorkaround"]
  B --> C{"Firefox + Shadow DOM?"}
  C -->|Yes| D["Convert to By.cssSelector"]
  C -->|No| E["Use original By"]
  D --> F["ShadowRoot.findElement"]
  E --> F

Loading

File Walkthrough

Relevant files

Bug fix

ShadowRoot.java Integrate Firefox className workaround in ShadowRoot          java/src/org/openqa/selenium/remote/ShadowRoot.java Import FirefoxClassNameWorkaround class Apply workaround resolution in findElement and findElements methods Minor code formatting changes in equals method +7/-8      FirefoxClassNameWorkaround.java Add Firefox className to CSS selector converter                    java/src/org/openqa/selenium/remote/shadow/FirefoxClassNameWorkaround.java Create new package-private class for Firefox-specific workaround Implement browser detection logic for Firefox capabilities Add className to CSS selector conversion with compound class validation Provide public resolveForShadow method for ShadowRoot integration +44/-0

---

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ pujagani
❌ nityanandbb
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[qodo-merge-pro]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Fragile Implementation The extractClassName method uses string parsing on by.toString() which is fragile and could break if the toString format changes. Consider using reflection or a more robust approach to extract the className value from the By.ByClassName instance. private static String extractClassName(By by) { String raw = by.toString().replace("By.className:", "").trim(); return raw.replaceAll("\\s+", ""); } Exception Handling The broad catch block catches all exceptions and silently returns false, which could mask important errors like ClassCastException or other runtime issues. Consider catching more specific exceptions or adding logging. } catch (Exception ignored) { return false; } Input Validation The convertToCss method doesn't validate if the extracted className is empty or null, which could result in invalid CSS selectors like "." being generated. static By convertToCss(By by) { String className = extractClassName(by); if (className.contains(" ")) { throw new InvalidSelectorException( "Compound class names not supported in Firefox Shadow DOM. Use single class name or By.cssSelector instead." ); } return By.cssSelector("." + className); }

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Escape special characters in CSS selectors The CSS selector construction doesn't escape special characters that are valid in class names but need escaping in CSS selectors. Add proper CSS escaping to handle characters like colons, dots, or brackets. java/src/org/openqa/selenium/remote/shadow/FirefoxClassNameWorkaround.java [26-34] static By convertToCss(By by) { String className = extractClassName(by); if (className.contains(" ")) { throw new InvalidSelectorException( "Compound class names not supported in Firefox Shadow DOM. Use single class name or By.cssSelector instead." ); } - return By.cssSelector("." + className); + String escapedClassName = className.replaceAll("([:.\\[\\]()])", "\\\\$1"); + return By.cssSelector("." + escapedClassName); } Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a potential bug where class names with special CSS characters would create invalid selectors, and provides a correct fix to escape them, preventing runtime errors.	Medium
Possible issue	Use reflection for reliable field access The string parsing approach is fragile and may break with different By.ByClassName implementations. Use reflection to access the private className field directly for more reliable extraction. java/src/org/openqa/selenium/remote/shadow/FirefoxClassNameWorkaround.java [36-39] private static String extractClassName(By by) { - String raw = by.toString().replace("By.className:", "").trim(); - return raw.replaceAll("\\s+", ""); + try { + java.lang.reflect.Field field = by.getClass().getDeclaredField("className"); + field.setAccessible(true); + return (String) field.get(by); + } catch (Exception e) { + throw new RuntimeException("Failed to extract className from By.ByClassName", e); + } } Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that parsing the toString() output is fragile and proposes a more robust reflection-based approach, which significantly improves code quality and maintainability.	Medium
Learned best practice	Add null parameter validation Add null checks for the by parameter and the extracted className before using them. This prevents potential NullPointerException when these values are null or when string operations are performed on null values. java/src/org/openqa/selenium/remote/shadow/FirefoxClassNameWorkaround.java [26-34] static By convertToCss(By by) { + if (by == null) { + throw new IllegalArgumentException("By selector cannot be null"); + } String className = extractClassName(by); + if (className == null || className.isEmpty()) { + throw new IllegalArgumentException("Class name cannot be null or empty"); + } if (className.contains(" ")) { throw new InvalidSelectorException( "Compound class names not supported in Firefox Shadow DOM. Use single class name or By.cssSelector instead." ); } return By.cssSelector("." + className); } Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Add null checks and validation for parameters, properties, and return values before using them to prevent NullReferenceException and other runtime errors	Low
Update

[pujagani]

Please add tests for your changes. Also, update the related issue for this, it is pointing me to another PR for some reason.

[pujagani]

Please avoid formatting changes as part of a PR. If required, create a separate PR for it.

[nityanandbb]

Thank you for the review @pujagani 🙏

• I understand the concern about avoiding browser-specific logic in core classes like ShadowRoot. I'm working on isolating the logic into a utility class (e.g., SelectorResolver) to keep ShadowRoot clean and compliant with the architecture. I'll update the PR accordingly.

• I'll also remove any unrelated formatting changes from this PR and keep it focused on the bug fix only.

• Regarding tests: I’ll add test coverage specifically for Firefox + By.className inside Shadow DOM to verify the selector resolution behavior.

• I'll update the linked issue to correctly point to this PR and add context for the changes.

• For the CLA — I'll ensure it's signed shortly so the workflow can proceed.

Thanks again for the guidance. Will push the updates soon.

[pujagani]

I would highly recommend not adding browser-specific logic here.

[pujagani]

I am not convinced of the approach used in this PR, I would like others to chime in. @diemol

[diemol]

@nityanandbb, what bug is this PR fixing? The related issue is a pull request.

[nityanandbb]

@nityanandbb, what bug is this PR fixing? The related issue is a pull request.

@diemol This PR addresses an issue where driver.findElement(By.className(...)) and driver.findElements(...) fail in the latest versions of Firefox. Firefox no longer consistently supports By.className in certain DOM contexts, such as inside Shadow DOMs.

To fix this, I've added logic that detects if the browser is Firefox and automatically converts By.className into By.cssSelector as a workaround.
This fix applies to both findElement and findElements, and ensures compatibility with Firefox while leaving behavior unchanged for other browsers.

[diemol]

Can you please share the link to the GitHub issue?

[nityanandbb]

Can you please share the link to the GitHub issue?

Sure @diemol, the related GitHub issue is #15961.
This PR addresses the problem where using By.className with findElement or findElements inside Shadow DOM causes an InvalidArgumentException in Firefox.
The fix adds logic to switch from By.className to By.cssSelector specifically for Firefox, resolving the issue while preserving behavior for other browsers.

#15961

[nityanandbb]

Hi @diemol, thanks for the review!
This is my first contribution to Selenium open source, so there might be a few areas in the PR that need refinement.
I'm happy to make any changes or improvements you suggest. Appreciate your guidance!

[cgoldberg]

automatically converts By.className into By.cssSelector as a workaround.

I'm not familiar with the Java bindings, but in Python, we always convert class name into a css selector. There is no "class name" locator strategy in the WebDriver Spec, so I don't see how all bindings don't already do this... which leaves me confused what this PR is trying to do.

[diemol]

Thank you for your PR; however, the approach was a workaround instead of a proper fix. Perhaps you can check other open issues and send another PR, if you need guidance, please join our Slack channel https://www.selenium.dev/support/

The Java bindings do convert those locators to CSS before sending the payload to the driver, but this is done at a central place. We probably forgot to add the shadow DOM commands to this logic as well. I implemented the fix on #16149.