Running and debugging tests

Introduction

CSTesting tests are run using the built-in CSTestingRunner with annotations (@CSTest, @BeforeMethod, @AfterMethod, etc.). You pass the test class to the runner from code or from the command line. The runner creates a new browser for each test method, injects it into your test class, and closes it after each test.

By default, tests run headless (no browser window). To see the browser, run in headed mode by setting headless(false) in the browser options.

Running with CSTestingRunner

Use CSTestingRunner with a test class that extends CSTestingTestBase and uses @CSTest, @BeforeMethod, @AfterMethod, and optionally @BeforeSuite, @AfterSuite, @BeforeClass, @AfterClass. The runner discovers all @CSTest methods in the class and runs them one by one, with a fresh browser per test.

Run all tests in a class from code:

public static void main(String[] args) {
    CSTestingRunner.run(MyTest.class);
}

Run with custom options (e.g. headed browser):

CSTestingRunner.run(MyTest.class, CSTestingOptions.builder().headless(false).build());

Or override getBrowserOptions() in your test class so every run uses those options:

@Override
protected CSTestingOptions getBrowserOptions() {
    return CSTestingOptions.builder().headless(false).build();
}

Run from command line (Maven):

mvn exec:java -Dexec.mainClass="com.cstesting.runner.CSTestingRunner" -Dexec.args="com.example.MyTest"

Replace com.example.MyTest with the fully qualified name of your test class. The runner executes every @CSTest method in that class.

Run a single test class: Pass that class name as the first argument. To run only one test method, use a test class that has a single @CSTest method, or run the class and let the runner execute all its tests.

Using the annotation-tests profile (if configured in your project):

mvn exec:java -Pannotation-tests

This runs whatever test class is configured in the profile (e.g. AnnotationTestExample). Change the profile in pom.xml to point to your own test class if needed.

See Annotations for the full lifecycle and all annotations.

Run tests in headed mode

By default, the browser runs headless (no window). To see the browser window while tests run, set headless(false):

When calling the runner from code:

CSTestingRunner.run(MyTest.class, CSTestingOptions.builder().headless(false).build());

When the test class is run by the runner: Override getBrowserOptions() in your test class:

@Override
protected CSTestingOptions getBrowserOptions() {
    return CSTestingOptions.builder().headless(false).build();
}

Headed mode is useful for debugging and watching the test step through the page.

Running from the IDE

1. Run the test class's main method – If your test class has public static void main(String[] args) that calls CSTestingRunner.run(MyTest.class), run that class as a Java application. All @CSTest methods in that class will run.
2. Debug – Run the same main in debug mode and set breakpoints in your test methods or in CSTesting code. Execution will stop at breakpoints during the run.

Debugging tips

1. Headed mode – Use headless(false) to see what the browser is doing.
2. Slow down – Add browser.waitForTime(2000) (or similar) before a failing step to watch the page state.
3. Assertions – Use browser.assertThat(locator).isVisible() and other assertions to fail fast with a clear message.
4. Breakpoints – Run from the IDE in debug mode and set breakpoints in your test or in CSTesting; step through as each @CSTest method runs.
5. Console / network – In headed mode, you can use Chrome DevTools (if available) to inspect console logs and network.

Summary

Topic	CSTesting
Run all tests in a class	CSTestingRunner.run(MyTest.class) or Maven: mvn exec:java -Dexec.mainClass="com.cstesting.runner.CSTestingRunner" -Dexec.args="com.example.MyTest".
Run single test class	Pass that class name as the first argument to the runner. To run one test method only, use a class with a single @CSTest method.
Headless (default)	Default options or CSTestingOptions.builder().headless(true).build().
Headed (see browser)	CSTestingOptions.builder().headless(false).build() or override getBrowserOptions() in your test class.
From IDE	Run the test class's main (which calls CSTestingRunner.run(MyTest.class)). Use debug mode for breakpoints.
Debugging	Run in headed mode, add waitForTime if needed, use assertions and breakpoints in the IDE.