Skip to main content

Getting Started

Get your first TestFly test running in under 5 minutes.

Prerequisites​

  • Java 21+
  • Maven 3.8+ or Gradle 8.5+
  • Chrome, Firefox, or Edge installed
info

No WebDriver binaries required — Selenium Manager handles browser driver downloads automatically.

Instant Setup with TestFly MCP & NPX (Recommended)

You can scaffold a production-ready TestFly Java 21 project with a single command:

npx @testfly/mcp init my-test-suite

This generates pom.xml, testfly.yml, and ready-to-run sample tests. Learn more in the TestFly MCP & CLI Guide.

Manual Setup​

If adding TestFly to an existing project, follow the steps below:

Step 1 — Add the dependency​

The examples below use the 1.0.7 source version. Before the release is published, check Maven Central for availability or use the latest published version instead.

pom.xml
<dependency>
    <groupId>io.github.hakanngul</groupId>
    <artifactId>testfly</artifactId>
    <version>1.0.7</version>
</dependency>
Using Gradle?

See the full Gradle Setup Guide for parallel config, JUnit 5, optional deps, and report locations.

Step 2 — Create the configuration file​

Create testfly.yml in your project root (next to pom.xml or build.gradle):

testfly.yml
execution:
  mode: local
  baseUrl: https://your-app.com

browser:
  name: chrome
  headless: false

retry:
  enabled: true
  maxAttempts: 2

timeouts:
  explicit: 10
  pageLoad: 30
Required keys

execution.mode, browser.name, timeouts.explicit, and timeouts.pageLoad are mandatory. If any of them is missing, TestFly stops at startup with a configuration error. Everything else has a sensible default.

Step 3 — Write your first test​

src/test/java/com/example/LoginTest.java
import io.testfly.test.BaseTest;
import org.testng.annotations.Test;

public class LoginTest extends BaseTest {

    @Test(description = "Valid user can log in")
    public void loginTest() {
        open();  // navigates to baseUrl
        // your test steps here
        softAssert().that(getDriver().getTitle().contains("Dashboard"), "Title should contain Dashboard");
    }
}

Step 4 — Create a TestNG suite​

testng.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="testfly-suite" verbose="1">
    <test name="MyTests">
        <classes>
            <class name="com.example.LoginTest"/>
        </classes>
    </test>
</suite>

Step 5 — Run​

mvn test

What happens​

  1. Framework loads testfly.yml
  2. Chrome launches automatically
  3. Your test runs
  4. Screenshot captured on any failure
  5. Browser closes
  6. HTML report generated at target/testfly-report.html (Maven) or build/testfly-report/ (Gradle)
  7. Metrics JSON at target/testfly-metrics.json

Project structure​

your-project/
├── pom.xml
├── testfly.yml
├── testng.xml
└── src/test/java/com/example/
    ├── pages/LoginPage.java
    └── tests/LoginTest.java

Working example project​

A complete working project is available at: https://github.com/hakanngul/testfly-test

Clone it, run mvn test (or ./gradlew test), and you'll have a full working suite with page objects, step logging, and retry configured.

Next steps​