ifndef::snippets-dir[]
:snippets-dir: ../../../../manual-snippets/src/test/groovy
:rb-snippets-dir: ../../../../manual-snippets/real-browser/src/test/groovy
:cm-snippets-dir: ../../../../../module/geb-core/src/main/groovy
:ct-snippets-dir: ../../../../../module/geb-core/src/test/groovy
endif::[]
[[reporting]]
= Reporting

Geb includes a simple reporting mechanism which can be used to snapshot the state of the browser at any point in time.

Reporters are implementations of the `{reporter-api}` interface.
Geb ships with three implementations that actually write reports: `{page-source-reporter-api}`, `{screenshot-reporter-api}` and `{frames-source-reporter-api}` as well as two ancillary implementations: `{composite-reporter-api}` and `{multi-window-reporter-api}`.

There are three bits of configuration that pertain to reporting: the <<reporter-configuration, reporter implementation>>, the <<reports-directory-configuration, reports directory>> and whether to
<<report-test-failures-configuration, only report test failures>> or not. If no reporter is explicitly defined, a {composite-reporter-link}[composite reporter] will be created from a `ScreenshotReporter` (takes a PNG screenshot) and `PageSourceReporter` (dumps the current
DOM state as HTML).

You take a report by calling the `{browser-report-method-api}` method on the browser object.

[source,groovy]
----
include::{snippets-dir}/reporting/ReportingSpec.groovy[tag=reporting,indent=0]
----

[WARNING]
====
The `report()` method will throw an exception if it is called and there is no configured `reportsDir`.
If you are going to use reporting you *must* specify a `reportsDir` via config.
====

Assuming that we configured a `reportsDir` of `reports/geb`, after running this script we will find two files in this directory:

* `google home page.html` - A HTML dump of the page source
* `google home page.png` - A screenshot of the browser as a PNG file (if the driver implementation supports this)

[NOTE]
====
To avoid issues with reserved characters in filenames, Geb replaces any character in the report name that is not an alphanumeric, a space or a hyphen with an underscore.
====

== Reporting on contents of frames

If you wish to <<reporter-configuration, configure the reporting>> to also write reports which contain the source content of page frames you can do so the following way:

[source,groovy]
----
include::{snippets-dir}/configuration/ReporterConfigSpec.groovy[tag=frames_source_reporter_config,indent=0]
----

== Reporting on multiple windows

By default, reports are only taken for the window which is set to be {browser-get-current-window-api-link}[the current browser window] at the time of taking a report.
It's also possible to take reports for each of the opened windows by <<reporter-configuration, configuring the reporting>> to use `{multi-window-reporter-api}`:

[source,groovy]
----
include::{snippets-dir}/configuration/ReporterConfigSpec.groovy[tag=multi_window_reporter_config,indent=0]
----

[[report-group]]
== The report group

The configuration mechanism allows you to specify the base `reportsDir` which is where reports are written to by default.
It is also possible to change the link:api/geb/Browser.html#reportGroup(java.lang.String)[report group] to a relative path inside this directory.

[source,groovy]
----
include::{snippets-dir}/reporting/ReportingSpec.groovy[tag=reporting_groups,indent=0]
----

We have now created the following files inside the `reportsDir`...

* `google/home page.html`
* `google/home page.png`
* `gebish/home page.html`
* `gebish/home page.png`

The browser will create the directory for the report group as needed.
By default, the report group is not set which means that reports are written to the base of the `reportsDir`.
To go back to this after setting a report group, simply call `reportGroup(null)`.

[NOTE]
====
It is common for test integrations to manage the report group for you, setting it to the name of the test class.
====

[[listening-to-reporting]]
== Listening to reporting

It is possible to register a listener on the reporter that gets notified when a report is taken.
This was added to make it possible to write something to stdout when a report is taken, which is how the
link:https://plugins.jenkins.io/junit-attachments/[Jenkins JUnit Attachments Plugin] makes it possible to associate arbitrary files to test execution.
Reporting listeners are of type `{reporting-listener-api}` can be specified as part of the config...

[source,groovy]
----
include::{snippets-dir}/reporting/ReportingListenerSpec.groovy[tag=config,indent=0]
----

== Cleaning

Geb does not automatically clean the reports dir for you. It does however provide a method that you can call to do this.

[source,groovy]
----
include::{snippets-dir}/reporting/ReportingSpec.groovy[tag=cleaning,indent=0]
----

The `{clean-report-group-dir-api}` method will remove whatever the reports group dir is set to at the time.
If it cannot do this it will throw an exception.

[NOTE]
====
The Spock, JUnit and TestNG test integrations *do* automatically clean the reports dir for you, see the <<testing-reporting, section in the testing chapter>> on these integrations.
====
