tag	cbff036e08722a7d8de5771d94d3d6e91734673a
tagger	grails-build <grails-build@users.noreply.github.com>	Fri Dec 20 14:50:41 2024 +0000
object	835c9748a26b75d7de00b370a916e0963e6f4c5a

commit	835c9748a26b75d7de00b370a916e0963e6f4c5a	[log] [tgz]
author	James Daugherty <jdaugherty@jdresources.net>	Fri Dec 20 09:45:35 2024 -0500
committer	GitHub <noreply@github.com>	Fri Dec 20 09:45:35 2024 -0500
tree	47f2d539fdcc6b575937dd8b6f9ac940fd1571ee
parent	37b81c01e2194cfa0222423531ba9628011ea3d0 [diff]
parent	bcc8bf582eee7a2069b1abbe9cc4e7a7ed8085fe [diff]

tree: 47f2d539fdcc6b575937dd8b6f9ac940fd1571ee

README.md

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:

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.

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.

Recording

By default, no test recording will be performed. Here are the system properties available to change the recording behavior:

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/recordings
grails.geb.recording.format
- purpose: sets the format of the recording
- possible values are FLV or MP4
- defaults to MP4

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