Skip to content
Alumnium
Blog Documentation

Alumnium v0.21 - Java client, Shadow DOM and cross-origin frame support

Published by Alex Rodionov's avatar Alex Rodionov
release notes

Alumnium v0.21 brings a full-featured Java client, adds support for Shadow DOM and cross-domain frames along with tons of small improvements and bug fixes.

This release was made for Maven Central, npm, and PyPI packages and a Docker image.

Java Client

Since v0.20, Alumnium core logic is centralized inside a cross-platform binary, which bundles a server used by other clients. The architecture is similar to Appium or Selenium, where a client would use an HTTP server to send commands such as do/get/check. With this new architecture, it was possible to implement a Java client that follows the same approach. The new client has near parity with Python and TypeScript packages, supporting all drivers (Appium, Playwright, Selenium) and LLMs.

Java client consists of the following packages published to Maven Central:

When installed, they are used together to write tests with Alumnium similar to Python and TypeScript. One notable difference is that do is a reserved keyword in Java, so we use act (or do_) instead.

import ai.alumnium.Alumni;
import org.openqa.selenium.chrome.ChromeDriver;


class AlumniumTest {
    public static void main(String...args) {
        ChromeDriver driver = new ChromeDriver();
        Alumni alumni = new Alumni(driver);
        driver.get("https://search.brave.com");
        alumni.act("type 'selenium' into the search field, then press 'Enter'");
        alumni.check("page title contains selenium");
        alumni.check("search results contain selenium.dev");
        alumni.quit();
    }
}

We have also updated all documentation to include Java examples (make sure to select t”Java” in the language switcher). Start with the Installation guide, then follow the Writing First Test guides for examples on integration with JUnit 5 and Appium, Playwright, or Selenium, and finally dive deeper into Guides.

All credits for the Java client implementation go to Ish Abbi, who I welcome to the contributors team!

Shadow DOM and Cross-Origin Frames

Two long-standing limitations in how Alumnium sees the page have been lifted in this release.

Alumnium now understands Shadow DOM. Elements encapsulated inside shadow roots - common in Web Components and many modern design systems - previously stayed invisible to the accessibility tree, so Alumnium couldn’t reason about or interact with them. They are now traversed and exposed like the rest of the page, for both Selenium and Playwright.

We’ve also added support for cross-origin frames in Playwright. When a page embeds an iframe from a different origin, Chromium renders it in a separate process (an out-of-process iframe, or OOPIF), which previously hid its contents from Alumnium. These frames are now included in the accessibility tree, so you can drive content inside cross-domain iframes the same way as the main page.

MCP Improvements

Many improvements were made in the MCP server:

  1. Bundled Playwright version was upgraded to 1.60.
  2. Playwright traces are now automatically saved inside the session artifacts folder (.alumnium/artifacts by default).
  3. A proxy field was added to alumnium:options which enables proxy for the browsers (supported for Playwright and Selenium).
  4. A userAgent field was added to alumnium:options which alters User-Agent header for the browser (supported for Playwright and Selenium)
  5. Environment variable values which use $(my-command) are treated as bash commands - Alumnium automatically executes the wrapped command and uses its output as the variable value.

Other Changes

This release also includes a number of smaller improvements and bug fixes:

  • Added support for LLM names containing slashes.
  • Promoted Gemini 3.1 Flash Lite from preview.
  • Removed the fuzzy matching layer of the elements cache.
  • Fixed Windows support.
  • Fixed parsing errors on complex accessibility trees.
  • Fixed selecting options inside <optgroup> elements.
  • Fixed “Illegal invocation” errors when waiting for the page to load.
  • Fixed missing runtime dependencies in the npm package.

Coming Next

With the Java client closing a major gap, we’d like to focus on extending Alumnium’s reach with an agents ecosystem:

  1. CLI. We have a basic version of a CLI skill working, allowing users to use Alumnium with coding assistants without the MCP server.
  2. Plugins. We’d like to add Claude Code and Codex plugins so Alumnium can be easily used for end-to-end testing during development with these agents.

On top of that, we’d like to eventually release a full-featured test runner. We are exploring the possibility of creating a test runner that can take free-form text and execute it with close-to-native performance and auto-healing. This would allow for building cross-platform tests without writing a single line of code.

Happy testing!