Grails Geb Plugin

Geb Functional Testing for the Grails® framework

This plugin integrates Geb with Grails to make it easy to write functional tests for your Grails applications.

Examples

If you are looking for examples on how to write Geb tests, check:

Geb/Grails example project or Grails functional test suite where Geb tests are used extensively. For further reference please see the Geb documentation.

Usage

To use the plugin, add the following dependencies to your build.gradle file:

dependencies {
    
    // This is only needed to if you want to use the
    // create-functional-test command (see below)
    implementation 'org.grails.plugins:geb'
    
    // This is needed to compile and run the tests
    integrationTestImplementation testFixtures('org.grails.plugins:geb')
}

To get started, you can use the create-functional-test command to generate a new functional test using Geb:

./grailsw create-functional-test com.example.MyFunctionalSpec

This will create a new Geb test named MyFunctionalSpec in the src/integration-test/groovy/com/example directory.

There are two ways to use this plugin. Either extend your test classes with the ContainerGebSpec class or with the GebSpec class.

ContainerGebSpec (recommended)

By extending your test classes with ContainerGebSpec, your tests will automatically use a containerized browser using Testcontainers. This requires a compatible container runtime to be installed, such as:

• Docker Desktop
• OrbStack - macOS only
• Rancher Desktop
• podman desktop
• Colima - macOS and Linux

If you choose to use the ContainerGebSpec class, as long as you have a compatible container runtime installed, you don't need to do anything else. Just run ./gradlew integrationTest and a container will be started and configured to start a browser that can access your application under test.

Parallel Execution

Parallel execution of ContainerGebSpec specifications is not currently supported.

Custom Host Configuration

The annotation ContainerGebConfiguration exists to customize the connection the container will use to access the application under test. The annotation is not required and ContainerGebSpec will use the default values in this annotation if it's not present. A traditional GebConfig.groovy can be provided to configure non-container specific settings.

Reporting

To configure reporting, enable it using the recording property on the annotation ContainerGebConfiguration. The following system properties exist for reporting configuration:

• grails.geb.reporting.directory
  • purpose: if the test enables reporting, the directory to save the reports relative to the project directory
  • defaults to build/gebContainer/reports

Recording

By default, no test recording will be performed. Various system properties exist to change the recording behavior. To set them, you can set them in your build.gradle file like so:

tasks.withType(Test) {
  useJUnitPlatform()
  systemProperty 'grails.geb.recording.mode', 'RECORD_ALL'
}

• grails.geb.recording.mode

  • purpose: which tests to record
  • possible values: SKIP, RECORD_ALL, or RECORD_FAILING
  • defaults to SKIP

• grails.geb.recording.directory

  • purpose: the directory to save the recordings relative to the project directory
  • defaults to build/gebContainer/recordings

• grails.geb.recording.format

  • purpose: sets the format of the recording
  • possible values are FLV or MP4
  • defaults to MP4

Observability and Tracing

Selenium integrates with OpenTelemetry to support observability and tracing out of the box. By default, Selenium enables tracing.

This plugin, however, disables tracing by default since most setups lack an OpenTelemetry collector to process the traces.

To enable tracing, set the following system property:

• grails.geb.tracing.enabled
  • possible values are true or false
  • defaults to false

This allows you to opt in to tracing when an OpenTelemetry collector is available.

GebSpec

If you choose to extend GebSpec, you will need to have a Selenium WebDriver installed that matches a browser you have installed on your system. This plugin comes with the selenium-chrome-driver java bindings pre-installed, but you can also add additional browser bindings.

To set up additional bindings, you need to add them to your build.gradle for example:

dependencies {
    integrationTestImplementation 'org.seleniumhq.selenium:selenium-firefox-driver'
    integrationTestImplementation 'org.seleniumhq.selenium:selenium-edge-driver'
}

You also need to add a GebConfig.groovy file in the src/integration-test/resources/ directory. For example:

/*
    This is the Geb configuration file.

    See: http://www.gebish.org/manual/current/#configuration
*/

/* ... */
import org.openqa.selenium.edge.EdgeDriver
import org.openqa.selenium.firefox.FirefoxDriver

environments {
    
    /* ... */
    edge {
        driver = { new EdgeDriver() }
    }
    firefox {
        driver = { new FirefoxDriver() }
    }
}

And pass on the geb.env system property if running your tests via Gradle:

// build.gradle
tasks.withType(Test) {
    useJUnitPlatform()
    systemProperty 'geb.env', System.getProperty('geb.env')
}

Now you can run your tests with the browsers installed on your system by specifying the Geb environment you have set up in your GebConfig.groovy file. For example:

./gradlew integrationTest -Dgeb.env=edge