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.apache.grails:grails-geb'
    
    // This is needed to compile and run the tests
    integrationTestImplementation testFixtures('org.apache.grails:grails-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

Uploads

Uploading a file is more complicated for Remote WebDriver sessions because the file you want to upload is likely on the host executing the tests and not in the container running the browser. For this reason, this plugin will setup a Local File Detector by default.

To customize the default, either:

1. Create a class that implements ContainerFileDetector and specify its fully qualified class name in a META-INF/services/grails.plugin.geb.ContainerFileDetector file on the classpath (e.g., src/integration-test/resources).
2. Use the ContainerGebConfiguration annotation and set its fileDetector property to your ContainerFileDetector implementation class.

Alternatively, you can access the BrowserWebDriverContainer instance via the container from within your ContainerGebSpec to, for example, call .copyFileToContainer(). An Example of this can be seen in ContainerSupport#createFileInputSource utility method.

Timeouts

• grails.geb.timeouts.implicitlyWait
  • purpose: amount of time the driver should wait when searching for an element if it is not immediately present.
  • defaults to 0 seconds, which means that if an element is not found, it will immediately return an error.
  • Warning: Do not mix implicit and explicit waits. Doing so can cause unpredictable wait times. Consult the Geb and/or Selenium documentation for details.
• grails.geb.timeouts.pageLoad
  • purpose: amount of time to wait for a page load to complete before throwing an error.
  • defaults to 300 seconds
• grails.geb.timeouts.script
  • purpose: amount of time to wait for an asynchronous script to finish execution before throwing an error.
  • defaults to 30 seconds

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