From 7e4df061d250b3cdd935ff3d0516fbd41388b8f5 Mon Sep 17 00:00:00 2001 From: Mattias Reichel Date: Mon, 4 Nov 2024 18:24:38 +0100 Subject: [PATCH] docs: Update README.md --- README.md | 73 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 56 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index be924a1..3ac9bda 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,39 @@ ## Geb Functional Testing for the Grails® framework -This plugin provides the Geb dependencies and a `create-functional-test` command for generating Geb tests in a Grails app. +This plugin integrates [Geb](https://www.gebish.org) with [Grails](https://www.grails.org) to make it easy to write functional tests for your applications. -It also provides a `ContainerGebSpec` class, which can be used in place of `GebSpec`, that automatically -runs the browser in a container using [Testcontainers](https://java.testcontainers.org/). This requires a -[compatible container runtime](https://java.testcontainers.org/supported_docker_environment/) be installed, such as: +## Examples + +If you are looking for examples on how to write Geb tests, check: + +[Geb/Grails example project](https://github.com/grails-samples/geb-example-grails) or [Grails functional test suite](https://github.com/grails/grails-functional-tests) where Geb tests are used extensively. +For further reference please see the [Geb documentation](https://www.gebish.org). + +## Usage + +To use the plugin, add the following dependencies to your `build.gradle`: +```groovy +dependencies { + implementation 'org.grails.plugins:geb' // This is only needed to use the create-functional-test command (see below) + integrationTestImplemntation testFixtures('org.grails.plugins:geb') // This is needed to compile and run the tests +} +``` + +To get started, you can use the `create-functional-test` command to generate a new Geb test: + +```console +./grailsw create-functional-test com.example.MyFunctionalSpec +``` + +This will create a new Geb test in the `src/integration-test/groovy/com/example` directory. + +There are two ways to use this plugin, either by extending your test classes with the `ContainerGebSpec` class or with the `GebSpec` class. + +### ContainerGebSpec (recommended) + +By extending your test classes with the `ContainerGebSpec` class, you can run your tests in a containerized browser using [Testcontainers](https://java.testcontainers.org/). +This requires a [compatible container runtime](https://java.testcontainers.org/supported_docker_environment/) to be installed, such as: - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - [OrbStack](https://orbstack.dev/) - macOS only @@ -17,23 +45,21 @@ runs the browser in a container using [Testcontainers](https://java.testcontaine - [podman desktop](https://podman-desktop.io/) - [Colima](https://github.com/abiosoft/colima) - macOS and Linux -For further reference please see the [Geb documentation](https://www.gebish.org). - -## Examples - -If you are looking for examples on how to write Geb tests, check: +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. -[Geb/Grails example project](https://github.com/grails-samples/geb-example-grails) or [Grails functional test suite](https://github.com/grails/grails-functional-tests) where Geb tests are used extensively. +### GebSpec -## Additional Drivers +If you choose to use the `GebSpec` class, you will need to have a browser driver installed that matches a browser you have installed on your system. +This plugin comes with the `selenium-chrome-driver` pre-installed, but you can also set up additional drivers. -Grails comes with a set of pre-installed browser drivers. -To set up additional drivers you need to add the driver to your `build.gradle` for example: +To set up additional drivers, you need to add the driver to your `build.gradle` for example: ```groovy -integrationTestRuntimeOnly "org.seleniumhq.selenium:selenium-edge-driver:$seleniumVersion" +integrationTestRuntimeOnly "org.seleniumhq.selenium:selenium-firefox-driver" +integrationTestRuntimeOnly "org.seleniumhq.selenium:selenium-edge-driver" ``` -You also need to add it to the `GebConfig.groovy` file in the `src/integration-test/resources/` directory. For example: +You also need to add a `GebConfig.groovy` file in the `src/integration-test/resources/` directory. For example: ```groovy /* This is the Geb configuration file. @@ -43,18 +69,31 @@ You also need to add it to the `GebConfig.groovy` file in the `src/integration-t /* ... */ 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 when running your tests via Gradle + +```groovy +// build.gradle +tasks.withType(Test) { + useJUnitPlatform() + systemProperty 'geb.env', System.getProperty('geb.env') } ``` -Now you can run your tests with the new driver by specifying the Geb environment: +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: ```console ./gradlew integrationTest -Dgeb.env=edge ```