Getting Started

Installation

Introduction

CSTesting for Java is a browser automation library designed for end-to-end testing and scripting. It drives Chrome via the Chrome DevTools Protocol (CDP) — no Playwright, no npx, no Node server. Run tests on Windows, Linux, and macOS, locally or on CI, headless or headed.

CSTesting is distributed as a Maven artifact. The easiest way to use it is to add one dependency to your project's pom.xml as described below. If you're not familiar with Maven, please refer to its documentation.

Usage

Get started by adding the dependency and running the example below.

pom.xml (add the dependency):

<dependency>
  <groupId>io.github.cstesttool</groupId>
  <artifactId>cstesting-java</artifactId>
  <version>0.1.4</version>
</dependency>

App.java (src/main/java/org/example/App.java):

package org.example;

import com.cstesting.CSTesting;
import com.cstesting.CSTestingBrowser;
import com.cstesting.CSTestingOptions;

public class App {
    public static void main(String[] args) {
        CSTestingBrowser browser = CSTesting.createBrowser(
            CSTestingOptions.builder().headless(true).build()
        );
        try {
            browser.gotoUrl("https://example.com");
            System.out.println(browser.title());
        } finally {
            browser.close();
        }
    }
}

Compile and run:

mvn compile exec:java -Dexec.mainClass="org.example.App"

No browser binaries are downloaded — CSTesting uses your system Chrome. To use a custom Chrome path, set -Dcstesting.chrome.path=/path/to/chrome.

First script

In this script we navigate to a page and take a screenshot (requires a small helper to save the page as PNG; here we use the title and URL as the "result"):

package org.example;

import com.cstesting.CSTesting;
import com.cstesting.CSTestingBrowser;
import com.cstesting.CSTestingOptions;

public class App {
    public static void main(String[] args) {
        CSTestingBrowser browser = CSTesting.createBrowser(
            CSTestingOptions.builder().headless(true).build()
        );
        try {
            browser.gotoUrl("https://example.com");
            browser.waitForLoad(5_000);
            System.out.println("Title: " + browser.title());
            System.out.println("URL: " + browser.url());
            browser.locator("h1").getTextContent();  // example interaction
        } finally {
            browser.close();
        }
    }
}

By default, the browser runs in headless mode. To see the browser window, set headless(false):

CSTestingBrowser browser = CSTesting.createBrowser(
    CSTestingOptions.builder().headless(false).build()
);

Running the example

mvn compile exec:java -Dexec.mainClass="org.example.App"

Browsers launched with CSTesting run headless by default (no visible window). Pass CSTestingOptions.builder().headless(false).build() to show the browser UI.

System requirements

• Java 11 or higher
• Chrome installed (used via CDP). On Windows: typical Chrome install path. On macOS: /Applications/Google Chrome.app. On Linux: google-chrome or chromium. Override with -Dcstesting.chrome.path=/path/to/chrome if needed.
• OS: Windows 10+, macOS 10.14+, or Linux (e.g. Debian, Ubuntu) on x86-64 or arm64.