You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by as...@apache.org on 2026/05/28 23:13:25 UTC
(grails-website) branch asf-site-production updated: Updating apache/grails-website asf-site-production branch for GitHub Actions run:26607389826
This is an automated email from the ASF dual-hosted git repository.
asf-ci-deploy pushed a commit to branch asf-site-production
in repository https://gitbox.apache.org/repos/asf/grails-website.git
The following commit(s) were added to refs/heads/asf-site-production by this push:
new 5a454b16d02 Updating apache/grails-website asf-site-production branch for GitHub Actions run:26607389826
5a454b16d02 is described below
commit 5a454b16d02d03cdeec051b2ce33f21d6d199381
Author: jamesfredley <ja...@users.noreply.github.com>
AuthorDate: Thu May 28 23:13:18 2026 +0000
Updating apache/grails-website asf-site-production branch for GitHub Actions run:26607389826
---
foundation/minutes.xml | 2 +-
foundation/minutes/20210321-tab.html | 10 +-
foundation/minutes/20211217-tab.html | 10 +-
foundation/minutes/20220323-tab.html | 10 +-
foundation/minutes/20220711-tab.html | 10 +-
foundation/minutes/20221128-tab.html | 10 +-
foundation/minutes/index.html | 2 +-
guides/_redirects.json | 2 +-
.../8/guide/bootBuildImage.html | 5 +-
.../8/guide/compose.html | 5 +-
.../8/guide/createApp.html | 5 +-
.../8/guide/dockerOverview.html | 5 +-
.../8/guide/dockerfile.html | 5 +-
.../8/guide/envProfiles.html | 5 +-
.../8/guide/gettingStarted.html | 5 +-
.../grails-docker-bootbuildimage/8/guide/ghcr.html | 5 +-
.../8/guide/healthCheck.html | 5 +-
.../8/guide/helpWithGrails.html | 13 +-
.../8/guide/index.html | 151 +++++-
.../8/guide/jvmContainer.html | 5 +-
.../8/guide/nonRoot.html | 9 +-
.../8/guide/pages/download.html | 5 +-
.../8/guide/pages/howto.html | 5 +-
.../8/guide/pages/postgresWiring.html | 5 +-
.../8/guide/pages/requirements.html | 5 +-
.../8/guide/pages/runImage.html | 5 +-
.../8/guide/pages/whatYouWillBuild.html | 5 +-
.../8/guide/single.html | 151 +++++-
.../8/guide/testing.html | 295 +++++++++++
guides/grails-docker-bootbuildimage/8/index.html | 4 +-
.../8/guide/associationWidgets.html | 5 +-
.../8/guide/cleanCrud.html | 9 +-
.../8/guide/createApp.html | 5 +-
.../8/guide/customDefaultWrapper.html | 5 +-
.../8/guide/customTable.html | 7 +-
.../8/guide/customWidgets.html | 5 +-
.../8/guide/domainModel.html | 15 +-
.../8/guide/fAllAndFDisplay.html | 5 +-
.../8/guide/fTable.html | 5 +-
.../8/guide/gettingStarted.html | 5 +-
.../8/guide/helpWithGrails.html | 13 +-
.../8/guide/index.html | 367 ++++++++++++-
.../8/guide/pages/appWideTable.html | 7 +-
.../8/guide/pages/authorClass.html | 5 +-
.../8/guide/pages/bookClass.html | 5 +-
.../8/guide/pages/bookDescription.html | 5 +-
.../8/guide/pages/bookIsbn.html | 21 +-
.../8/guide/pages/booleanWidget.html | 5 +-
.../8/guide/pages/bootstrapData.html | 15 +-
.../8/guide/pages/dateWidget.html | 5 +-
.../8/guide/pages/defaultViews.html | 5 +-
.../8/guide/pages/download.html | 5 +-
.../8/guide/pages/fAllInCreate.html | 5 +-
.../8/guide/pages/fAllInEdit.html | 5 +-
.../8/guide/pages/fDisplayInShow.html | 5 +-
.../8/guide/pages/fTableForAuthors.html | 5 +-
.../8/guide/pages/fTableForBooks.html | 5 +-
.../8/guide/pages/fieldsPluginAlreadyIncluded.html | 5 +-
.../8/guide/pages/generateControllers.html | 5 +-
.../8/guide/pages/howto.html | 5 +-
.../8/guide/pages/manyToManyWidget.html | 5 +-
.../8/guide/pages/manyToOneWidget.html | 5 +-
.../8/guide/pages/oneToManyWidget.html | 5 +-
.../8/guide/pages/oneToOneWidget.html | 5 +-
.../8/guide/pages/perColumnCells.html | 5 +-
.../8/guide/pages/perDomainTable.html | 5 +-
.../8/guide/pages/requirements.html | 5 +-
.../8/guide/pages/stringWidget.html | 5 +-
.../8/guide/pages/whatYouWillBuild.html | 5 +-
.../8/guide/perPropertyOverrides.html | 21 +-
.../8/guide/scaffolding.html | 5 +-
.../8/guide/single.html | 367 ++++++++++++-
.../8/guide/templateLookup.html | 5 +-
.../8/guide/testing.html | 489 ++++++++++++++++++
.../8/index.html | 4 +-
.../8/guide/functionalTests.html | 60 +++
.../grails-github-actions-cicd/8/guide/index.html | 172 +++++++
.../8/guide/integrationTests.html | 47 ++
.../grails-github-actions-cicd/8/guide/single.html | 172 +++++++
.../8/guide/unitTests.html | 65 +++
guides/grails-htmx/8/guide/controller.html | 5 +-
guides/grails-htmx/8/guide/createApp.html | 5 +-
guides/grails-htmx/8/guide/csrf.html | 5 +-
guides/grails-htmx/8/guide/gettingStarted.html | 5 +-
guides/grails-htmx/8/guide/helpWithGrails.html | 13 +-
guides/grails-htmx/8/guide/index.html | 321 +++++++++++-
guides/grails-htmx/8/guide/indexPage.html | 7 +-
guides/grails-htmx/8/guide/inlineEdit.html | 9 +-
guides/grails-htmx/8/guide/layoutWithHtmx.html | 5 +-
guides/grails-htmx/8/guide/liveSearch.html | 5 +-
guides/grails-htmx/8/guide/pages/howto.html | 5 +-
guides/grails-htmx/8/guide/pages/requirements.html | 5 +-
.../8/guide/pages/whatYouWillBuild.html | 5 +-
guides/grails-htmx/8/guide/rowPartial.html | 11 +-
guides/grails-htmx/8/guide/single.html | 321 +++++++++++-
guides/grails-htmx/8/guide/spaComparison.html | 9 +-
guides/grails-htmx/8/guide/taskDomain.html | 5 +-
guides/grails-htmx/8/guide/testing.html | 442 ++++++++++++++++
guides/grails-htmx/8/guide/urlMappings.html | 19 +-
guides/grails-htmx/8/index.html | 4 +-
guides/grails-multi-module/8/guide/index.html | 279 ++++++++++
guides/grails-multi-module/8/guide/single.html | 279 ++++++++++
.../8/guide/testingPerModule.html | 279 ++++++++++
guides/grails-rest-library/8/guide/bulkCreate.html | 7 +-
.../grails-rest-library/8/guide/controllers.html | 7 +-
guides/grails-rest-library/8/guide/createApp.html | 7 +-
.../grails-rest-library/8/guide/domainModel.html | 13 +-
.../8/guide/gettingStarted.html | 7 +-
.../8/guide/helpWithGrails.html | 15 +-
guides/grails-rest-library/8/guide/index.html | 437 +++++++++++++++-
guides/grails-rest-library/8/guide/jsonViews.html | 7 +-
.../8/guide/pages/bootstrapData.html | 13 +-
.../8/guide/pages/download.html | 7 +-
.../grails-rest-library/8/guide/pages/howto.html | 7 +-
.../8/guide/pages/requirements.html | 7 +-
.../8/guide/pages/whatYouWillBuild.html | 7 +-
guides/grails-rest-library/8/guide/pagination.html | 7 +-
.../grails-rest-library/8/guide/runningTheApp.html | 19 +-
guides/grails-rest-library/8/guide/single.html | 437 +++++++++++++++-
guides/grails-rest-library/8/guide/testing.html | 566 +++++++++++++++++++++
.../grails-rest-library/8/guide/urlMappings.html | 7 +-
guides/grails-rest-library/8/guide/validation.html | 12 +-
guides/grails-rest-library/8/guide/versioning.html | 11 +-
guides/grails-rest-library/8/index.html | 6 +-
.../8/guide/controllerUnitTest.html | 8 +-
.../grails-spock-test-tour/8/guide/dataTest.html | 10 +-
.../8/guide/domainUnitTest.html | 27 +-
.../8/guide/functionalTest.html | 112 +++-
.../8/guide/gettingStarted.html | 2 +-
guides/grails-spock-test-tour/8/guide/index.html | 180 ++++++-
.../8/guide/integrationTest.html | 19 +-
.../8/guide/pages/whatYouWillBuild.html | 2 +-
.../grails-spock-test-tour/8/guide/platform.html | 2 +-
guides/grails-spock-test-tour/8/guide/single.html | 180 ++++++-
.../grails-tailwindcss/8/guide/componentLayer.html | 9 +-
.../8/guide/configureTailwind.html | 5 +-
guides/grails-tailwindcss/8/guide/createApp.html | 5 +-
guides/grails-tailwindcss/8/guide/darkMode.html | 5 +-
guides/grails-tailwindcss/8/guide/firstPaint.html | 5 +-
.../grails-tailwindcss/8/guide/gettingStarted.html | 5 +-
.../grails-tailwindcss/8/guide/gradleWiring.html | 5 +-
.../grails-tailwindcss/8/guide/helpWithGrails.html | 13 +-
guides/grails-tailwindcss/8/guide/index.html | 132 ++++-
.../8/guide/installTailwind.html | 5 +-
.../grails-tailwindcss/8/guide/pages/download.html | 5 +-
guides/grails-tailwindcss/8/guide/pages/howto.html | 5 +-
.../grails-tailwindcss/8/guide/pages/inputCss.html | 5 +-
.../8/guide/pages/requirements.html | 5 +-
.../8/guide/pages/whatYouWillBuild.html | 5 +-
guides/grails-tailwindcss/8/guide/single.html | 132 ++++-
guides/grails-tailwindcss/8/guide/testing.html | 267 ++++++++++
guides/grails-tailwindcss/8/index.html | 4 +-
guides/grails-vite-spa/8/guide/backend.html | 13 +-
guides/grails-vite-spa/8/guide/cors.html | 11 +-
guides/grails-vite-spa/8/guide/devMode.html | 7 +-
guides/grails-vite-spa/8/guide/frontend.html | 11 +-
guides/grails-vite-spa/8/guide/gettingStarted.html | 7 +-
guides/grails-vite-spa/8/guide/helpWithGrails.html | 15 +-
guides/grails-vite-spa/8/guide/index.html | 405 ++++++++++++++-
guides/grails-vite-spa/8/guide/layout.html | 7 +-
guides/grails-vite-spa/8/guide/pages/howto.html | 7 +-
.../8/guide/pages/requirements.html | 7 +-
.../8/guide/pages/whatYouWillBuild.html | 7 +-
guides/grails-vite-spa/8/guide/prodBuild.html | 7 +-
guides/grails-vite-spa/8/guide/single.html | 405 ++++++++++++++-
guides/grails-vite-spa/8/guide/spaController.html | 38 +-
guides/grails-vite-spa/8/guide/testing.html | 499 ++++++++++++++++++
guides/grails-vite-spa/8/guide/urlMappings.html | 21 +-
guides/grails-vite-spa/8/guide/viteConfig.html | 7 +-
guides/grails-vite-spa/8/index.html | 6 +-
rss.xml | 2 +-
171 files changed, 8633 insertions(+), 432 deletions(-)
diff --git a/foundation/minutes.xml b/foundation/minutes.xml
index 61484dcb2ee..afc08961e12 100644
--- a/foundation/minutes.xml
+++ b/foundation/minutes.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?><rss xmlns:content="http://purl.org/rss/1.0/modules/content/" version="2.0"><channel><title>Foundation | Grails Framework</title><link>https://grails.apache.org</link><description>A powerful Groovy-based web application framework for the JVM built on top of Spring Boot</description><pubDate>Thu, 28 May 2026 22:37:29 GMT</pubDate><item><title>Technology Advisory Board Meeting</title><link>https://grails.apache.org/foundation/minutes/20221128-tab.html< [...]
+<?xml version="1.0" encoding="UTF-8"?><rss xmlns:content="http://purl.org/rss/1.0/modules/content/" version="2.0"><channel><title>Foundation | Grails Framework</title><link>https://grails.apache.org</link><description>A powerful Groovy-based web application framework for the JVM built on top of Spring Boot</description><pubDate>Thu, 28 May 2026 23:04:15 GMT</pubDate><item><title>Technology Advisory Board Meeting</title><link>https://grails.apache.org/foundation/minutes/20221128-tab.html< [...]
<h3>Meeting Attendance:</h3>
<ul>
<li><strong>Puneet Behl</strong> - Grails Product Development Lead at Object Computing</li>
diff --git a/foundation/minutes/20210321-tab.html b/foundation/minutes/20210321-tab.html
index 5a63858f494..657d54e31de 100644
--- a/foundation/minutes/20210321-tab.html
+++ b/foundation/minutes/20210321-tab.html
@@ -213,17 +213,17 @@ community events</p>
<h3>2022</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@66a37bcf</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@13fd31d5</minutesLink>
<parseDate>Nov 28, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@79a7f78d</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@3f300370</minutesLink>
<parseDate>Jul 07, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@285d5eaa</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@1f3c7050</minutesLink>
<parseDate>Mar 23, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
@@ -231,12 +231,12 @@ community events</p>
<h3>2021</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@1587cd5f</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@63bae823</minutesLink>
<parseDate>Dec 17, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@2585821</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@7e1fe2d6</minutesLink>
<parseDate>Mar 21, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
diff --git a/foundation/minutes/20211217-tab.html b/foundation/minutes/20211217-tab.html
index bf4de8f2b52..b28aa83d660 100644
--- a/foundation/minutes/20211217-tab.html
+++ b/foundation/minutes/20211217-tab.html
@@ -255,17 +255,17 @@
<h3>2022</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@66a37bcf</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@13fd31d5</minutesLink>
<parseDate>Nov 28, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@79a7f78d</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@3f300370</minutesLink>
<parseDate>Jul 07, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@285d5eaa</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@1f3c7050</minutesLink>
<parseDate>Mar 23, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
@@ -273,12 +273,12 @@
<h3>2021</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@1587cd5f</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@63bae823</minutesLink>
<parseDate>Dec 17, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@2585821</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@7e1fe2d6</minutesLink>
<parseDate>Mar 21, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
diff --git a/foundation/minutes/20220323-tab.html b/foundation/minutes/20220323-tab.html
index 8598ab6cd21..1bde4dbcc31 100644
--- a/foundation/minutes/20220323-tab.html
+++ b/foundation/minutes/20220323-tab.html
@@ -298,17 +298,17 @@
<h3>2022</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@66a37bcf</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@13fd31d5</minutesLink>
<parseDate>Nov 28, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@79a7f78d</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@3f300370</minutesLink>
<parseDate>Jul 07, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@285d5eaa</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@1f3c7050</minutesLink>
<parseDate>Mar 23, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
@@ -316,12 +316,12 @@
<h3>2021</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@1587cd5f</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@63bae823</minutesLink>
<parseDate>Dec 17, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@2585821</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@7e1fe2d6</minutesLink>
<parseDate>Mar 21, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
diff --git a/foundation/minutes/20220711-tab.html b/foundation/minutes/20220711-tab.html
index da34904db8b..5f89888376a 100644
--- a/foundation/minutes/20220711-tab.html
+++ b/foundation/minutes/20220711-tab.html
@@ -206,17 +206,17 @@
<h3>2022</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@66a37bcf</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@13fd31d5</minutesLink>
<parseDate>Nov 28, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@79a7f78d</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@3f300370</minutesLink>
<parseDate>Jul 07, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@285d5eaa</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@1f3c7050</minutesLink>
<parseDate>Mar 23, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
@@ -224,12 +224,12 @@
<h3>2021</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@1587cd5f</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@63bae823</minutesLink>
<parseDate>Dec 17, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@2585821</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@7e1fe2d6</minutesLink>
<parseDate>Mar 21, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
diff --git a/foundation/minutes/20221128-tab.html b/foundation/minutes/20221128-tab.html
index 5073628a75b..5c945339c5d 100644
--- a/foundation/minutes/20221128-tab.html
+++ b/foundation/minutes/20221128-tab.html
@@ -245,17 +245,17 @@
<h3>2022</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@66a37bcf</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@13fd31d5</minutesLink>
<parseDate>Nov 28, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@79a7f78d</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@3f300370</minutesLink>
<parseDate>Jul 07, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@285d5eaa</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@1f3c7050</minutesLink>
<parseDate>Mar 23, 2022</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
@@ -263,12 +263,12 @@
<h3>2021</h3>
<ul>
<li>
- <minutesLink>website.model.HtmlMinutes@1587cd5f</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@63bae823</minutesLink>
<parseDate>Dec 17, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
<li>
- <minutesLink>website.model.HtmlMinutes@2585821</minutesLink>
+ <minutesLink>website.model.HtmlMinutes@7e1fe2d6</minutesLink>
<parseDate>Mar 21, 2021</parseDate>
<a href='minutesLink'>MMM dd - Technology Advisory Board Meeting</a>
</li>
diff --git a/foundation/minutes/index.html b/foundation/minutes/index.html
index d9543097371..bb7502a113f 100644
--- a/foundation/minutes/index.html
+++ b/foundation/minutes/index.html
@@ -100,7 +100,7 @@
</div>
</header>
-<article><div class='header-bar chalices-bg'><div class='content'><h1><a href='https://grails.apache.org/foundation/index.html'>Foundation</a></h1></div></div><div class='clear content container'><h3 class='column-header'>Meeting Minutes Archive</h3><div class='light'><div class='padded' style='padding-top: 0;'><div class="three-columns"><div class='column'><article class='blog-card' style='margin-bottom: 0; background-image: url(https://grails.apache.org/images/grails-blog-index-6.png)' [...]
+<article><div class='header-bar chalices-bg'><div class='content'><h1><a href='https://grails.apache.org/foundation/index.html'>Foundation</a></h1></div></div><div class='clear content container'><h3 class='column-header'>Meeting Minutes Archive</h3><div class='light'><div class='padded' style='padding-top: 0;'><div class="three-columns"><div class='column'><article class='blog-card' style='margin-bottom: 0; background-image: url(https://grails.apache.org/images/grails-blog-index-6.png)' [...]
<footer>
<div class='content'>
<div class='apache-grails'>
diff --git a/guides/_redirects.json b/guides/_redirects.json
index 17637f51ba6..e775a7af719 100644
--- a/guides/_redirects.json
+++ b/guides/_redirects.json
@@ -1,6 +1,6 @@
{
"version": 1,
- "generated": "2026-05-28T22:38:38.177069976Z",
+ "generated": "2026-05-28T23:06:11.789127914Z",
"from_base": "https://guides.grails.org",
"to_base": "https://grails.apache.org/guides",
"count": 1767,
diff --git a/guides/grails-docker-bootbuildimage/8/guide/bootBuildImage.html b/guides/grails-docker-bootbuildimage/8/guide/bootBuildImage.html
index 6fc62e47560..b3a7f437ea9 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/bootBuildImage.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/bootBuildImage.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/compose.html b/guides/grails-docker-bootbuildimage/8/guide/compose.html
index 525481bfa18..8576783a82a 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/compose.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/compose.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/createApp.html b/guides/grails-docker-bootbuildimage/8/guide/createApp.html
index 53640aa4c05..4af0741ce52 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/createApp.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/createApp.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/dockerOverview.html b/guides/grails-docker-bootbuildimage/8/guide/dockerOverview.html
index 6ce867d0046..28c55b0e1ae 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/dockerOverview.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/dockerOverview.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/dockerfile.html b/guides/grails-docker-bootbuildimage/8/guide/dockerfile.html
index c9dfc6921ab..904483ee8ad 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/dockerfile.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/dockerfile.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/envProfiles.html b/guides/grails-docker-bootbuildimage/8/guide/envProfiles.html
index e0ea83ea04e..6f0b4ac4c65 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/envProfiles.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/envProfiles.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/gettingStarted.html b/guides/grails-docker-bootbuildimage/8/guide/gettingStarted.html
index d1db6902549..e8136a300b5 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/gettingStarted.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/gettingStarted.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/ghcr.html b/guides/grails-docker-bootbuildimage/8/guide/ghcr.html
index 0911f8b13b3..8510aa7969b 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/ghcr.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/ghcr.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/healthCheck.html b/guides/grails-docker-bootbuildimage/8/guide/healthCheck.html
index 2ebf5273654..dcce79dbbe0 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/healthCheck.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/healthCheck.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/helpWithGrails.html b/guides/grails-docker-bootbuildimage/8/guide/helpWithGrails.html
index b94fd27b382..e163844452a 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/helpWithGrails.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/helpWithGrails.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>12 Do you need help with Grails?</title>
+ <title>13 Do you need help with Grails?</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -81,7 +84,7 @@ function addJsClass() {
<div id="main" class="corner-all">
- <div class="toc-item prev-left"><a href="../guide/nonRoot.html"><< <strong>11</strong><span>Running as a Non-Root User</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>12</strong><span>Testing the Health Probes</span></a></div>
@@ -91,7 +94,7 @@ function addJsClass() {
-<h1 id="helpWithGrails">12 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-docker-bootbuildimage/v8/guide/helpWithGrails.adoc"'>
@@ -131,7 +134,7 @@ function addJsClass() {
<div style="clear:both;margin-top:15px;"></div>
- <div class="toc-item prev-left"><a href="../guide/nonRoot.html"><< <strong>11</strong><span>Running as a Non-Root User</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>12</strong><span>Testing the Health Probes</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/index.html b/guides/grails-docker-bootbuildimage/8/guide/index.html
index b24e8fe54ab..53f07bb7e7a 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/index.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/index.html
@@ -135,7 +135,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#nonRoot"><strong>11</strong><span>Running as a Non-Root User</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>12</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>12</strong><span>Testing the Health Probes</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -1103,7 +1105,152 @@ docker push ghcr.io/grails-guides/grails-docker-bootbuildimage:0.1</code></pre>
</div>
-<h1 id="helpWithGrails">12 Do you need help with Grails?</h1>
+<h1 id="testing">12 Testing the Health Probes</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-docker-bootbuildimage/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The deployment contract for this app is not a web page - it is the Actuator health surface that the Docker <code>HEALTHCHECK</code> and a Kubernetes readiness/liveness probe poll. A functional test pins exactly that contract, booting the app against a Testcontainers PostgreSQL database (the readiness probe checks the datasource, so a real database is required for it to report <code>UP</code>).</p>
+</div>
+<div class="sect1">
+<h2 id="_test_configuration">Test configuration</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Testcontainers artifacts are not in the Grails BOM, so they need an explicit <code>testcontainers-bom</code>. Because the app uses the database-migration plugin with an empty changelog, the test profile turns migration off and lets GORM create the schema directly:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/resources/application-test.yml</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">dataSource</span>:
+ <span class="key">url</span>: <span class="string"><span class="content">jdbc:tc:postgresql:12:///postgres</span></span>
+ <span class="key">driverClassName</span>: <span class="string"><span class="content">org.testcontainers.jdbc.ContainerDatabaseDriver</span></span>
+ <span class="key">dbCreate</span>: <span class="string"><span class="content">create-drop</span></span>
+<span class="key">grails</span>:
+ <span class="key">plugin</span>:
+ <span class="key">databasemigration</span>:
+ <span class="key">updateOnStart</span>: <span class="string"><span class="content">false</span></span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_health_probe_functional_spec">The health-probe functional spec</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/ActuatorHealthFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional tests for the Spring Boot Actuator health surface this guide
+ * configures - the same endpoints the Docker HEALTHCHECK and a Kubernetes
+ * readiness/liveness probe hit. @Integration boots the app against a
+ * Testcontainers PostgreSQL database, so the readiness probe (which checks
+ * the datasource) reports UP.
+ *
+ * No Geb here: the deployment contract is HTTP/JSON, not a browser page.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">ActuatorHealthFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> get(<span class="predefined-type">String</span> path) {
+ client.send(
+ HttpRequest.newBuilder(<span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>)).GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="comment">// Spring Boot's health JSON nests the status as {code, description}, so</span>
+ <span class="comment">// the live status string is json.status.code.</span>
+ <span class="directive">private</span> <span class="directive">static</span> <span class="predefined-type">String</span> statusCode(<span class="predefined-type">String</span> body) {
+ (<span class="keyword">new</span> JsonSlurper().parseText(body) <span class="keyword">as</span> <span class="predefined-type">Map</span>).status.code
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /actuator/health reports UP</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the liveness probe is exposed and UP</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health/liveness</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the readiness probe is exposed and UP against a real database</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health/readiness</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">operator-grade endpoints stay closed</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>: <span class="string"><span class="delimiter">'</span><span class="content">only health and info are on the public surface</span><span class="delimiter">'</span></span>
+ get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/env</span><span class="delimiter">'</span></span>).statusCode() == <span class="integer">404</span>
+ get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/metrics</span><span class="delimiter">'</span></span>).statusCode() == <span class="integer">404</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The assertions encode the operational contract from the <a href="#healthCheck">health-probe chapter</a>:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>/actuator/health</code>, <code>/actuator/health/liveness</code>, and <code>/actuator/health/readiness</code> all report <code>UP</code> (the status is nested as <code>status.code</code> in Spring Boot’s health JSON);</p>
+</li>
+<li>
+<p>the readiness probe reports <code>UP</code> only because a real database is reachable - this is why the spec runs against Testcontainers PostgreSQL rather than a mock;</p>
+</li>
+<li>
+<p>the operator-grade endpoints (<code>/actuator/env</code>, <code>/actuator/metrics</code>) stay closed (<code>404</code>), confirming the <code>exposure.include: health,info</code> restriction actually holds.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Run it:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew integrationTest # boots the app against Testcontainers PostgreSQL - Docker required</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This is the same <code>readiness</code> endpoint the Compose <code>HEALTHCHECK</code> polls, so a green functional run is direct evidence the container’s health check will pass once the image is built and run.</p>
+</div>
+</div>
+</div>
+
+
+<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-docker-bootbuildimage/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/jvmContainer.html b/guides/grails-docker-bootbuildimage/8/guide/jvmContainer.html
index 12d8ce459fe..7f53285740d 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/jvmContainer.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/jvmContainer.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/nonRoot.html b/guides/grails-docker-bootbuildimage/8/guide/nonRoot.html
index 2048c8d1a38..a461dd1ce05 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/nonRoot.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/nonRoot.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -85,7 +88,7 @@ function addJsClass() {
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span> >></a></div>
@@ -151,7 +154,7 @@ function addJsClass() {
<div class="toc-item prev-left"><a href="../guide/ghcr.html"><< <strong>10</strong><span>Pushing to GitHub Container Registry</span></a></div>
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span> >></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/pages/download.html b/guides/grails-docker-bootbuildimage/8/guide/pages/download.html
index 1fa9c780673..032ab94d6b5 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/pages/download.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/pages/download.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/pages/howto.html b/guides/grails-docker-bootbuildimage/8/guide/pages/howto.html
index 5ab65b73e07..5b32f76efd5 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/pages/howto.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/pages/howto.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/pages/postgresWiring.html b/guides/grails-docker-bootbuildimage/8/guide/pages/postgresWiring.html
index 5654c78e18c..8d62719b38f 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/pages/postgresWiring.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/pages/postgresWiring.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/pages/requirements.html b/guides/grails-docker-bootbuildimage/8/guide/pages/requirements.html
index f270fefcad0..f0d66c65732 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/pages/requirements.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/pages/requirements.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/pages/runImage.html b/guides/grails-docker-bootbuildimage/8/guide/pages/runImage.html
index b5945284b37..1f16488a1c9 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/pages/runImage.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/pages/runImage.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/pages/whatYouWillBuild.html b/guides/grails-docker-bootbuildimage/8/guide/pages/whatYouWillBuild.html
index 5931e0efdfc..dcc560a3d84 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/pages/whatYouWillBuild.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/pages/whatYouWillBuild.html
@@ -63,7 +63,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/single.html b/guides/grails-docker-bootbuildimage/8/guide/single.html
index b24e8fe54ab..53f07bb7e7a 100644
--- a/guides/grails-docker-bootbuildimage/8/guide/single.html
+++ b/guides/grails-docker-bootbuildimage/8/guide/single.html
@@ -135,7 +135,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#nonRoot"><strong>11</strong><span>Running as a Non-Root User</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>12</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>12</strong><span>Testing the Health Probes</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -1103,7 +1105,152 @@ docker push ghcr.io/grails-guides/grails-docker-bootbuildimage:0.1</code></pre>
</div>
-<h1 id="helpWithGrails">12 Do you need help with Grails?</h1>
+<h1 id="testing">12 Testing the Health Probes</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-docker-bootbuildimage/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The deployment contract for this app is not a web page - it is the Actuator health surface that the Docker <code>HEALTHCHECK</code> and a Kubernetes readiness/liveness probe poll. A functional test pins exactly that contract, booting the app against a Testcontainers PostgreSQL database (the readiness probe checks the datasource, so a real database is required for it to report <code>UP</code>).</p>
+</div>
+<div class="sect1">
+<h2 id="_test_configuration">Test configuration</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Testcontainers artifacts are not in the Grails BOM, so they need an explicit <code>testcontainers-bom</code>. Because the app uses the database-migration plugin with an empty changelog, the test profile turns migration off and lets GORM create the schema directly:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/resources/application-test.yml</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">dataSource</span>:
+ <span class="key">url</span>: <span class="string"><span class="content">jdbc:tc:postgresql:12:///postgres</span></span>
+ <span class="key">driverClassName</span>: <span class="string"><span class="content">org.testcontainers.jdbc.ContainerDatabaseDriver</span></span>
+ <span class="key">dbCreate</span>: <span class="string"><span class="content">create-drop</span></span>
+<span class="key">grails</span>:
+ <span class="key">plugin</span>:
+ <span class="key">databasemigration</span>:
+ <span class="key">updateOnStart</span>: <span class="string"><span class="content">false</span></span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_health_probe_functional_spec">The health-probe functional spec</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/ActuatorHealthFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional tests for the Spring Boot Actuator health surface this guide
+ * configures - the same endpoints the Docker HEALTHCHECK and a Kubernetes
+ * readiness/liveness probe hit. @Integration boots the app against a
+ * Testcontainers PostgreSQL database, so the readiness probe (which checks
+ * the datasource) reports UP.
+ *
+ * No Geb here: the deployment contract is HTTP/JSON, not a browser page.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">ActuatorHealthFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> get(<span class="predefined-type">String</span> path) {
+ client.send(
+ HttpRequest.newBuilder(<span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>)).GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="comment">// Spring Boot's health JSON nests the status as {code, description}, so</span>
+ <span class="comment">// the live status string is json.status.code.</span>
+ <span class="directive">private</span> <span class="directive">static</span> <span class="predefined-type">String</span> statusCode(<span class="predefined-type">String</span> body) {
+ (<span class="keyword">new</span> JsonSlurper().parseText(body) <span class="keyword">as</span> <span class="predefined-type">Map</span>).status.code
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /actuator/health reports UP</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the liveness probe is exposed and UP</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health/liveness</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the readiness probe is exposed and UP against a real database</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health/readiness</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">operator-grade endpoints stay closed</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>: <span class="string"><span class="delimiter">'</span><span class="content">only health and info are on the public surface</span><span class="delimiter">'</span></span>
+ get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/env</span><span class="delimiter">'</span></span>).statusCode() == <span class="integer">404</span>
+ get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/metrics</span><span class="delimiter">'</span></span>).statusCode() == <span class="integer">404</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The assertions encode the operational contract from the <a href="#healthCheck">health-probe chapter</a>:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>/actuator/health</code>, <code>/actuator/health/liveness</code>, and <code>/actuator/health/readiness</code> all report <code>UP</code> (the status is nested as <code>status.code</code> in Spring Boot’s health JSON);</p>
+</li>
+<li>
+<p>the readiness probe reports <code>UP</code> only because a real database is reachable - this is why the spec runs against Testcontainers PostgreSQL rather than a mock;</p>
+</li>
+<li>
+<p>the operator-grade endpoints (<code>/actuator/env</code>, <code>/actuator/metrics</code>) stay closed (<code>404</code>), confirming the <code>exposure.include: health,info</code> restriction actually holds.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Run it:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew integrationTest # boots the app against Testcontainers PostgreSQL - Docker required</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This is the same <code>readiness</code> endpoint the Compose <code>HEALTHCHECK</code> polls, so a green functional run is direct evidence the container’s health check will pass once the image is built and run.</p>
+</div>
+</div>
+</div>
+
+
+<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-docker-bootbuildimage/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-docker-bootbuildimage/8/guide/testing.html b/guides/grails-docker-bootbuildimage/8/guide/testing.html
new file mode 100644
index 00000000000..49b8ddcca43
--- /dev/null
+++ b/guides/grails-docker-bootbuildimage/8/guide/testing.html
@@ -0,0 +1,295 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+ <title>12 Testing the Health Probes</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
+ <link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
+ <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
+ <script type="text/javascript">
+function addJsClass() {
+ var classes = document.body.className.split(" ");
+ classes.push("js");
+ document.body.className = classes.join(" ");
+}
+ </script>
+</head>
+
+<body class="body" onload="addJsClass();">
+<div id="navigation">
+ <div class="navTitle">
+
+ Grails Framework Guide
+ </div>
+ <div class="navLinks">
+ <ul>
+ <li>
+ <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
+ <a href="../guide/index.html" class="button">Table of contents</a>
+
+ <div id="nav-summary-childs" style="display:none;">
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>1</strong><span>Getting Started</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/createApp.html"><strong>2</strong><span>Creating the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/dockerOverview.html"><strong>3</strong><span>Two Paths to a Container Image</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/bootBuildImage.html"><strong>4</strong><span>The Spring Boot bootBuildImage Task</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/dockerfile.html"><strong>5</strong><span>The Hand-Rolled Multi-Stage Dockerfile</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/envProfiles.html"><strong>6</strong><span>Environment-Driven application.yml</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/jvmContainer.html"><strong>7</strong><span>Container-Friendly JVM Flags</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/healthCheck.html"><strong>8</strong><span>Spring Boot Actuator Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/compose.html"><strong>9</strong><span>Orchestrating the Stack with Docker Compose</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/ghcr.html"><strong>10</strong><span>Pushing to GitHub Container Registry</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ </div>
+
+ </div>
+ </div>
+ </li>
+ </ul>
+ </div>
+
+
+</div>
+
+<table id="colset" border="0" cellpadding="0" cellspacing="0">
+ <tr>
+ <td id="col1">
+ <div id="main" class="corner-all">
+
+
+ <div class="toc-item prev-left"><a href="../guide/nonRoot.html"><< <strong>11</strong><span>Running as a Non-Root User</span></a></div>
+
+
+
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span> >></a></div>
+
+
+
+
+
+
+
+<h1 id="testing">12 Testing the Health Probes</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-docker-bootbuildimage/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The deployment contract for this app is not a web page - it is the Actuator health surface that the Docker <code>HEALTHCHECK</code> and a Kubernetes readiness/liveness probe poll. A functional test pins exactly that contract, booting the app against a Testcontainers PostgreSQL database (the readiness probe checks the datasource, so a real database is required for it to report <code>UP</code>).</p>
+</div>
+<div class="sect1">
+<h2 id="_test_configuration">Test configuration</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Testcontainers artifacts are not in the Grails BOM, so they need an explicit <code>testcontainers-bom</code>. Because the app uses the database-migration plugin with an empty changelog, the test profile turns migration off and lets GORM create the schema directly:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/resources/application-test.yml</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">dataSource</span>:
+ <span class="key">url</span>: <span class="string"><span class="content">jdbc:tc:postgresql:12:///postgres</span></span>
+ <span class="key">driverClassName</span>: <span class="string"><span class="content">org.testcontainers.jdbc.ContainerDatabaseDriver</span></span>
+ <span class="key">dbCreate</span>: <span class="string"><span class="content">create-drop</span></span>
+<span class="key">grails</span>:
+ <span class="key">plugin</span>:
+ <span class="key">databasemigration</span>:
+ <span class="key">updateOnStart</span>: <span class="string"><span class="content">false</span></span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_health_probe_functional_spec">The health-probe functional spec</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/ActuatorHealthFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional tests for the Spring Boot Actuator health surface this guide
+ * configures - the same endpoints the Docker HEALTHCHECK and a Kubernetes
+ * readiness/liveness probe hit. @Integration boots the app against a
+ * Testcontainers PostgreSQL database, so the readiness probe (which checks
+ * the datasource) reports UP.
+ *
+ * No Geb here: the deployment contract is HTTP/JSON, not a browser page.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">ActuatorHealthFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> get(<span class="predefined-type">String</span> path) {
+ client.send(
+ HttpRequest.newBuilder(<span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>)).GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="comment">// Spring Boot's health JSON nests the status as {code, description}, so</span>
+ <span class="comment">// the live status string is json.status.code.</span>
+ <span class="directive">private</span> <span class="directive">static</span> <span class="predefined-type">String</span> statusCode(<span class="predefined-type">String</span> body) {
+ (<span class="keyword">new</span> JsonSlurper().parseText(body) <span class="keyword">as</span> <span class="predefined-type">Map</span>).status.code
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /actuator/health reports UP</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the liveness probe is exposed and UP</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health/liveness</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the readiness probe is exposed and UP against a real database</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/health/readiness</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ statusCode(resp.body()) == <span class="string"><span class="delimiter">'</span><span class="content">UP</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">operator-grade endpoints stay closed</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>: <span class="string"><span class="delimiter">'</span><span class="content">only health and info are on the public surface</span><span class="delimiter">'</span></span>
+ get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/env</span><span class="delimiter">'</span></span>).statusCode() == <span class="integer">404</span>
+ get(<span class="string"><span class="delimiter">'</span><span class="content">/actuator/metrics</span><span class="delimiter">'</span></span>).statusCode() == <span class="integer">404</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The assertions encode the operational contract from the <a href="#healthCheck">health-probe chapter</a>:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>/actuator/health</code>, <code>/actuator/health/liveness</code>, and <code>/actuator/health/readiness</code> all report <code>UP</code> (the status is nested as <code>status.code</code> in Spring Boot’s health JSON);</p>
+</li>
+<li>
+<p>the readiness probe reports <code>UP</code> only because a real database is reachable - this is why the spec runs against Testcontainers PostgreSQL rather than a mock;</p>
+</li>
+<li>
+<p>the operator-grade endpoints (<code>/actuator/env</code>, <code>/actuator/metrics</code>) stay closed (<code>404</code>), confirming the <code>exposure.include: health,info</code> restriction actually holds.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Run it:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew integrationTest # boots the app against Testcontainers PostgreSQL - Docker required</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This is the same <code>readiness</code> endpoint the Compose <code>HEALTHCHECK</code> polls, so a green functional run is direct evidence the container’s health check will pass once the image is built and run.</p>
+</div>
+</div>
+</div>
+
+
+ <div style="clear:both;margin-top:15px;"></div>
+
+ <div class="toc-item prev-left"><a href="../guide/nonRoot.html"><< <strong>11</strong><span>Running as a Non-Root User</span></a></div>
+
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span> >></a></div>
+
+ <div style="clear:both"></div>
+ </div>
+ </td>
+ <td id="col2">
+ <div class="local clearfix">
+ <div class="local-title" style="text-align: right"><a href="https://travis-ci.org/grails-guides/grails-docker-bootbuildimage"><img src="https://travis-ci.org/grails-guides/grails-docker-bootbuildimage.svg?branch=master" /></a></div>
+ <div class="local-title">
+ <a href="https://github.com/grails-guides/grails-docker-bootbuildimage">
+ <svg height="35" class="octicon octicon-mark-github" viewBox="0 0 16 16" version="1.1" width="35" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.8 [...]
+ </div>
+ <div class="menu">
+ <div class="input-group">
+ <button href="#" onclick="document.getElementById('github-url').value='git@github.com:grails-guides/grails-docker-bootbuildimage.git'" class="codeButton">SSH</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-docker-bootbuildimage.git'" class="codeButton">HTTPS</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-docker-bootbuildimage'" class="codeButton">Subversion</button>
+ </div>
+
+ <div class="input-group">
+ <!-- Target -->
+ <input id="github-url" value="git@github.com:grails-guides/grails-docker-bootbuildimage.git" type="text" />
+
+ <!-- Trigger -->
+ <button class="clipbtn" type="button" data-clipboard-target="#github-url">
+
+ <img width="13" src="../img/clippy.svg" alt="Copy to clipboard">
+ </button>
+
+ </div>
+ <div class="input-group">
+ <a href="https://github.com/grails-guides/grails-docker-bootbuildimage/archive/master.zip" class="downloadButton">Download ZIP</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ </tr>
+</table>
+
+<div id="footer">
+
+
+</div>
+
+<script type="text/javascript" src="../js/docs.js"></script>
+
+</body>
+</html>
diff --git a/guides/grails-docker-bootbuildimage/8/index.html b/guides/grails-docker-bootbuildimage/8/index.html
index cb4e67f44c1..ecdab77a67e 100644
--- a/guides/grails-docker-bootbuildimage/8/index.html
+++ b/guides/grails-docker-bootbuildimage/8/index.html
@@ -135,7 +135,9 @@
<div class="toc-item" style="margin-left:0px"><a href="./guide/nonRoot.html"><strong>11</strong><span>Running as a Non-Root User</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/testing.html"><strong>12</strong><span>Testing the Health Probes</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/associationWidgets.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/associationWidgets.html
index 8fc7381e9b8..b707d3c9052 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/associationWidgets.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/associationWidgets.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/cleanCrud.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/cleanCrud.html
index 78899fcd5ab..4e038751eb9 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/cleanCrud.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/cleanCrud.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -91,7 +94,7 @@ function addJsClass() {
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span> >></a></div>
@@ -213,7 +216,7 @@ function addJsClass() {
<div class="toc-item prev-left"><a href="../guide/customTable.html"><< <strong>12</strong><span>Customising the Table Template</span></a></div>
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span> >></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/createApp.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/createApp.html
index b6caa0f40e5..1cdcd199313 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/createApp.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/createApp.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customDefaultWrapper.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customDefaultWrapper.html
index a0d3c9b40c8..37c8286dfb8 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customDefaultWrapper.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customDefaultWrapper.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customTable.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customTable.html
index 45038ce1fae..d634bad0949 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customTable.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customTable.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -178,7 +181,7 @@ Unlike the form templates (<code><f:field></code>, <code><f:all></co
<span class="tag"><tr></span>
<span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainProperties}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">prop</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span><span class="tag">></span>
- <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></span><span cl [...]
+ <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.javaClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></spa [...]
<span class="tag"></th></span>
<span class="tag"></g:each></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">text-end</span><span class="delimiter">"</span></span><span class="tag">></span>Actions<span class="tag"></th></span>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customWidgets.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customWidgets.html
index d06046333dd..2c5e04ef9f6 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customWidgets.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/customWidgets.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/domainModel.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/domainModel.html
index 1fb056b120d..59eaddd201c 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/domainModel.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/domainModel.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -359,6 +362,12 @@ function addJsClass() {
<span class="type">class</span> <span class="class">BootStrap</span> {
<span class="keyword">def</span> init = { servletContext ->
+ <span class="comment">// Wrap the seed in a transaction so the writes - including the</span>
+ <span class="comment">// many-to-many Book<->Tag join rows - flush and commit together.</span>
+ <span class="comment">// A bare save() in BootStrap runs outside any transaction, and the</span>
+ <span class="comment">// join table is not reliably persisted; save(flush: true) without a</span>
+ <span class="comment">// transaction throws TransactionRequiredException.</span>
+ <span class="predefined-type">Book</span>.withTransaction {
Tag fantasy = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag classic = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag romance = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Romance</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
@@ -411,6 +420,7 @@ function addJsClass() {
<span class="key">author</span>: austen
)
pride.addToTags(romance).addToTags(classic).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
}
<span class="keyword">def</span> destroy = {}
@@ -418,6 +428,9 @@ function addJsClass() {
</div>
</div>
<div class="paragraph">
+<p>The seed runs inside a <code>Book.withTransaction { }</code> block. This matters for the <code>Book</code>-<code>Tag</code> many-to-many: a bare <code>save()</code> in <code>BootStrap</code> runs outside any transaction and the join-table rows are not reliably flushed, while <code>save(flush: true)</code> without a transaction throws <code>TransactionRequiredException</code>. Wrapping the whole seed in a transaction lets the books, authors, contact info, and the many-to-many join all [...]
+</div>
+<div class="paragraph">
<p>Restart the application with <code>./gradlew bootRun</code>. The H2 database is in-memory by default, so the seed data is recreated on every startup.</p>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fAllAndFDisplay.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fAllAndFDisplay.html
index 478d2ad276f..c5afca285c3 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fAllAndFDisplay.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fAllAndFDisplay.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fTable.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fTable.html
index d0e9b947bd1..77c54d70f4b 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fTable.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/fTable.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/gettingStarted.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/gettingStarted.html
index 5d205679f16..ac8761b17d8 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/gettingStarted.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/gettingStarted.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/helpWithGrails.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/helpWithGrails.html
index 854a9556238..5e70e7af940 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/helpWithGrails.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/helpWithGrails.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>14 Do you need help with Grails?</title>
+ <title>15 Do you need help with Grails?</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -87,7 +90,7 @@ function addJsClass() {
<div id="main" class="corner-all">
- <div class="toc-item prev-left"><a href="../guide/cleanCrud.html"><< <strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>14</strong><span>Testing the Widgets and Wrappers</span></a></div>
@@ -97,7 +100,7 @@ function addJsClass() {
-<h1 id="helpWithGrails">14 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">15 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-fields-custom-widgets-and-wrappers/v8/guide/helpWithGrails.adoc"'>
@@ -137,7 +140,7 @@ function addJsClass() {
<div style="clear:both;margin-top:15px;"></div>
- <div class="toc-item prev-left"><a href="../guide/cleanCrud.html"><< <strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>14</strong><span>Testing the Widgets and Wrappers</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/index.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/index.html
index 9a67163345c..6d7b000c29d 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/index.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/index.html
@@ -181,7 +181,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#cleanCrud"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>14</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>15</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -653,6 +655,12 @@ cd grails-fields-custom-widgets-and-wrappers/complete
<span class="type">class</span> <span class="class">BootStrap</span> {
<span class="keyword">def</span> init = { servletContext ->
+ <span class="comment">// Wrap the seed in a transaction so the writes - including the</span>
+ <span class="comment">// many-to-many Book<->Tag join rows - flush and commit together.</span>
+ <span class="comment">// A bare save() in BootStrap runs outside any transaction, and the</span>
+ <span class="comment">// join table is not reliably persisted; save(flush: true) without a</span>
+ <span class="comment">// transaction throws TransactionRequiredException.</span>
+ <span class="predefined-type">Book</span>.withTransaction {
Tag fantasy = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag classic = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag romance = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Romance</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
@@ -705,6 +713,7 @@ cd grails-fields-custom-widgets-and-wrappers/complete
<span class="key">author</span>: austen
)
pride.addToTags(romance).addToTags(classic).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
}
<span class="keyword">def</span> destroy = {}
@@ -712,6 +721,9 @@ cd grails-fields-custom-widgets-and-wrappers/complete
</div>
</div>
<div class="paragraph">
+<p>The seed runs inside a <code>Book.withTransaction { }</code> block. This matters for the <code>Book</code>-<code>Tag</code> many-to-many: a bare <code>save()</code> in <code>BootStrap</code> runs outside any transaction and the join-table rows are not reliably flushed, while <code>save(flush: true)</code> without a transaction throws <code>TransactionRequiredException</code>. Wrapping the whole seed in a transaction lets the books, authors, contact info, and the many-to-many join all [...]
+</div>
+<div class="paragraph">
<p>Restart the application with <code>./gradlew bootRun</code>. The H2 database is in-memory by default, so the seed data is recreated on every startup.</p>
</div>
@@ -2021,7 +2033,7 @@ For very large candidate sets (hundreds of <code>Tag</code> rows), a checkbox gr
<pre class="CodeRay highlight"><code data-lang="html"><span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prefix}${property}</span><span class="delimiter">"</span></span>
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${value}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">${invalid ? 'form-control is-invalid' : 'form-control'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\d{10}|\d{13}|\d{3}-\d-\d{2}-\d{6}-\d)</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\\d{10}|\\d{13}|\\d{3}-\\d-\\d{2}-\\d{6}-\\d)</span><span class="delimiter">"</span></span>
<span class="attribute-name">maxlength</span>=<span class="string"><span class="delimiter">"</span><span class="content">20</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">ISBN-10 or ISBN-13</span><span class="delimiter">"</span></span>
<span class="attribute-name">required</span>=<span class="string"><span class="delimiter">"</span><span class="content">${required}</span><span class="delimiter">"</span></span><span class="tag">/></span>
@@ -2034,6 +2046,20 @@ For very large candidate sets (hundreds of <code>Tag</code> rows), a checkbox gr
<div class="paragraph">
<p>Note how the per-property widget can still reuse the wrapper from <code>_fields/default/_wrapper.gsp</code> by emitting just the input and the help line - the wrapper supplies the label, required marker, and validation feedback.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The backslashes in the <code>pattern</code> attribute are <strong>doubled</strong> (<code>\\d</code>, not <code>\d</code>). A GSP attribute value is compiled into a Groovy string, and <code>\d</code> is not a valid Groovy escape sequence - it fails template compilation with <code>Unexpected character</code>. Writing <code>\\d</code> in the GSP emits a literal <code>\d</code> into the rendered HTML, which is what the browser’s <code>pattern</code> attribute needs. The server-side [...]
+</div>
+</td>
+</tr>
+</table>
+</div>
<h2 id="bookDescription">11.2 Per-Property Wrapper for Description</h2>
@@ -2172,7 +2198,7 @@ Unlike the form templates (<code><f:field></code>, <code><f:all></co
<span class="tag"><tr></span>
<span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainProperties}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">prop</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span><span class="tag">></span>
- <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></span><span cl [...]
+ <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.javaClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></spa [...]
<span class="tag"></th></span>
<span class="tag"></g:each></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">text-end</span><span class="delimiter">"</span></span><span class="tag">></span>Actions<span class="tag"></th></span>
@@ -2454,7 +2480,340 @@ Unlike the form templates (<code><f:field></code>, <code><f:all></co
</div>
-<h1 id="helpWithGrails">14 Do you need help with Grails?</h1>
+<h1 id="testing">14 Testing the Widgets and Wrappers</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-fields-custom-widgets-and-wrappers/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>Custom widgets and wrappers render fine "on my machine" right up until a GSP attribute or a template-lookup assumption breaks them silently. The sample app is covered at three layers: domain unit tests, <code>@Integration</code> tests for the associations, and Geb browser tests that prove the custom widgets actually render in a real page.</p>
+</div>
+<div class="sect1">
+<h2 id="_unit_the_domain_constraints">Unit: the domain constraints</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DataTest</code> mocks the associated domains so <code>belongsTo</code>/<code>hasMany</code> are satisfied without a Spring context:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Book. DataTest mocks the associated
+ * domains so belongsTo/hasMany are satisfied without a Spring context.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>, Tag] }
+
+ <span class="directive">private</span> <span class="predefined-type">Book</span> bookWith(<span class="predefined-type">Map</span> overrides = [:]) {
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">A</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">a@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</ [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">T</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span class="string"><span class="delimiter">'</span> [...]
+ <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">9.99</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>, <span class="key">author</span>: a] + overrides)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a fully populated book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith().validate()
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title and description are required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">title</span>: <span class="predefined-constant">null</span>, <span class="key">description</span>: <span class="predefined-constant">null</span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">description</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn '#isbn' isValid=#isValid</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith(<span class="key">isbn</span>: isbn).validate() == isValid
+
+ <span class="key">where</span>:
+ isbn || isValid
+ <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span> || <span class="predefined-constant">true</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">0547928227</span><span class="delimiter">'</span></span> || <span class="predefined-constant">true</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">abc</span><span class="delimiter">'</span></span> || <span class="predefined-constant">false</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">123</span><span class="delimiter">'</span></span> || <span class="predefined-constant">false</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">genre must be in the allowed list</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">genre</span>: <span class="string"><span class="delimiter">'</span><span class="content">Cooking</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">genre</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">not.inList</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">priceUSD cannot be negative</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">priceUSD</span>: -<span class="float">1.00</span>G)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">priceUSD</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">min.notmet</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/AuthorSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Author, including the email/url
+ * constraints and the hasOne ContactInfo / hasMany Book associations.
+ */</span>
+<span class="type">class</span> <span class="class">AuthorSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>, Tag, ContactInfo] }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid author validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Tolkien</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">jrr@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</spa [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">email must be well formed</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">X</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-email</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</s [...]
+
+ <span class="key">then</span>:
+ !a.validate()
+ a.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">email</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">email.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">website must be a valid url when present</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">X</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">x@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</ [...]
+
+ <span class="key">then</span>:
+ !a.validate()
+ a.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">website</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">url.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author owns many books</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Tolkien</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">jrr@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="conten [...]
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span class="string"><span class [...]
+ <span class="key">description</span>: <span class="string"><span class="delimiter">'</span><span class="content">d</span><span class="delimiter">'</span></span>, <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">9.99</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>))
+ a.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Author.get(a.id).books.size() == <span class="integer">1</span>
+ <span class="comment">// the hasOne ContactInfo association is exercised in LibraryIntegrationSpec,</span>
+ <span class="comment">// where a real datastore sets the inverse side that DataTest's in-memory</span>
+ <span class="comment">// store does not.</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_the_associations_against_a_real_database">Integration: the associations against a real database</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Integration</code> + <code>@Rollback</code> boots the full context against the in-memory H2 database and asserts on the <code>BootStrap</code> seed - including the <code>Book</code>-<code>Tag</code> many-to-many and the <code>Author</code>-<code>ContactInfo</code> one-to-one:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/LibraryIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full context against the in-memory H2 database.
+ * @Rollback isolates each method. BootStrap seeds two authors and two books
+ * at startup, so these specs assert on that committed seed data and create
+ * their own rows with distinct values.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">LibraryIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">BootStrap seeded the library</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">Pride and Prejudice</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a book belongs to an author and has many tags</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Book</span> hobbit = <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+
+ <span class="key">expect</span>:
+ hobbit.author.name == <span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>
+ hobbit.tags*.name.sort() == [<span class="string"><span class="delimiter">'</span><span class="content">Adventure</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author has a one-to-one contactInfo</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author tolkien = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+
+ <span class="key">expect</span>:
+ tolkien.contactInfo != <span class="predefined-constant">null</span>
+ tolkien.contactInfo.phone == <span class="string"><span class="delimiter">'</span><span class="content">+44 20 7946 0958</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a new book round-trips with its association</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">Jane Austen</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Emma</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780141439587</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span [...]
+ <span class="key">description</span>: <span class="string"><span class="delimiter">'</span><span class="content">A young woman who fancies herself a matchmaker.</span><span class="delimiter">'</span></span>,
+ <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">8.50</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>, <span class="key">author</span>: a)
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ <span class="predefined-type">Book</span>.get(b.id).author.name == <span class="string"><span class="delimiter">'</span><span class="content">Jane Austen</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_browser_the_custom_widgets_through_geb">Browser: the custom widgets through Geb</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>ContainerGebSpec</code> starts a Selenium-Chrome container via Testcontainers and drives the booted app, so only a running Docker daemon is required. These specs are the ones that catch the GSP-level bugs custom widgets are prone to:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/LibraryFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Browser tests for the Fields-plugin UI, driven by Geb 8 against the real
+ * booted app. ContainerGebSpec starts a Selenium-Chrome container via
+ * Testcontainers, so only a running Docker daemon is required. BootStrap
+ * seeds the library at startup, so these read-only specs assert on it.
+ *
+ * The point is to prove the custom widgets and wrappers actually render -
+ * f:table on the index, f:display on the show page (custom isbn widget,
+ * description wrapper), and the custom association widgets on the create form.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">LibraryFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index renders the custom f:table with seeded rows</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/book/index</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ title == <span class="string"><span class="delimiter">'</span><span class="content">Books</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped thead.table-dark</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody tr</span><span class="delimiter">'</span></span>).size() >= <span class="integer">2</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Pride and Prejudice</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book show page renders the custom isbn widget and description wrapper</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">the seeded Hobbit id</span><span class="delimiter">'</span></span>
+ <span class="predefined-type">Long</span> id = <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">"</span><span class="content">/book/show/</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">f:display renders the value and the custom isbn display includes its formatted output</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">A reluctant hobbit</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book create form renders the custom widgets</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/book/create</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the custom isbn widget renders with its pattern and help text</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).@pattern.contains(<span class="string"><span class="delimiter">'</span><span class="char">\\</span><span class="content">d{13}</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">10 or 13 digits</span><span class="delimiter">'</span></span>)
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the manyToOne author widget renders as a select</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">select</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">author.id</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the manyToMany tags widget renders a checkbox per seeded tag</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimiter">'</span><span class="content">checkbox</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">tags</span><span class="delimiter">'</span></span>).size() [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the author show page renders the one-to-one contactInfo via its custom display</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Long</span> id = Author.withNewTransaction { Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">"</span><span class="content">/author/show/</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">f:display renders the hasOne ContactInfo through its toString()</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Contact for J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The assertions map directly to the customisations earlier in the guide:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>the index page renders the app-wide custom <code>f:table</code> with its dark header and the seeded rows;</p>
+</li>
+<li>
+<p>the show page renders the value through the custom display widgets;</p>
+</li>
+<li>
+<p>the create form renders the per-property ISBN widget (with its <code>pattern</code> and help text), the many-to-one author select, and one many-to-many checkbox per <code>Tag</code>;</p>
+</li>
+<li>
+<p>the author show page renders the one-to-one <code>ContactInfo</code> through its <code>toString()</code>.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>A browser test here is not gold-plating: the custom ISBN widget’s <code>pattern</code> attribute and the app-wide table’s <code>domainClass.javaClass.simpleName</code> lookup are both the kind of thing that compiles cleanly and only fails when the page is actually rendered in a request. The Geb layer exercises exactly that path.</p>
+</div>
+<div class="paragraph">
+<p>Run it all:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + Geb browser tests - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+<h1 id="helpWithGrails">15 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-fields-custom-widgets-and-wrappers/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/appWideTable.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/appWideTable.html
index 506c5c4e099..f0310c48bd3 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/appWideTable.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/appWideTable.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -122,7 +125,7 @@ function addJsClass() {
<span class="tag"><tr></span>
<span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainProperties}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">prop</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span><span class="tag">></span>
- <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></span><span cl [...]
+ <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.javaClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></spa [...]
<span class="tag"></th></span>
<span class="tag"></g:each></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">text-end</span><span class="delimiter">"</span></span><span class="tag">></span>Actions<span class="tag"></th></span>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/authorClass.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/authorClass.html
index 29d86febe03..8a01d92cafa 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/authorClass.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/authorClass.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookClass.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookClass.html
index 12a5aa1102a..f7ec7ea470b 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookClass.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookClass.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookDescription.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookDescription.html
index a67fd7569b4..2c86509d86e 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookDescription.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookDescription.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookIsbn.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookIsbn.html
index 2c884f29b18..75443731f84 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookIsbn.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bookIsbn.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -120,7 +123,7 @@ function addJsClass() {
<pre class="CodeRay highlight"><code data-lang="html"><span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prefix}${property}</span><span class="delimiter">"</span></span>
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${value}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">${invalid ? 'form-control is-invalid' : 'form-control'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\d{10}|\d{13}|\d{3}-\d-\d{2}-\d{6}-\d)</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\\d{10}|\\d{13}|\\d{3}-\\d-\\d{2}-\\d{6}-\\d)</span><span class="delimiter">"</span></span>
<span class="attribute-name">maxlength</span>=<span class="string"><span class="delimiter">"</span><span class="content">20</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">ISBN-10 or ISBN-13</span><span class="delimiter">"</span></span>
<span class="attribute-name">required</span>=<span class="string"><span class="delimiter">"</span><span class="content">${required}</span><span class="delimiter">"</span></span><span class="tag">/></span>
@@ -132,6 +135,20 @@ function addJsClass() {
</div>
<div class="paragraph">
<p>Note how the per-property widget can still reuse the wrapper from <code>_fields/default/_wrapper.gsp</code> by emitting just the input and the help line - the wrapper supplies the label, required marker, and validation feedback.</p>
+</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The backslashes in the <code>pattern</code> attribute are <strong>doubled</strong> (<code>\\d</code>, not <code>\d</code>). A GSP attribute value is compiled into a Groovy string, and <code>\d</code> is not a valid Groovy escape sequence - it fails template compilation with <code>Unexpected character</code>. Writing <code>\\d</code> in the GSP emits a literal <code>\d</code> into the rendered HTML, which is what the browser’s <code>pattern</code> attribute needs. The server-side [...]
+</div>
+</td>
+</tr>
+</table>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/booleanWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/booleanWidget.html
index 3d7d14c5bdd..eb7573c8492 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/booleanWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/booleanWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bootstrapData.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bootstrapData.html
index 5316438212b..c5e56a3c8f3 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bootstrapData.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/bootstrapData.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -119,6 +122,12 @@ function addJsClass() {
<span class="type">class</span> <span class="class">BootStrap</span> {
<span class="keyword">def</span> init = { servletContext ->
+ <span class="comment">// Wrap the seed in a transaction so the writes - including the</span>
+ <span class="comment">// many-to-many Book<->Tag join rows - flush and commit together.</span>
+ <span class="comment">// A bare save() in BootStrap runs outside any transaction, and the</span>
+ <span class="comment">// join table is not reliably persisted; save(flush: true) without a</span>
+ <span class="comment">// transaction throws TransactionRequiredException.</span>
+ <span class="predefined-type">Book</span>.withTransaction {
Tag fantasy = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag classic = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag romance = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Romance</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
@@ -171,6 +180,7 @@ function addJsClass() {
<span class="key">author</span>: austen
)
pride.addToTags(romance).addToTags(classic).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
}
<span class="keyword">def</span> destroy = {}
@@ -178,6 +188,9 @@ function addJsClass() {
</div>
</div>
<div class="paragraph">
+<p>The seed runs inside a <code>Book.withTransaction { }</code> block. This matters for the <code>Book</code>-<code>Tag</code> many-to-many: a bare <code>save()</code> in <code>BootStrap</code> runs outside any transaction and the join-table rows are not reliably flushed, while <code>save(flush: true)</code> without a transaction throws <code>TransactionRequiredException</code>. Wrapping the whole seed in a transaction lets the books, authors, contact info, and the many-to-many join all [...]
+</div>
+<div class="paragraph">
<p>Restart the application with <code>./gradlew bootRun</code>. The H2 database is in-memory by default, so the seed data is recreated on every startup.</p>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/dateWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/dateWidget.html
index 5ffc4034699..91cf23ccab6 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/dateWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/dateWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/defaultViews.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/defaultViews.html
index 690683c0774..84af7563d92 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/defaultViews.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/defaultViews.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/download.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/download.html
index 98e690e309f..73fcf9ea852 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/download.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/download.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInCreate.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInCreate.html
index 82909b99a76..b6a14784d84 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInCreate.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInCreate.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInEdit.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInEdit.html
index c40a1ef5add..beca6542574 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInEdit.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fAllInEdit.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fDisplayInShow.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fDisplayInShow.html
index 75b21c6c9de..ab1ee5f45a1 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fDisplayInShow.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fDisplayInShow.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForAuthors.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForAuthors.html
index ed6bb2266cc..10c3aacc363 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForAuthors.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForAuthors.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForBooks.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForBooks.html
index f57c84d2362..4d865764117 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForBooks.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fTableForBooks.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fieldsPluginAlreadyIncluded.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fieldsPluginAlreadyIncluded.html
index 76ef98cf6ea..19db277a22d 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fieldsPluginAlreadyIncluded.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/fieldsPluginAlreadyIncluded.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/generateControllers.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/generateControllers.html
index 7c762ca1d6f..b53a0bffd02 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/generateControllers.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/generateControllers.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/howto.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/howto.html
index 150f75d21df..f6019efcc90 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/howto.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/howto.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToManyWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToManyWidget.html
index eb725f78051..352c6cf1083 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToManyWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToManyWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToOneWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToOneWidget.html
index 5a4ed582fd0..e2ef28f318c 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToOneWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/manyToOneWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToManyWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToManyWidget.html
index a9e16eb4e37..46cfb31211d 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToManyWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToManyWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToOneWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToOneWidget.html
index bdd5d69aaed..3a08eb94e02 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToOneWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/oneToOneWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perColumnCells.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perColumnCells.html
index bd7a2c76e49..b2cce0b8e11 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perColumnCells.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perColumnCells.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perDomainTable.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perDomainTable.html
index 217fcbb509d..fca6378c2ce 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perDomainTable.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/perDomainTable.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/requirements.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/requirements.html
index fc3cc650c2d..9fc07ba0c5c 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/requirements.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/requirements.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/stringWidget.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/stringWidget.html
index 33ad10c27e0..2d43c690f81 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/stringWidget.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/stringWidget.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/whatYouWillBuild.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/whatYouWillBuild.html
index bfb297bcf4f..a625b63b946 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/whatYouWillBuild.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/pages/whatYouWillBuild.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/perPropertyOverrides.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/perPropertyOverrides.html
index 68bc0e393b8..4fd20e5e988 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/perPropertyOverrides.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/perPropertyOverrides.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -148,7 +151,7 @@ function addJsClass() {
<pre class="CodeRay highlight"><code data-lang="html"><span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prefix}${property}</span><span class="delimiter">"</span></span>
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${value}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">${invalid ? 'form-control is-invalid' : 'form-control'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\d{10}|\d{13}|\d{3}-\d-\d{2}-\d{6}-\d)</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\\d{10}|\\d{13}|\\d{3}-\\d-\\d{2}-\\d{6}-\\d)</span><span class="delimiter">"</span></span>
<span class="attribute-name">maxlength</span>=<span class="string"><span class="delimiter">"</span><span class="content">20</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">ISBN-10 or ISBN-13</span><span class="delimiter">"</span></span>
<span class="attribute-name">required</span>=<span class="string"><span class="delimiter">"</span><span class="content">${required}</span><span class="delimiter">"</span></span><span class="tag">/></span>
@@ -161,6 +164,20 @@ function addJsClass() {
<div class="paragraph">
<p>Note how the per-property widget can still reuse the wrapper from <code>_fields/default/_wrapper.gsp</code> by emitting just the input and the help line - the wrapper supplies the label, required marker, and validation feedback.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The backslashes in the <code>pattern</code> attribute are <strong>doubled</strong> (<code>\\d</code>, not <code>\d</code>). A GSP attribute value is compiled into a Groovy string, and <code>\d</code> is not a valid Groovy escape sequence - it fails template compilation with <code>Unexpected character</code>. Writing <code>\\d</code> in the GSP emits a literal <code>\d</code> into the rendered HTML, which is what the browser’s <code>pattern</code> attribute needs. The server-side [...]
+</div>
+</td>
+</tr>
+</table>
+</div>
<h2 id="bookDescription">11.2 Per-Property Wrapper for Description</h2>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/scaffolding.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/scaffolding.html
index b9c41405b81..ee6295de804 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/scaffolding.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/scaffolding.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/single.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/single.html
index 9a67163345c..6d7b000c29d 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/single.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/single.html
@@ -181,7 +181,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#cleanCrud"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>14</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>15</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -653,6 +655,12 @@ cd grails-fields-custom-widgets-and-wrappers/complete
<span class="type">class</span> <span class="class">BootStrap</span> {
<span class="keyword">def</span> init = { servletContext ->
+ <span class="comment">// Wrap the seed in a transaction so the writes - including the</span>
+ <span class="comment">// many-to-many Book<->Tag join rows - flush and commit together.</span>
+ <span class="comment">// A bare save() in BootStrap runs outside any transaction, and the</span>
+ <span class="comment">// join table is not reliably persisted; save(flush: true) without a</span>
+ <span class="comment">// transaction throws TransactionRequiredException.</span>
+ <span class="predefined-type">Book</span>.withTransaction {
Tag fantasy = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag classic = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
Tag romance = <span class="keyword">new</span> Tag(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Romance</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
@@ -705,6 +713,7 @@ cd grails-fields-custom-widgets-and-wrappers/complete
<span class="key">author</span>: austen
)
pride.addToTags(romance).addToTags(classic).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
}
<span class="keyword">def</span> destroy = {}
@@ -712,6 +721,9 @@ cd grails-fields-custom-widgets-and-wrappers/complete
</div>
</div>
<div class="paragraph">
+<p>The seed runs inside a <code>Book.withTransaction { }</code> block. This matters for the <code>Book</code>-<code>Tag</code> many-to-many: a bare <code>save()</code> in <code>BootStrap</code> runs outside any transaction and the join-table rows are not reliably flushed, while <code>save(flush: true)</code> without a transaction throws <code>TransactionRequiredException</code>. Wrapping the whole seed in a transaction lets the books, authors, contact info, and the many-to-many join all [...]
+</div>
+<div class="paragraph">
<p>Restart the application with <code>./gradlew bootRun</code>. The H2 database is in-memory by default, so the seed data is recreated on every startup.</p>
</div>
@@ -2021,7 +2033,7 @@ For very large candidate sets (hundreds of <code>Tag</code> rows), a checkbox gr
<pre class="CodeRay highlight"><code data-lang="html"><span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prefix}${property}</span><span class="delimiter">"</span></span>
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${value}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">${invalid ? 'form-control is-invalid' : 'form-control'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\d{10}|\d{13}|\d{3}-\d-\d{2}-\d{6}-\d)</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">"</span><span class="content">(?:\\d{10}|\\d{13}|\\d{3}-\\d-\\d{2}-\\d{6}-\\d)</span><span class="delimiter">"</span></span>
<span class="attribute-name">maxlength</span>=<span class="string"><span class="delimiter">"</span><span class="content">20</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">ISBN-10 or ISBN-13</span><span class="delimiter">"</span></span>
<span class="attribute-name">required</span>=<span class="string"><span class="delimiter">"</span><span class="content">${required}</span><span class="delimiter">"</span></span><span class="tag">/></span>
@@ -2034,6 +2046,20 @@ For very large candidate sets (hundreds of <code>Tag</code> rows), a checkbox gr
<div class="paragraph">
<p>Note how the per-property widget can still reuse the wrapper from <code>_fields/default/_wrapper.gsp</code> by emitting just the input and the help line - the wrapper supplies the label, required marker, and validation feedback.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The backslashes in the <code>pattern</code> attribute are <strong>doubled</strong> (<code>\\d</code>, not <code>\d</code>). A GSP attribute value is compiled into a Groovy string, and <code>\d</code> is not a valid Groovy escape sequence - it fails template compilation with <code>Unexpected character</code>. Writing <code>\\d</code> in the GSP emits a literal <code>\d</code> into the rendered HTML, which is what the browser’s <code>pattern</code> attribute needs. The server-side [...]
+</div>
+</td>
+</tr>
+</table>
+</div>
<h2 id="bookDescription">11.2 Per-Property Wrapper for Description</h2>
@@ -2172,7 +2198,7 @@ Unlike the form templates (<code><f:field></code>, <code><f:all></co
<span class="tag"><tr></span>
<span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainProperties}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">prop</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span><span class="tag">></span>
- <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></span><span cl [...]
+ <span class="tag"><g:message</span> <span class="attribute-name">code</span>=<span class="string"><span class="delimiter">"</span><span class="content">${domainClass.javaClass.simpleName.toLowerCase()}.${prop.name}.label</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">${prop.naturalName}</span><span class="delimiter">"</span></spa [...]
<span class="tag"></th></span>
<span class="tag"></g:each></span>
<span class="tag"><th</span> <span class="attribute-name">scope</span>=<span class="string"><span class="delimiter">"</span><span class="content">col</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">text-end</span><span class="delimiter">"</span></span><span class="tag">></span>Actions<span class="tag"></th></span>
@@ -2454,7 +2480,340 @@ Unlike the form templates (<code><f:field></code>, <code><f:all></co
</div>
-<h1 id="helpWithGrails">14 Do you need help with Grails?</h1>
+<h1 id="testing">14 Testing the Widgets and Wrappers</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-fields-custom-widgets-and-wrappers/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>Custom widgets and wrappers render fine "on my machine" right up until a GSP attribute or a template-lookup assumption breaks them silently. The sample app is covered at three layers: domain unit tests, <code>@Integration</code> tests for the associations, and Geb browser tests that prove the custom widgets actually render in a real page.</p>
+</div>
+<div class="sect1">
+<h2 id="_unit_the_domain_constraints">Unit: the domain constraints</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DataTest</code> mocks the associated domains so <code>belongsTo</code>/<code>hasMany</code> are satisfied without a Spring context:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Book. DataTest mocks the associated
+ * domains so belongsTo/hasMany are satisfied without a Spring context.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>, Tag] }
+
+ <span class="directive">private</span> <span class="predefined-type">Book</span> bookWith(<span class="predefined-type">Map</span> overrides = [:]) {
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">A</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">a@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</ [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">T</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span class="string"><span class="delimiter">'</span> [...]
+ <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">9.99</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>, <span class="key">author</span>: a] + overrides)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a fully populated book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith().validate()
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title and description are required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">title</span>: <span class="predefined-constant">null</span>, <span class="key">description</span>: <span class="predefined-constant">null</span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">description</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn '#isbn' isValid=#isValid</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith(<span class="key">isbn</span>: isbn).validate() == isValid
+
+ <span class="key">where</span>:
+ isbn || isValid
+ <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span> || <span class="predefined-constant">true</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">0547928227</span><span class="delimiter">'</span></span> || <span class="predefined-constant">true</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">abc</span><span class="delimiter">'</span></span> || <span class="predefined-constant">false</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">123</span><span class="delimiter">'</span></span> || <span class="predefined-constant">false</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">genre must be in the allowed list</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">genre</span>: <span class="string"><span class="delimiter">'</span><span class="content">Cooking</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">genre</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">not.inList</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">priceUSD cannot be negative</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">priceUSD</span>: -<span class="float">1.00</span>G)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">priceUSD</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">min.notmet</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/AuthorSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Author, including the email/url
+ * constraints and the hasOne ContactInfo / hasMany Book associations.
+ */</span>
+<span class="type">class</span> <span class="class">AuthorSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>, Tag, ContactInfo] }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid author validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Tolkien</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">jrr@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</spa [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">email must be well formed</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">X</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-email</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</s [...]
+
+ <span class="key">then</span>:
+ !a.validate()
+ a.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">email</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">email.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">website must be a valid url when present</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">X</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">x@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</ [...]
+
+ <span class="key">then</span>:
+ !a.validate()
+ a.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">website</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">url.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author owns many books</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Tolkien</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">jrr@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="conten [...]
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span class="string"><span class [...]
+ <span class="key">description</span>: <span class="string"><span class="delimiter">'</span><span class="content">d</span><span class="delimiter">'</span></span>, <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">9.99</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>))
+ a.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Author.get(a.id).books.size() == <span class="integer">1</span>
+ <span class="comment">// the hasOne ContactInfo association is exercised in LibraryIntegrationSpec,</span>
+ <span class="comment">// where a real datastore sets the inverse side that DataTest's in-memory</span>
+ <span class="comment">// store does not.</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_the_associations_against_a_real_database">Integration: the associations against a real database</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Integration</code> + <code>@Rollback</code> boots the full context against the in-memory H2 database and asserts on the <code>BootStrap</code> seed - including the <code>Book</code>-<code>Tag</code> many-to-many and the <code>Author</code>-<code>ContactInfo</code> one-to-one:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/LibraryIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full context against the in-memory H2 database.
+ * @Rollback isolates each method. BootStrap seeds two authors and two books
+ * at startup, so these specs assert on that committed seed data and create
+ * their own rows with distinct values.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">LibraryIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">BootStrap seeded the library</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">Pride and Prejudice</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a book belongs to an author and has many tags</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Book</span> hobbit = <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+
+ <span class="key">expect</span>:
+ hobbit.author.name == <span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>
+ hobbit.tags*.name.sort() == [<span class="string"><span class="delimiter">'</span><span class="content">Adventure</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author has a one-to-one contactInfo</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author tolkien = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+
+ <span class="key">expect</span>:
+ tolkien.contactInfo != <span class="predefined-constant">null</span>
+ tolkien.contactInfo.phone == <span class="string"><span class="delimiter">'</span><span class="content">+44 20 7946 0958</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a new book round-trips with its association</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">Jane Austen</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Emma</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780141439587</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span [...]
+ <span class="key">description</span>: <span class="string"><span class="delimiter">'</span><span class="content">A young woman who fancies herself a matchmaker.</span><span class="delimiter">'</span></span>,
+ <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">8.50</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>, <span class="key">author</span>: a)
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ <span class="predefined-type">Book</span>.get(b.id).author.name == <span class="string"><span class="delimiter">'</span><span class="content">Jane Austen</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_browser_the_custom_widgets_through_geb">Browser: the custom widgets through Geb</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>ContainerGebSpec</code> starts a Selenium-Chrome container via Testcontainers and drives the booted app, so only a running Docker daemon is required. These specs are the ones that catch the GSP-level bugs custom widgets are prone to:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/LibraryFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Browser tests for the Fields-plugin UI, driven by Geb 8 against the real
+ * booted app. ContainerGebSpec starts a Selenium-Chrome container via
+ * Testcontainers, so only a running Docker daemon is required. BootStrap
+ * seeds the library at startup, so these read-only specs assert on it.
+ *
+ * The point is to prove the custom widgets and wrappers actually render -
+ * f:table on the index, f:display on the show page (custom isbn widget,
+ * description wrapper), and the custom association widgets on the create form.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">LibraryFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index renders the custom f:table with seeded rows</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/book/index</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ title == <span class="string"><span class="delimiter">'</span><span class="content">Books</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped thead.table-dark</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody tr</span><span class="delimiter">'</span></span>).size() >= <span class="integer">2</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Pride and Prejudice</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book show page renders the custom isbn widget and description wrapper</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">the seeded Hobbit id</span><span class="delimiter">'</span></span>
+ <span class="predefined-type">Long</span> id = <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">"</span><span class="content">/book/show/</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">f:display renders the value and the custom isbn display includes its formatted output</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">A reluctant hobbit</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book create form renders the custom widgets</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/book/create</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the custom isbn widget renders with its pattern and help text</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).@pattern.contains(<span class="string"><span class="delimiter">'</span><span class="char">\\</span><span class="content">d{13}</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">10 or 13 digits</span><span class="delimiter">'</span></span>)
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the manyToOne author widget renders as a select</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">select</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">author.id</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the manyToMany tags widget renders a checkbox per seeded tag</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimiter">'</span><span class="content">checkbox</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">tags</span><span class="delimiter">'</span></span>).size() [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the author show page renders the one-to-one contactInfo via its custom display</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Long</span> id = Author.withNewTransaction { Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">"</span><span class="content">/author/show/</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">f:display renders the hasOne ContactInfo through its toString()</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Contact for J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The assertions map directly to the customisations earlier in the guide:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>the index page renders the app-wide custom <code>f:table</code> with its dark header and the seeded rows;</p>
+</li>
+<li>
+<p>the show page renders the value through the custom display widgets;</p>
+</li>
+<li>
+<p>the create form renders the per-property ISBN widget (with its <code>pattern</code> and help text), the many-to-one author select, and one many-to-many checkbox per <code>Tag</code>;</p>
+</li>
+<li>
+<p>the author show page renders the one-to-one <code>ContactInfo</code> through its <code>toString()</code>.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>A browser test here is not gold-plating: the custom ISBN widget’s <code>pattern</code> attribute and the app-wide table’s <code>domainClass.javaClass.simpleName</code> lookup are both the kind of thing that compiles cleanly and only fails when the page is actually rendered in a request. The Geb layer exercises exactly that path.</p>
+</div>
+<div class="paragraph">
+<p>Run it all:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + Geb browser tests - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+<h1 id="helpWithGrails">15 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-fields-custom-widgets-and-wrappers/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/templateLookup.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/templateLookup.html
index 154d8943d2b..53e6a01fc42 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/templateLookup.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/templateLookup.html
@@ -69,7 +69,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/guide/testing.html b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/testing.html
new file mode 100644
index 00000000000..e8321cb814d
--- /dev/null
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/guide/testing.html
@@ -0,0 +1,489 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+ <title>14 Testing the Widgets and Wrappers</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
+ <link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
+ <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
+ <script type="text/javascript">
+function addJsClass() {
+ var classes = document.body.className.split(" ");
+ classes.push("js");
+ document.body.className = classes.join(" ");
+}
+ </script>
+</head>
+
+<body class="body" onload="addJsClass();">
+<div id="navigation">
+ <div class="navTitle">
+
+ Grails Framework Guide
+ </div>
+ <div class="navLinks">
+ <ul>
+ <li>
+ <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
+ <a href="../guide/index.html" class="button">Table of contents</a>
+
+ <div id="nav-summary-childs" style="display:none;">
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>1</strong><span>Getting Started</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/createApp.html"><strong>2</strong><span>Creating the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/domainModel.html"><strong>3</strong><span>The Book and Author Domain Model</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/scaffolding.html"><strong>4</strong><span>Scaffolding the CRUD Controllers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/fAllAndFDisplay.html"><strong>5</strong><span>Replacing the GSPs with f:all and f:display</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/fTable.html"><strong>6</strong><span>Replacing list.gsp with f:table</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/templateLookup.html"><strong>7</strong><span>Template Lookup Precedence</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/customDefaultWrapper.html"><strong>8</strong><span>Customising the Default Wrapper</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/customWidgets.html"><strong>9</strong><span>Customising Widgets by Type</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/associationWidgets.html"><strong>10</strong><span>Customising Association Widgets</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/perPropertyOverrides.html"><strong>11</strong><span>Per-Property Overrides</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/customTable.html"><strong>12</strong><span>Customising the Table Template</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a>
+ </div>
+
+ </div>
+ </div>
+ </li>
+ </ul>
+ </div>
+
+
+</div>
+
+<table id="colset" border="0" cellpadding="0" cellspacing="0">
+ <tr>
+ <td id="col1">
+ <div id="main" class="corner-all">
+
+
+ <div class="toc-item prev-left"><a href="../guide/cleanCrud.html"><< <strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
+
+
+
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span> >></a></div>
+
+
+
+
+
+
+
+<h1 id="testing">14 Testing the Widgets and Wrappers</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-fields-custom-widgets-and-wrappers/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>Custom widgets and wrappers render fine "on my machine" right up until a GSP attribute or a template-lookup assumption breaks them silently. The sample app is covered at three layers: domain unit tests, <code>@Integration</code> tests for the associations, and Geb browser tests that prove the custom widgets actually render in a real page.</p>
+</div>
+<div class="sect1">
+<h2 id="_unit_the_domain_constraints">Unit: the domain constraints</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DataTest</code> mocks the associated domains so <code>belongsTo</code>/<code>hasMany</code> are satisfied without a Spring context:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Book. DataTest mocks the associated
+ * domains so belongsTo/hasMany are satisfied without a Spring context.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>, Tag] }
+
+ <span class="directive">private</span> <span class="predefined-type">Book</span> bookWith(<span class="predefined-type">Map</span> overrides = [:]) {
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">A</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">a@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</ [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">T</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span class="string"><span class="delimiter">'</span> [...]
+ <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">9.99</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>, <span class="key">author</span>: a] + overrides)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a fully populated book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith().validate()
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title and description are required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">title</span>: <span class="predefined-constant">null</span>, <span class="key">description</span>: <span class="predefined-constant">null</span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">description</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn '#isbn' isValid=#isValid</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith(<span class="key">isbn</span>: isbn).validate() == isValid
+
+ <span class="key">where</span>:
+ isbn || isValid
+ <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span> || <span class="predefined-constant">true</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">0547928227</span><span class="delimiter">'</span></span> || <span class="predefined-constant">true</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">abc</span><span class="delimiter">'</span></span> || <span class="predefined-constant">false</span>
+ <span class="string"><span class="delimiter">'</span><span class="content">123</span><span class="delimiter">'</span></span> || <span class="predefined-constant">false</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">genre must be in the allowed list</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">genre</span>: <span class="string"><span class="delimiter">'</span><span class="content">Cooking</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">genre</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">not.inList</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">priceUSD cannot be negative</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">priceUSD</span>: -<span class="float">1.00</span>G)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">priceUSD</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">min.notmet</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/AuthorSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Author, including the email/url
+ * constraints and the hasOne ContactInfo / hasMany Book associations.
+ */</span>
+<span class="type">class</span> <span class="class">AuthorSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>, Tag, ContactInfo] }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid author validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Tolkien</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">jrr@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</spa [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">email must be well formed</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">X</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-email</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</s [...]
+
+ <span class="key">then</span>:
+ !a.validate()
+ a.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">email</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">email.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">website must be a valid url when present</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">X</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">x@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="content">bio</ [...]
+
+ <span class="key">then</span>:
+ !a.validate()
+ a.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">website</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">url.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author owns many books</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Tolkien</span><span class="delimiter">'</span></span>, <span class="key">email</span>: <span class="string"><span class="delimiter">'</span><span class="content">jrr@example.com</span><span class="delimiter">'</span></span>, <span class="key">bio</span>: <span class="string"><span class="delimiter">'</span><span class="conten [...]
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span class="string"><span class [...]
+ <span class="key">description</span>: <span class="string"><span class="delimiter">'</span><span class="content">d</span><span class="delimiter">'</span></span>, <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">9.99</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>))
+ a.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Author.get(a.id).books.size() == <span class="integer">1</span>
+ <span class="comment">// the hasOne ContactInfo association is exercised in LibraryIntegrationSpec,</span>
+ <span class="comment">// where a real datastore sets the inverse side that DataTest's in-memory</span>
+ <span class="comment">// store does not.</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_the_associations_against_a_real_database">Integration: the associations against a real database</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Integration</code> + <code>@Rollback</code> boots the full context against the in-memory H2 database and asserts on the <code>BootStrap</code> seed - including the <code>Book</code>-<code>Tag</code> many-to-many and the <code>Author</code>-<code>ContactInfo</code> one-to-one:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/LibraryIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full context against the in-memory H2 database.
+ * @Rollback isolates each method. BootStrap seeds two authors and two books
+ * at startup, so these specs assert on that committed seed data and create
+ * their own rows with distinct values.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">LibraryIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">BootStrap seeded the library</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">Pride and Prejudice</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a book belongs to an author and has many tags</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Book</span> hobbit = <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+
+ <span class="key">expect</span>:
+ hobbit.author.name == <span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>
+ hobbit.tags*.name.sort() == [<span class="string"><span class="delimiter">'</span><span class="content">Adventure</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Classic</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Fantasy</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author has a one-to-one contactInfo</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author tolkien = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+
+ <span class="key">expect</span>:
+ tolkien.contactInfo != <span class="predefined-constant">null</span>
+ tolkien.contactInfo.phone == <span class="string"><span class="delimiter">'</span><span class="content">+44 20 7946 0958</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a new book round-trips with its association</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">Jane Austen</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Emma</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780141439587</span><span class="delimiter">'</span></span>, <span class="key">genre</span>: <span [...]
+ <span class="key">description</span>: <span class="string"><span class="delimiter">'</span><span class="content">A young woman who fancies herself a matchmaker.</span><span class="delimiter">'</span></span>,
+ <span class="key">publishedDate</span>: <span class="keyword">new</span> <span class="predefined-type">Date</span>(), <span class="key">priceUSD</span>: <span class="float">8.50</span>G, <span class="key">inStock</span>: <span class="predefined-constant">true</span>, <span class="key">author</span>: a)
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ <span class="predefined-type">Book</span>.get(b.id).author.name == <span class="string"><span class="delimiter">'</span><span class="content">Jane Austen</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_browser_the_custom_widgets_through_geb">Browser: the custom widgets through Geb</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>ContainerGebSpec</code> starts a Selenium-Chrome container via Testcontainers and drives the booted app, so only a running Docker daemon is required. These specs are the ones that catch the GSP-level bugs custom widgets are prone to:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/LibraryFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Browser tests for the Fields-plugin UI, driven by Geb 8 against the real
+ * booted app. ContainerGebSpec starts a Selenium-Chrome container via
+ * Testcontainers, so only a running Docker daemon is required. BootStrap
+ * seeds the library at startup, so these read-only specs assert on it.
+ *
+ * The point is to prove the custom widgets and wrappers actually render -
+ * f:table on the index, f:display on the show page (custom isbn widget,
+ * description wrapper), and the custom association widgets on the create form.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">LibraryFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index renders the custom f:table with seeded rows</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/book/index</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ title == <span class="string"><span class="delimiter">'</span><span class="content">Books</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped thead.table-dark</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody tr</span><span class="delimiter">'</span></span>).size() >= <span class="integer">2</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table.table-striped tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Pride and Prejudice</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book show page renders the custom isbn widget and description wrapper</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">the seeded Hobbit id</span><span class="delimiter">'</span></span>
+ <span class="predefined-type">Long</span> id = <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">"</span><span class="content">/book/show/</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">f:display renders the value and the custom isbn display includes its formatted output</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">A reluctant hobbit</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book create form renders the custom widgets</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/book/create</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the custom isbn widget renders with its pattern and help text</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).@pattern.contains(<span class="string"><span class="delimiter">'</span><span class="char">\\</span><span class="content">d{13}</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">10 or 13 digits</span><span class="delimiter">'</span></span>)
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the manyToOne author widget renders as a select</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">select</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">author.id</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the manyToMany tags widget renders a checkbox per seeded tag</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimiter">'</span><span class="content">checkbox</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">tags</span><span class="delimiter">'</span></span>).size() [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the author show page renders the one-to-one contactInfo via its custom display</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Long</span> id = Author.withNewTransaction { Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">"</span><span class="content">/author/show/</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">f:display renders the hasOne ContactInfo through its toString()</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">body</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Contact for J.R.R. Tolkien</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The assertions map directly to the customisations earlier in the guide:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>the index page renders the app-wide custom <code>f:table</code> with its dark header and the seeded rows;</p>
+</li>
+<li>
+<p>the show page renders the value through the custom display widgets;</p>
+</li>
+<li>
+<p>the create form renders the per-property ISBN widget (with its <code>pattern</code> and help text), the many-to-one author select, and one many-to-many checkbox per <code>Tag</code>;</p>
+</li>
+<li>
+<p>the author show page renders the one-to-one <code>ContactInfo</code> through its <code>toString()</code>.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>A browser test here is not gold-plating: the custom ISBN widget’s <code>pattern</code> attribute and the app-wide table’s <code>domainClass.javaClass.simpleName</code> lookup are both the kind of thing that compiles cleanly and only fails when the page is actually rendered in a request. The Geb layer exercises exactly that path.</p>
+</div>
+<div class="paragraph">
+<p>Run it all:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + Geb browser tests - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+ <div style="clear:both;margin-top:15px;"></div>
+
+ <div class="toc-item prev-left"><a href="../guide/cleanCrud.html"><< <strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
+
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span> >></a></div>
+
+ <div style="clear:both"></div>
+ </div>
+ </td>
+ <td id="col2">
+ <div class="local clearfix">
+ <div class="local-title" style="text-align: right"><a href="https://travis-ci.org/grails-guides/grails-fields-custom-widgets-and-wrappers"><img src="https://travis-ci.org/grails-guides/grails-fields-custom-widgets-and-wrappers.svg?branch=master" /></a></div>
+ <div class="local-title">
+ <a href="https://github.com/grails-guides/grails-fields-custom-widgets-and-wrappers">
+ <svg height="35" class="octicon octicon-mark-github" viewBox="0 0 16 16" version="1.1" width="35" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.8 [...]
+ </div>
+ <div class="menu">
+ <div class="input-group">
+ <button href="#" onclick="document.getElementById('github-url').value='git@github.com:grails-guides/grails-fields-custom-widgets-and-wrappers.git'" class="codeButton">SSH</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-fields-custom-widgets-and-wrappers.git'" class="codeButton">HTTPS</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-fields-custom-widgets-and-wrappers'" class="codeButton">Subversion</button>
+ </div>
+
+ <div class="input-group">
+ <!-- Target -->
+ <input id="github-url" value="git@github.com:grails-guides/grails-fields-custom-widgets-and-wrappers.git" type="text" />
+
+ <!-- Trigger -->
+ <button class="clipbtn" type="button" data-clipboard-target="#github-url">
+
+ <img width="13" src="../img/clippy.svg" alt="Copy to clipboard">
+ </button>
+
+ </div>
+ <div class="input-group">
+ <a href="https://github.com/grails-guides/grails-fields-custom-widgets-and-wrappers/archive/master.zip" class="downloadButton">Download ZIP</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ </tr>
+</table>
+
+<div id="footer">
+
+
+</div>
+
+<script type="text/javascript" src="../js/docs.js"></script>
+
+</body>
+</html>
diff --git a/guides/grails-fields-custom-widgets-and-wrappers/8/index.html b/guides/grails-fields-custom-widgets-and-wrappers/8/index.html
index 79df69ffc38..c4ed6e12fd8 100644
--- a/guides/grails-fields-custom-widgets-and-wrappers/8/index.html
+++ b/guides/grails-fields-custom-widgets-and-wrappers/8/index.html
@@ -181,7 +181,9 @@
<div class="toc-item" style="margin-left:0px"><a href="./guide/cleanCrud.html"><strong>13</strong><span>The Result - Clean CRUD GSPs</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/testing.html"><strong>14</strong><span>Testing the Widgets and Wrappers</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>15</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-github-actions-cicd/8/guide/functionalTests.html b/guides/grails-github-actions-cicd/8/guide/functionalTests.html
index c5ccfa53fdb..28a7b4c0074 100644
--- a/guides/grails-github-actions-cicd/8/guide/functionalTests.html
+++ b/guides/grails-github-actions-cicd/8/guide/functionalTests.html
@@ -135,6 +135,66 @@ function addJsClass() {
</div>
<div class="paragraph">
<p>No <code>apt-get install</code> of Chrome/Firefox is needed - the browser process lives inside the Selenium container Testcontainers pulls (<code>selenium/standalone-chrome</code> by default). The first cold run pulls the image (~200 MB) and is slower; subsequent runs reuse the cached layer. The legacy <code>geb-with-webdriver-binaries</code> forge feature is obsolete in Grails 8 and is not used here.</p>
+</div>
+<div class="sect1">
+<h2 id="_wiring_the_functionaltest_task">Wiring the functionalTest task</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>./gradlew functionalTest</code> is not a built-in Grails task. Grails gives you <code>test</code> (unit) and <code>integrationTest</code>; the functional stage is a second <code>Test</code> task over the same <code>integration-test</code> source set, filtered to the Geb specs. The <code>integrationTest</code> task is filtered the opposite way so the two stages never overlap:</p>
+</div>
+<div class="listingblock">
+<div class="title">build.gradle</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy">tasks.named(<span class="string"><span class="delimiter">'</span><span class="content">integrationTest</span><span class="delimiter">'</span></span>, Test) {
+ filter {
+ includeTestsMatching <span class="string"><span class="delimiter">'</span><span class="content">*IntegrationSpec</span><span class="delimiter">'</span></span>
+ }
+}
+
+tasks.register(<span class="string"><span class="delimiter">'</span><span class="content">functionalTest</span><span class="delimiter">'</span></span>, Test) {
+ group = <span class="string"><span class="delimiter">'</span><span class="content">verification</span><span class="delimiter">'</span></span>
+ description = <span class="string"><span class="delimiter">'</span><span class="content">Runs the Geb functional specs against the booted application.</span><span class="delimiter">'</span></span>
+ testClassesDirs = sourceSets.integrationTest.output.classesDirs
+ classpath = sourceSets.integrationTest.runtimeClasspath
+ useJUnitPlatform()
+ filter {
+ includeTestsMatching <span class="string"><span class="delimiter">'</span><span class="content">*FunctionalSpec</span><span class="delimiter">'</span></span>
+ }
+ shouldRunAfter tasks.named(<span class="string"><span class="delimiter">'</span><span class="content">integrationTest</span><span class="delimiter">'</span></span>)
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Reusing the <code>integration-test</code> source set means <code>@Integration</code> boots the app exactly as it does for the integration stage - no separate source-set plumbing - while the name filter keeps the two CI jobs running disjoint sets of specs. The Geb spec itself extends <code>ContainerGebSpec</code> and is named to match the <code>functionalTest</code> filter:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/HomePageFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Functional layer - runs in the `functional-test` CI stage
+ * (./gradlew functionalTest). ContainerGebSpec starts a Selenium-Chrome
+ * container via Testcontainers and drives the booted application; the only
+ * host requirement is a running Docker daemon.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">HomePageFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">the home page renders the welcome title</span><span class="delimiter">'</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">visiting the home page</span><span class="delimiter">'</span></span>
+ go <span class="string"><span class="delimiter">'</span><span class="content">/</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the page title is correct</span><span class="delimiter">'</span></span>
+ title == <span class="string"><span class="delimiter">'</span><span class="content">Welcome to Grails</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
</div>
diff --git a/guides/grails-github-actions-cicd/8/guide/index.html b/guides/grails-github-actions-cicd/8/guide/index.html
index a841a0dc086..936a1dd022c 100644
--- a/guides/grails-github-actions-cicd/8/guide/index.html
+++ b/guides/grails-github-actions-cicd/8/guide/index.html
@@ -582,6 +582,71 @@ cd grails-github-actions-cicd/complete
</li>
</ul>
</div>
+<div class="paragraph">
+<p>The stage needs at least one real unit test to be meaningful. A tiny domain class gives the suite something to exercise across all three layers:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/domain/example/Message.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.persistence.Entity</span>
+
+<span class="annotation">@Entity</span>
+<span class="type">class</span> <span class="class">Message</span> {
+
+ <span class="predefined-type">String</span> content
+
+ <span class="directive">static</span> constraints = {
+ content <span class="key">blank</span>: <span class="predefined-constant">false</span>, <span class="key">maxSize</span>: <span class="integer">500</span>
+ }
+
+ <span class="predefined-type">String</span> toString() { content }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><code>DomainUnitTest</code> runs the constraints in milliseconds with no Spring context and no database, so it belongs in the fast <code>unit-test</code> stage:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/MessageSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit layer - runs in the `unit-test` CI stage (./gradlew test). No Spring
+ * context, no database; just the domain constraints.
+ */</span>
+<span class="type">class</span> <span class="class">MessageSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<Message> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">content is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message()
+
+ <span class="key">then</span>:
+ !m.validate()
+ m.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">content</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">content over maxSize is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">501</span>)
+
+ <span class="key">then</span>:
+ !m.validate()
+ m.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">content</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a short message validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">hello</span><span class="delimiter">'</span></span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
<h1 id="integrationTests">6 The Integration-Test Job (Postgres Service Container)</h1>
@@ -630,6 +695,53 @@ cd grails-github-actions-cicd/complete
</tr>
</table>
</div>
+<div class="paragraph">
+<p>An <code>@Integration</code> spec with <code>@Rollback</code> runs against that database in the <code>integration-test</code> stage:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/MessageIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Integration layer - runs in the `integration-test` CI stage
+ * (./gradlew integrationTest) against a real PostgreSQL. @Rollback keeps
+ * each method isolated and gives a bare GORM call an ambient session.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">MessageIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a message round-trips through GORM</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Message saved = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">persist me</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ Message reloaded = Message.get(saved.id)
+
+ <span class="key">then</span>:
+ reloaded.content == <span class="string"><span class="delimiter">'</span><span class="content">persist me</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a blank message is rejected by the database layer</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>)
+ m.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ m.hasErrors()
+ Message.get(m.id) == <span class="predefined-constant">null</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Both the DB-integration specs and the Geb functional specs live in <code>src/integration-test</code> so <code>@Integration</code> wires them identically, but they run as two distinct stages. The <code>integrationTest</code> task is narrowed to the <code>*IntegrationSpec</code> classes; the next chapter’s <code>functionalTest</code> task picks up the <code>*FunctionalSpec</code> classes.</p>
+</div>
<h1 id="functionalTests">7 The Functional-Test Job (Geb + Testcontainers)</h1>
@@ -675,6 +787,66 @@ cd grails-github-actions-cicd/complete
<div class="paragraph">
<p>No <code>apt-get install</code> of Chrome/Firefox is needed - the browser process lives inside the Selenium container Testcontainers pulls (<code>selenium/standalone-chrome</code> by default). The first cold run pulls the image (~200 MB) and is slower; subsequent runs reuse the cached layer. The legacy <code>geb-with-webdriver-binaries</code> forge feature is obsolete in Grails 8 and is not used here.</p>
</div>
+<div class="sect1">
+<h2 id="_wiring_the_functionaltest_task">Wiring the functionalTest task</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>./gradlew functionalTest</code> is not a built-in Grails task. Grails gives you <code>test</code> (unit) and <code>integrationTest</code>; the functional stage is a second <code>Test</code> task over the same <code>integration-test</code> source set, filtered to the Geb specs. The <code>integrationTest</code> task is filtered the opposite way so the two stages never overlap:</p>
+</div>
+<div class="listingblock">
+<div class="title">build.gradle</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy">tasks.named(<span class="string"><span class="delimiter">'</span><span class="content">integrationTest</span><span class="delimiter">'</span></span>, Test) {
+ filter {
+ includeTestsMatching <span class="string"><span class="delimiter">'</span><span class="content">*IntegrationSpec</span><span class="delimiter">'</span></span>
+ }
+}
+
+tasks.register(<span class="string"><span class="delimiter">'</span><span class="content">functionalTest</span><span class="delimiter">'</span></span>, Test) {
+ group = <span class="string"><span class="delimiter">'</span><span class="content">verification</span><span class="delimiter">'</span></span>
+ description = <span class="string"><span class="delimiter">'</span><span class="content">Runs the Geb functional specs against the booted application.</span><span class="delimiter">'</span></span>
+ testClassesDirs = sourceSets.integrationTest.output.classesDirs
+ classpath = sourceSets.integrationTest.runtimeClasspath
+ useJUnitPlatform()
+ filter {
+ includeTestsMatching <span class="string"><span class="delimiter">'</span><span class="content">*FunctionalSpec</span><span class="delimiter">'</span></span>
+ }
+ shouldRunAfter tasks.named(<span class="string"><span class="delimiter">'</span><span class="content">integrationTest</span><span class="delimiter">'</span></span>)
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Reusing the <code>integration-test</code> source set means <code>@Integration</code> boots the app exactly as it does for the integration stage - no separate source-set plumbing - while the name filter keeps the two CI jobs running disjoint sets of specs. The Geb spec itself extends <code>ContainerGebSpec</code> and is named to match the <code>functionalTest</code> filter:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/HomePageFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Functional layer - runs in the `functional-test` CI stage
+ * (./gradlew functionalTest). ContainerGebSpec starts a Selenium-Chrome
+ * container via Testcontainers and drives the booted application; the only
+ * host requirement is a running Docker daemon.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">HomePageFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">the home page renders the welcome title</span><span class="delimiter">'</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">visiting the home page</span><span class="delimiter">'</span></span>
+ go <span class="string"><span class="delimiter">'</span><span class="content">/</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the page title is correct</span><span class="delimiter">'</span></span>
+ title == <span class="string"><span class="delimiter">'</span><span class="content">Welcome to Grails</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
<h1 id="releaseYml">8 The Release Workflow</h1>
diff --git a/guides/grails-github-actions-cicd/8/guide/integrationTests.html b/guides/grails-github-actions-cicd/8/guide/integrationTests.html
index 6c5aa652788..8b6620dab7e 100644
--- a/guides/grails-github-actions-cicd/8/guide/integrationTests.html
+++ b/guides/grails-github-actions-cicd/8/guide/integrationTests.html
@@ -138,6 +138,53 @@ function addJsClass() {
</td>
</tr>
</table>
+</div>
+<div class="paragraph">
+<p>An <code>@Integration</code> spec with <code>@Rollback</code> runs against that database in the <code>integration-test</code> stage:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/MessageIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Integration layer - runs in the `integration-test` CI stage
+ * (./gradlew integrationTest) against a real PostgreSQL. @Rollback keeps
+ * each method isolated and gives a bare GORM call an ambient session.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">MessageIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a message round-trips through GORM</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Message saved = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">persist me</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ Message reloaded = Message.get(saved.id)
+
+ <span class="key">then</span>:
+ reloaded.content == <span class="string"><span class="delimiter">'</span><span class="content">persist me</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a blank message is rejected by the database layer</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>)
+ m.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ m.hasErrors()
+ Message.get(m.id) == <span class="predefined-constant">null</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Both the DB-integration specs and the Geb functional specs live in <code>src/integration-test</code> so <code>@Integration</code> wires them identically, but they run as two distinct stages. The <code>integrationTest</code> task is narrowed to the <code>*IntegrationSpec</code> classes; the next chapter’s <code>functionalTest</code> task picks up the <code>*FunctionalSpec</code> classes.</p>
</div>
diff --git a/guides/grails-github-actions-cicd/8/guide/single.html b/guides/grails-github-actions-cicd/8/guide/single.html
index a841a0dc086..936a1dd022c 100644
--- a/guides/grails-github-actions-cicd/8/guide/single.html
+++ b/guides/grails-github-actions-cicd/8/guide/single.html
@@ -582,6 +582,71 @@ cd grails-github-actions-cicd/complete
</li>
</ul>
</div>
+<div class="paragraph">
+<p>The stage needs at least one real unit test to be meaningful. A tiny domain class gives the suite something to exercise across all three layers:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/domain/example/Message.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.persistence.Entity</span>
+
+<span class="annotation">@Entity</span>
+<span class="type">class</span> <span class="class">Message</span> {
+
+ <span class="predefined-type">String</span> content
+
+ <span class="directive">static</span> constraints = {
+ content <span class="key">blank</span>: <span class="predefined-constant">false</span>, <span class="key">maxSize</span>: <span class="integer">500</span>
+ }
+
+ <span class="predefined-type">String</span> toString() { content }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><code>DomainUnitTest</code> runs the constraints in milliseconds with no Spring context and no database, so it belongs in the fast <code>unit-test</code> stage:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/MessageSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit layer - runs in the `unit-test` CI stage (./gradlew test). No Spring
+ * context, no database; just the domain constraints.
+ */</span>
+<span class="type">class</span> <span class="class">MessageSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<Message> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">content is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message()
+
+ <span class="key">then</span>:
+ !m.validate()
+ m.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">content</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">content over maxSize is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">501</span>)
+
+ <span class="key">then</span>:
+ !m.validate()
+ m.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">content</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a short message validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">hello</span><span class="delimiter">'</span></span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
<h1 id="integrationTests">6 The Integration-Test Job (Postgres Service Container)</h1>
@@ -630,6 +695,53 @@ cd grails-github-actions-cicd/complete
</tr>
</table>
</div>
+<div class="paragraph">
+<p>An <code>@Integration</code> spec with <code>@Rollback</code> runs against that database in the <code>integration-test</code> stage:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/MessageIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Integration layer - runs in the `integration-test` CI stage
+ * (./gradlew integrationTest) against a real PostgreSQL. @Rollback keeps
+ * each method isolated and gives a bare GORM call an ambient session.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">MessageIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a message round-trips through GORM</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Message saved = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">persist me</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ Message reloaded = Message.get(saved.id)
+
+ <span class="key">then</span>:
+ reloaded.content == <span class="string"><span class="delimiter">'</span><span class="content">persist me</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a blank message is rejected by the database layer</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>)
+ m.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ m.hasErrors()
+ Message.get(m.id) == <span class="predefined-constant">null</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Both the DB-integration specs and the Geb functional specs live in <code>src/integration-test</code> so <code>@Integration</code> wires them identically, but they run as two distinct stages. The <code>integrationTest</code> task is narrowed to the <code>*IntegrationSpec</code> classes; the next chapter’s <code>functionalTest</code> task picks up the <code>*FunctionalSpec</code> classes.</p>
+</div>
<h1 id="functionalTests">7 The Functional-Test Job (Geb + Testcontainers)</h1>
@@ -675,6 +787,66 @@ cd grails-github-actions-cicd/complete
<div class="paragraph">
<p>No <code>apt-get install</code> of Chrome/Firefox is needed - the browser process lives inside the Selenium container Testcontainers pulls (<code>selenium/standalone-chrome</code> by default). The first cold run pulls the image (~200 MB) and is slower; subsequent runs reuse the cached layer. The legacy <code>geb-with-webdriver-binaries</code> forge feature is obsolete in Grails 8 and is not used here.</p>
</div>
+<div class="sect1">
+<h2 id="_wiring_the_functionaltest_task">Wiring the functionalTest task</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>./gradlew functionalTest</code> is not a built-in Grails task. Grails gives you <code>test</code> (unit) and <code>integrationTest</code>; the functional stage is a second <code>Test</code> task over the same <code>integration-test</code> source set, filtered to the Geb specs. The <code>integrationTest</code> task is filtered the opposite way so the two stages never overlap:</p>
+</div>
+<div class="listingblock">
+<div class="title">build.gradle</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy">tasks.named(<span class="string"><span class="delimiter">'</span><span class="content">integrationTest</span><span class="delimiter">'</span></span>, Test) {
+ filter {
+ includeTestsMatching <span class="string"><span class="delimiter">'</span><span class="content">*IntegrationSpec</span><span class="delimiter">'</span></span>
+ }
+}
+
+tasks.register(<span class="string"><span class="delimiter">'</span><span class="content">functionalTest</span><span class="delimiter">'</span></span>, Test) {
+ group = <span class="string"><span class="delimiter">'</span><span class="content">verification</span><span class="delimiter">'</span></span>
+ description = <span class="string"><span class="delimiter">'</span><span class="content">Runs the Geb functional specs against the booted application.</span><span class="delimiter">'</span></span>
+ testClassesDirs = sourceSets.integrationTest.output.classesDirs
+ classpath = sourceSets.integrationTest.runtimeClasspath
+ useJUnitPlatform()
+ filter {
+ includeTestsMatching <span class="string"><span class="delimiter">'</span><span class="content">*FunctionalSpec</span><span class="delimiter">'</span></span>
+ }
+ shouldRunAfter tasks.named(<span class="string"><span class="delimiter">'</span><span class="content">integrationTest</span><span class="delimiter">'</span></span>)
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Reusing the <code>integration-test</code> source set means <code>@Integration</code> boots the app exactly as it does for the integration stage - no separate source-set plumbing - while the name filter keeps the two CI jobs running disjoint sets of specs. The Geb spec itself extends <code>ContainerGebSpec</code> and is named to match the <code>functionalTest</code> filter:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/HomePageFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Functional layer - runs in the `functional-test` CI stage
+ * (./gradlew functionalTest). ContainerGebSpec starts a Selenium-Chrome
+ * container via Testcontainers and drives the booted application; the only
+ * host requirement is a running Docker daemon.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">HomePageFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">the home page renders the welcome title</span><span class="delimiter">'</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">visiting the home page</span><span class="delimiter">'</span></span>
+ go <span class="string"><span class="delimiter">'</span><span class="content">/</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the page title is correct</span><span class="delimiter">'</span></span>
+ title == <span class="string"><span class="delimiter">'</span><span class="content">Welcome to Grails</span><span class="delimiter">'</span></span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
<h1 id="releaseYml">8 The Release Workflow</h1>
diff --git a/guides/grails-github-actions-cicd/8/guide/unitTests.html b/guides/grails-github-actions-cicd/8/guide/unitTests.html
index e578bcc3235..b5e4ff726c1 100644
--- a/guides/grails-github-actions-cicd/8/guide/unitTests.html
+++ b/guides/grails-github-actions-cicd/8/guide/unitTests.html
@@ -140,6 +140,71 @@ function addJsClass() {
<p><code>--no-daemon</code> ensures the JVM starts cold and reports honest first-run times. The Gradle dependency cache is still warm; the daemon caching disagreement was about JVM warm-up, not classpath resolution.</p>
</li>
</ul>
+</div>
+<div class="paragraph">
+<p>The stage needs at least one real unit test to be meaningful. A tiny domain class gives the suite something to exercise across all three layers:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/domain/example/Message.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.persistence.Entity</span>
+
+<span class="annotation">@Entity</span>
+<span class="type">class</span> <span class="class">Message</span> {
+
+ <span class="predefined-type">String</span> content
+
+ <span class="directive">static</span> constraints = {
+ content <span class="key">blank</span>: <span class="predefined-constant">false</span>, <span class="key">maxSize</span>: <span class="integer">500</span>
+ }
+
+ <span class="predefined-type">String</span> toString() { content }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><code>DomainUnitTest</code> runs the constraints in milliseconds with no Spring context and no database, so it belongs in the fast <code>unit-test</code> stage:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/MessageSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit layer - runs in the `unit-test` CI stage (./gradlew test). No Spring
+ * context, no database; just the domain constraints.
+ */</span>
+<span class="type">class</span> <span class="class">MessageSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<Message> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">content is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message()
+
+ <span class="key">then</span>:
+ !m.validate()
+ m.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">content</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">content over maxSize is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Message m = <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">501</span>)
+
+ <span class="key">then</span>:
+ !m.validate()
+ m.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">content</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a short message validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Message(<span class="key">content</span>: <span class="string"><span class="delimiter">'</span><span class="content">hello</span><span class="delimiter">'</span></span>).validate()
+ }
+}</code></pre>
+</div>
</div>
diff --git a/guides/grails-htmx/8/guide/controller.html b/guides/grails-htmx/8/guide/controller.html
index 74e52a903f1..c78b4c65811 100644
--- a/guides/grails-htmx/8/guide/controller.html
+++ b/guides/grails-htmx/8/guide/controller.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/createApp.html b/guides/grails-htmx/8/guide/createApp.html
index 3bfc20ea929..54823ce353f 100644
--- a/guides/grails-htmx/8/guide/createApp.html
+++ b/guides/grails-htmx/8/guide/createApp.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/csrf.html b/guides/grails-htmx/8/guide/csrf.html
index 5235029acd4..ae230c39f24 100644
--- a/guides/grails-htmx/8/guide/csrf.html
+++ b/guides/grails-htmx/8/guide/csrf.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/gettingStarted.html b/guides/grails-htmx/8/guide/gettingStarted.html
index 81aa2fc9714..84e11273a47 100644
--- a/guides/grails-htmx/8/guide/gettingStarted.html
+++ b/guides/grails-htmx/8/guide/gettingStarted.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/helpWithGrails.html b/guides/grails-htmx/8/guide/helpWithGrails.html
index bb5f6e7e1ca..eeabf054da9 100644
--- a/guides/grails-htmx/8/guide/helpWithGrails.html
+++ b/guides/grails-htmx/8/guide/helpWithGrails.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>13 Do you need help with Grails?</title>
+ <title>14 Do you need help with Grails?</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -84,7 +87,7 @@ function addJsClass() {
<div id="main" class="corner-all">
- <div class="toc-item prev-left"><a href="../guide/spaComparison.html"><< <strong>12</strong><span>HTMX vs an SPA</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>13</strong><span>Testing the HTMX UI</span></a></div>
@@ -94,7 +97,7 @@ function addJsClass() {
-<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">14 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-htmx/v8/guide/helpWithGrails.adoc"'>
@@ -137,7 +140,7 @@ function addJsClass() {
<div style="clear:both;margin-top:15px;"></div>
- <div class="toc-item prev-left"><a href="../guide/spaComparison.html"><< <strong>12</strong><span>HTMX vs an SPA</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>13</strong><span>Testing the HTMX UI</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-htmx/8/guide/index.html b/guides/grails-htmx/8/guide/index.html
index 62a88bf2a36..c605e5cc1d6 100644
--- a/guides/grails-htmx/8/guide/index.html
+++ b/guides/grails-htmx/8/guide/index.html
@@ -131,7 +131,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#spaComparison"><strong>12</strong><span>HTMX vs an SPA</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>13</strong><span>Testing the HTMX UI</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>14</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -558,6 +560,20 @@ cd grails-htmx/complete
<div class="paragraph">
<p>This is also close to the Grails 8 <code>web</code> profile skeleton, which still shows explicit <code>"/$controller/$action?/$id?(.$format)?"</code> mappings in <code>UrlMappings.groovy</code>.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Because <code>/tasks</code> is shared by <code>index</code> and <code>create</code>, and <code>/tasks/$id</code> by <code>show</code>, <code>update</code>, and <code>delete</code>, Grails' reverse URL mapping cannot unambiguously pick a route from a controller+action pair alone - <code>createLink(controller: 'task', action: 'create')</code> falls back to the default <code>/task/create</code> convention, which no mapping serves, so the HTMX request 404s and nothing swaps. The partials [...]
+</div>
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>Files touched:</p>
</div>
@@ -753,7 +769,7 @@ cd grails-htmx/complete
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${q}</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">Search tasks...</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">form-control mb-3</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'search')}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/search')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-trigger</span>=<span class="string"><span class="delimiter">"</span><span class="content">keyup changed delay:300ms</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">#taskList</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">innerHTML</span><span class="delimiter">"</span></span><span class="tag">/></span>
@@ -836,7 +852,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-sm ${task.done ? 'btn-success' : 'btn-outline-secondary'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-post</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'toggle', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-post</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id + '/toggle')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span>
<span class="attribute-name">aria-pressed</span>=<span class="string"><span class="delimiter">"</span><span class="content">${task.done}</span><span class="delimiter">"</span></span>
@@ -846,7 +862,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-link p-0 text-start text-decoration-none flex-grow-1 ${task.done ? 'text-body-secondary' : 'text-body'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'editForm', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id + '/edit')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span>
<span class="attribute-name">title</span>=<span class="string"><span class="delimiter">"</span><span class="content">Click to edit</span><span class="delimiter">"</span></span><span class="tag">></span>
@@ -855,7 +871,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-sm btn-outline-danger</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-delete</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'delete', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-delete</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML swap:200ms</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-confirm</span>=<span class="string"><span class="delimiter">"</span><span class="content">Delete this task?</span><span class="delimiter">"</span></span>
@@ -931,7 +947,7 @@ cd grails-htmx/complete
<span class="attribute-name">action</span>=<span class="string"><span class="delimiter">"</span><span class="content">update</span><span class="delimiter">"</span></span>
<span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">${task.id}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">d-flex gap-2</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-patch</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'update', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-patch</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">title</span><span class="delimiter">"</span></span>
@@ -942,7 +958,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">submit</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-primary btn-sm</span><span class="delimiter">"</span></span><span class="tag">></span>Save<span class="tag"></button></span>
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-outline-secondary btn-sm</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'show', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span><span class="tag">></span>Cancel<span class="tag"></button></span>
<span class="tag"></g:form></span>
@@ -1237,7 +1253,296 @@ withForm {
</div>
-<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
+<h1 id="testing">13 Testing the HTMX UI</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-htmx/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The sample app is covered at three layers: fast domain unit tests, <code>@Integration</code> tests for the GORM queries the controller relies on, and Geb browser tests that drive the real HTMX interactions. The integration and functional layers run against the in-memory H2 database; the browser layer additionally needs a running Docker daemon for the Selenium container.</p>
+</div>
+<div class="sect1">
+<h2 id="_unit_the_task_domain">Unit: the Task domain</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DomainUnitTest<Task></code> exercises the constraints in milliseconds with no Spring context:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/TaskSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Domain unit tests for Task - constraints and defaults, no Spring context.
+ */</span>
+<span class="type">class</span> <span class="class">TaskSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<Task> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Task t = <span class="keyword">new</span> Task()
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a blank title is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a blank string is assigned directly (the map constructor would null it)</span><span class="delimiter">'</span></span>
+ Task t = <span class="keyword">new</span> Task()
+ t.title = <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a title longer than maxSize is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Task t = <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">256</span>)
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a new task defaults to not done</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ !<span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Something</span><span class="delimiter">'</span></span>).done
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid task validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Buy milk</span><span class="delimiter">'</span></span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_the_queries_behind_the_endpoints">Integration: the queries behind the endpoints</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The live-search action calls <code>Task.findAllByTitleIlike(…​)</code> and the list relies on the <code>dateCreated desc</code> mapping. An <code>@Integration</code> + <code>@Rollback</code> spec pins both against a real database:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/TaskIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full context against the in-memory H2 database.
+ * @Rollback isolates each method and provides an ambient session, so the
+ * GORM queries the TaskController relies on can be exercised directly.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">TaskIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">findAllByTitleIlike matches case-insensitively (the live-search query)</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Walk the dog</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%milk%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>]
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%MILK%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>]
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%walk%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Walk the dog</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">tasks list newest first per the domain mapping</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Older</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="predefined-type">Thread</span>.sleep(<span class="integer">20</span>)
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Newer</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Task.list().first().title == <span class="string"><span class="delimiter">'</span><span class="content">Newer</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">toggling done persists</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Task t = <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Toggle</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ t.done = <span class="predefined-constant">true</span>
+ t.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ Task.get(t.id).done
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_browser_the_htmx_interactions_through_geb">Browser: the HTMX interactions through Geb</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>ContainerGebSpec</code> starts a Selenium-Chrome container via Testcontainers and drives the booted app. Each HTMX swap type is exercised: the create OOB prepend, the toggle and inline-edit <code>outerHTML</code> swaps, the live-search <code>innerHTML</code> swap, and the delete removal. <code>withConfirm(true)</code> answers the <code>hx-confirm</code> dialog on delete:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/TaskTrackerFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Browser tests for the htmx interactions, driven by Geb 8 against a real
+ * booted application. ContainerGebSpec starts a Selenium-Chrome container via
+ * Testcontainers, so the only host requirement is a running Docker daemon.
+ *
+ * Each htmx swap type is exercised: the create OOB prepend, the toggle/edit
+ * outerHTML swaps, the live-search innerHTML swap, and the delete removal.
+ * @Rollback is not used (the endpoints commit); tests use unique titles so
+ * they stay independent of rows left by earlier feature methods.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">TaskTrackerFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="directive">private</span> <span class="type">void</span> addTaskThroughForm(<span class="predefined-type">String</span> taskTitle) {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).value(taskTitle)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimiter">'</span><span class="content">submit</span><span class="delimiter">'</span></span>).click()
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(taskTitle) }
+ }
+
+ <span class="directive">private</span> rowFor(<span class="predefined-type">String</span> taskTitle) {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList li</span><span class="delimiter">'</span></span>).findAll { <span class="local-variable">it</span>.text().contains(taskTitle) }[<span class="integer">0</span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">the task page loads with the add form and search box</span><span class="delimiter">'</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ title == <span class="string"><span class="delimiter">'</span><span class="content">HTMX Task Tracker</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">h1</span><span class="delimiter">'</span></span>).text() == <span class="string"><span class="delimiter">'</span><span class="content">Tasks</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">q</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">adding a task prepends it to the list via an OOB swap and resets the form</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+
+ <span class="key">when</span>:
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">OOB swap task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the new row is at the top of the list</span><span class="delimiter">'</span></span>
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList li</span><span class="delimiter">'</span></span>, <span class="integer">0</span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">OOB swap task</span><span class="delimiter">'</span></span>) }
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the add form input was reset by the swap</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).value() == <span class [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">toggling a task applies the done styling</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">clicking the toggle button (first button in the row)</span><span class="delimiter">'</span></span>
+ rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>)[<span class="integer">0</span>].click()
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the swapped-in row carries the done class</span><span class="delimiter">'</span></span>
+ waitFor { rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>).classes().contains(<span class="string"><span class="delimiter">'</span><span class="content">text-decoration-line-through</span><span class="delimiter">'</span></span>) }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">clicking a task opens the inline edit form and saving updates the title</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Editable task</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Long</span> id = Task.withNewTransaction { Task.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">Editable task</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">clicking the title button opens the edit form</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">title</span>: <span class="string"><span class="delimit [...]
+
+ <span class="key">then</span>:
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class= [...]
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">editing and saving (the row keeps its id across the swap)</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter [...]
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimite [...]
+
+ <span class="key">then</span>:
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Edited task title</span><span class="delimiter">'</span></span>) }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">live search filters the list via an innerHTML swap</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Searchable alpha unique</span><span class="delimiter">'</span></span>)
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Searchable beta unique</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">typing a term that matches only one task</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">q</span><span class="delimiter">'</span></span>).value(<span class="string"><span class="delimiter">'</span><span class="content">alpha unique</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ waitFor {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Searchable alpha unique</span><span class="delimiter">'</span></span>) &&
+ !<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Searchable beta unique</span><span class="delimiter">'</span></span>)
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">deleting a task removes its row</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">confirming the delete</span><span class="delimiter">'</span></span>
+ withConfirm(<span class="predefined-constant">true</span>) {
+ rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">aria-label</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="con [...]
+ }
+
+ <span class="key">then</span>:
+ waitFor { !<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>) }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>A few disciplines keep these browser tests reliable:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>@Rollback</code> is <strong>not</strong> used - the HTMX endpoints commit, so each spec creates its fixture through the UI (or <code>withNewTransaction</code>) and uses unique titles so rows left by earlier feature methods do not interfere.</p>
+</li>
+<li>
+<p><code>waitFor { …​ }</code> wraps every assertion that follows an HTMX request, because the swap happens asynchronously after the AJAX round trip.</p>
+</li>
+<li>
+<p>Rows are targeted by their stable <code>#task-${id}</code> id, which survives the <code>outerHTML</code> swaps, rather than by text that changes mid-edit.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Run it all:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + Geb browser tests - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+<h1 id="helpWithGrails">14 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-htmx/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-htmx/8/guide/indexPage.html b/guides/grails-htmx/8/guide/indexPage.html
index b5752b95289..3a602e3574c 100644
--- a/guides/grails-htmx/8/guide/indexPage.html
+++ b/guides/grails-htmx/8/guide/indexPage.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -130,7 +133,7 @@ function addJsClass() {
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${q}</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">Search tasks...</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">form-control mb-3</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'search')}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/search')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-trigger</span>=<span class="string"><span class="delimiter">"</span><span class="content">keyup changed delay:300ms</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">#taskList</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">innerHTML</span><span class="delimiter">"</span></span><span class="tag">/></span>
diff --git a/guides/grails-htmx/8/guide/inlineEdit.html b/guides/grails-htmx/8/guide/inlineEdit.html
index b596dea66a5..76239ccb7a6 100644
--- a/guides/grails-htmx/8/guide/inlineEdit.html
+++ b/guides/grails-htmx/8/guide/inlineEdit.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -116,7 +119,7 @@ function addJsClass() {
<span class="attribute-name">action</span>=<span class="string"><span class="delimiter">"</span><span class="content">update</span><span class="delimiter">"</span></span>
<span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">${task.id}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">d-flex gap-2</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-patch</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'update', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-patch</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">title</span><span class="delimiter">"</span></span>
@@ -127,7 +130,7 @@ function addJsClass() {
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">submit</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-primary btn-sm</span><span class="delimiter">"</span></span><span class="tag">></span>Save<span class="tag"></button></span>
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-outline-secondary btn-sm</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'show', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span><span class="tag">></span>Cancel<span class="tag"></button></span>
<span class="tag"></g:form></span>
diff --git a/guides/grails-htmx/8/guide/layoutWithHtmx.html b/guides/grails-htmx/8/guide/layoutWithHtmx.html
index caffe20c883..92b67df47de 100644
--- a/guides/grails-htmx/8/guide/layoutWithHtmx.html
+++ b/guides/grails-htmx/8/guide/layoutWithHtmx.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/liveSearch.html b/guides/grails-htmx/8/guide/liveSearch.html
index d4d5f446bf7..edb98e1236d 100644
--- a/guides/grails-htmx/8/guide/liveSearch.html
+++ b/guides/grails-htmx/8/guide/liveSearch.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/pages/howto.html b/guides/grails-htmx/8/guide/pages/howto.html
index 349eab5d363..55381ef94d7 100644
--- a/guides/grails-htmx/8/guide/pages/howto.html
+++ b/guides/grails-htmx/8/guide/pages/howto.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/pages/requirements.html b/guides/grails-htmx/8/guide/pages/requirements.html
index 02d0277f9c8..e440f61f070 100644
--- a/guides/grails-htmx/8/guide/pages/requirements.html
+++ b/guides/grails-htmx/8/guide/pages/requirements.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/pages/whatYouWillBuild.html b/guides/grails-htmx/8/guide/pages/whatYouWillBuild.html
index 7cd6eaffe6f..4adf6265c47 100644
--- a/guides/grails-htmx/8/guide/pages/whatYouWillBuild.html
+++ b/guides/grails-htmx/8/guide/pages/whatYouWillBuild.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/rowPartial.html b/guides/grails-htmx/8/guide/rowPartial.html
index 705e6ec715f..d374406c9b3 100644
--- a/guides/grails-htmx/8/guide/rowPartial.html
+++ b/guides/grails-htmx/8/guide/rowPartial.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -131,7 +134,7 @@ function addJsClass() {
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-sm ${task.done ? 'btn-success' : 'btn-outline-secondary'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-post</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'toggle', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-post</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id + '/toggle')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span>
<span class="attribute-name">aria-pressed</span>=<span class="string"><span class="delimiter">"</span><span class="content">${task.done}</span><span class="delimiter">"</span></span>
@@ -141,7 +144,7 @@ function addJsClass() {
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-link p-0 text-start text-decoration-none flex-grow-1 ${task.done ? 'text-body-secondary' : 'text-body'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'editForm', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id + '/edit')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span>
<span class="attribute-name">title</span>=<span class="string"><span class="delimiter">"</span><span class="content">Click to edit</span><span class="delimiter">"</span></span><span class="tag">></span>
@@ -150,7 +153,7 @@ function addJsClass() {
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-sm btn-outline-danger</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-delete</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'delete', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-delete</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML swap:200ms</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-confirm</span>=<span class="string"><span class="delimiter">"</span><span class="content">Delete this task?</span><span class="delimiter">"</span></span>
diff --git a/guides/grails-htmx/8/guide/single.html b/guides/grails-htmx/8/guide/single.html
index 62a88bf2a36..c605e5cc1d6 100644
--- a/guides/grails-htmx/8/guide/single.html
+++ b/guides/grails-htmx/8/guide/single.html
@@ -131,7 +131,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#spaComparison"><strong>12</strong><span>HTMX vs an SPA</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>13</strong><span>Testing the HTMX UI</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>14</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -558,6 +560,20 @@ cd grails-htmx/complete
<div class="paragraph">
<p>This is also close to the Grails 8 <code>web</code> profile skeleton, which still shows explicit <code>"/$controller/$action?/$id?(.$format)?"</code> mappings in <code>UrlMappings.groovy</code>.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Because <code>/tasks</code> is shared by <code>index</code> and <code>create</code>, and <code>/tasks/$id</code> by <code>show</code>, <code>update</code>, and <code>delete</code>, Grails' reverse URL mapping cannot unambiguously pick a route from a controller+action pair alone - <code>createLink(controller: 'task', action: 'create')</code> falls back to the default <code>/task/create</code> convention, which no mapping serves, so the HTMX request 404s and nothing swaps. The partials [...]
+</div>
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>Files touched:</p>
</div>
@@ -753,7 +769,7 @@ cd grails-htmx/complete
<span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">${q}</span><span class="delimiter">"</span></span>
<span class="attribute-name">placeholder</span>=<span class="string"><span class="delimiter">"</span><span class="content">Search tasks...</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">form-control mb-3</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'search')}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/search')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-trigger</span>=<span class="string"><span class="delimiter">"</span><span class="content">keyup changed delay:300ms</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">#taskList</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">innerHTML</span><span class="delimiter">"</span></span><span class="tag">/></span>
@@ -836,7 +852,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-sm ${task.done ? 'btn-success' : 'btn-outline-secondary'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-post</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'toggle', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-post</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id + '/toggle')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span>
<span class="attribute-name">aria-pressed</span>=<span class="string"><span class="delimiter">"</span><span class="content">${task.done}</span><span class="delimiter">"</span></span>
@@ -846,7 +862,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-link p-0 text-start text-decoration-none flex-grow-1 ${task.done ? 'text-body-secondary' : 'text-body'}</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'editForm', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id + '/edit')}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span>
<span class="attribute-name">title</span>=<span class="string"><span class="delimiter">"</span><span class="content">Click to edit</span><span class="delimiter">"</span></span><span class="tag">></span>
@@ -855,7 +871,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-sm btn-outline-danger</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-delete</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'delete', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-delete</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML swap:200ms</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-confirm</span>=<span class="string"><span class="delimiter">"</span><span class="content">Delete this task?</span><span class="delimiter">"</span></span>
@@ -931,7 +947,7 @@ cd grails-htmx/complete
<span class="attribute-name">action</span>=<span class="string"><span class="delimiter">"</span><span class="content">update</span><span class="delimiter">"</span></span>
<span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">${task.id}</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">d-flex gap-2</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-patch</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'update', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-patch</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><g:textField</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">title</span><span class="delimiter">"</span></span>
@@ -942,7 +958,7 @@ cd grails-htmx/complete
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">submit</span><span class="delimiter">"</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-primary btn-sm</span><span class="delimiter">"</span></span><span class="tag">></span>Save<span class="tag"></button></span>
<span class="tag"><button</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">button</span><span class="delimiter">"</span></span>
<span class="attribute-name">class</span>=<span class="string"><span class="delimiter">"</span><span class="content">btn btn-outline-secondary btn-sm</span><span class="delimiter">"</span></span>
- <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(controller: 'task', action: 'show', id: task.id)}</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">hx-get</span>=<span class="string"><span class="delimiter">"</span><span class="content">${createLink(uri: '/tasks/' + task.id)}</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-target</span>=<span class="string"><span class="delimiter">"</span><span class="content">closest li</span><span class="delimiter">"</span></span>
<span class="attribute-name">hx-swap</span>=<span class="string"><span class="delimiter">"</span><span class="content">outerHTML</span><span class="delimiter">"</span></span><span class="tag">></span>Cancel<span class="tag"></button></span>
<span class="tag"></g:form></span>
@@ -1237,7 +1253,296 @@ withForm {
</div>
-<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
+<h1 id="testing">13 Testing the HTMX UI</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-htmx/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The sample app is covered at three layers: fast domain unit tests, <code>@Integration</code> tests for the GORM queries the controller relies on, and Geb browser tests that drive the real HTMX interactions. The integration and functional layers run against the in-memory H2 database; the browser layer additionally needs a running Docker daemon for the Selenium container.</p>
+</div>
+<div class="sect1">
+<h2 id="_unit_the_task_domain">Unit: the Task domain</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DomainUnitTest<Task></code> exercises the constraints in milliseconds with no Spring context:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/TaskSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Domain unit tests for Task - constraints and defaults, no Spring context.
+ */</span>
+<span class="type">class</span> <span class="class">TaskSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<Task> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Task t = <span class="keyword">new</span> Task()
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a blank title is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a blank string is assigned directly (the map constructor would null it)</span><span class="delimiter">'</span></span>
+ Task t = <span class="keyword">new</span> Task()
+ t.title = <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a title longer than maxSize is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Task t = <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">256</span>)
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a new task defaults to not done</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ !<span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Something</span><span class="delimiter">'</span></span>).done
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid task validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Buy milk</span><span class="delimiter">'</span></span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_the_queries_behind_the_endpoints">Integration: the queries behind the endpoints</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The live-search action calls <code>Task.findAllByTitleIlike(…​)</code> and the list relies on the <code>dateCreated desc</code> mapping. An <code>@Integration</code> + <code>@Rollback</code> spec pins both against a real database:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/TaskIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full context against the in-memory H2 database.
+ * @Rollback isolates each method and provides an ambient session, so the
+ * GORM queries the TaskController relies on can be exercised directly.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">TaskIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">findAllByTitleIlike matches case-insensitively (the live-search query)</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Walk the dog</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%milk%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>]
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%MILK%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>]
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%walk%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Walk the dog</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">tasks list newest first per the domain mapping</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Older</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="predefined-type">Thread</span>.sleep(<span class="integer">20</span>)
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Newer</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Task.list().first().title == <span class="string"><span class="delimiter">'</span><span class="content">Newer</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">toggling done persists</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Task t = <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Toggle</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ t.done = <span class="predefined-constant">true</span>
+ t.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ Task.get(t.id).done
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_browser_the_htmx_interactions_through_geb">Browser: the HTMX interactions through Geb</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>ContainerGebSpec</code> starts a Selenium-Chrome container via Testcontainers and drives the booted app. Each HTMX swap type is exercised: the create OOB prepend, the toggle and inline-edit <code>outerHTML</code> swaps, the live-search <code>innerHTML</code> swap, and the delete removal. <code>withConfirm(true)</code> answers the <code>hx-confirm</code> dialog on delete:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/TaskTrackerFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Browser tests for the htmx interactions, driven by Geb 8 against a real
+ * booted application. ContainerGebSpec starts a Selenium-Chrome container via
+ * Testcontainers, so the only host requirement is a running Docker daemon.
+ *
+ * Each htmx swap type is exercised: the create OOB prepend, the toggle/edit
+ * outerHTML swaps, the live-search innerHTML swap, and the delete removal.
+ * @Rollback is not used (the endpoints commit); tests use unique titles so
+ * they stay independent of rows left by earlier feature methods.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">TaskTrackerFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="directive">private</span> <span class="type">void</span> addTaskThroughForm(<span class="predefined-type">String</span> taskTitle) {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).value(taskTitle)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimiter">'</span><span class="content">submit</span><span class="delimiter">'</span></span>).click()
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(taskTitle) }
+ }
+
+ <span class="directive">private</span> rowFor(<span class="predefined-type">String</span> taskTitle) {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList li</span><span class="delimiter">'</span></span>).findAll { <span class="local-variable">it</span>.text().contains(taskTitle) }[<span class="integer">0</span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">the task page loads with the add form and search box</span><span class="delimiter">'</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ title == <span class="string"><span class="delimiter">'</span><span class="content">HTMX Task Tracker</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">h1</span><span class="delimiter">'</span></span>).text() == <span class="string"><span class="delimiter">'</span><span class="content">Tasks</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">q</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">adding a task prepends it to the list via an OOB swap and resets the form</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+
+ <span class="key">when</span>:
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">OOB swap task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the new row is at the top of the list</span><span class="delimiter">'</span></span>
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList li</span><span class="delimiter">'</span></span>, <span class="integer">0</span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">OOB swap task</span><span class="delimiter">'</span></span>) }
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the add form input was reset by the swap</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).value() == <span class [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">toggling a task applies the done styling</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">clicking the toggle button (first button in the row)</span><span class="delimiter">'</span></span>
+ rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>)[<span class="integer">0</span>].click()
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the swapped-in row carries the done class</span><span class="delimiter">'</span></span>
+ waitFor { rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>).classes().contains(<span class="string"><span class="delimiter">'</span><span class="content">text-decoration-line-through</span><span class="delimiter">'</span></span>) }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">clicking a task opens the inline edit form and saving updates the title</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Editable task</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Long</span> id = Task.withNewTransaction { Task.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">Editable task</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">clicking the title button opens the edit form</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">title</span>: <span class="string"><span class="delimit [...]
+
+ <span class="key">then</span>:
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class= [...]
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">editing and saving (the row keeps its id across the swap)</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter [...]
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimite [...]
+
+ <span class="key">then</span>:
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Edited task title</span><span class="delimiter">'</span></span>) }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">live search filters the list via an innerHTML swap</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Searchable alpha unique</span><span class="delimiter">'</span></span>)
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Searchable beta unique</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">typing a term that matches only one task</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">q</span><span class="delimiter">'</span></span>).value(<span class="string"><span class="delimiter">'</span><span class="content">alpha unique</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ waitFor {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Searchable alpha unique</span><span class="delimiter">'</span></span>) &&
+ !<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Searchable beta unique</span><span class="delimiter">'</span></span>)
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">deleting a task removes its row</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">confirming the delete</span><span class="delimiter">'</span></span>
+ withConfirm(<span class="predefined-constant">true</span>) {
+ rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">aria-label</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="con [...]
+ }
+
+ <span class="key">then</span>:
+ waitFor { !<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>) }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>A few disciplines keep these browser tests reliable:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>@Rollback</code> is <strong>not</strong> used - the HTMX endpoints commit, so each spec creates its fixture through the UI (or <code>withNewTransaction</code>) and uses unique titles so rows left by earlier feature methods do not interfere.</p>
+</li>
+<li>
+<p><code>waitFor { …​ }</code> wraps every assertion that follows an HTMX request, because the swap happens asynchronously after the AJAX round trip.</p>
+</li>
+<li>
+<p>Rows are targeted by their stable <code>#task-${id}</code> id, which survives the <code>outerHTML</code> swaps, rather than by text that changes mid-edit.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Run it all:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + Geb browser tests - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+<h1 id="helpWithGrails">14 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-htmx/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-htmx/8/guide/spaComparison.html b/guides/grails-htmx/8/guide/spaComparison.html
index 4fe813b9017..426ba1a6f7a 100644
--- a/guides/grails-htmx/8/guide/spaComparison.html
+++ b/guides/grails-htmx/8/guide/spaComparison.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -88,7 +91,7 @@ function addJsClass() {
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span> >></a></div>
@@ -155,7 +158,7 @@ function addJsClass() {
<div class="toc-item prev-left"><a href="../guide/csrf.html"><< <strong>11</strong><span>CSRF With HTMX</span></a></div>
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span> >></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-htmx/8/guide/taskDomain.html b/guides/grails-htmx/8/guide/taskDomain.html
index 988c4aaf3bf..340265514f2 100644
--- a/guides/grails-htmx/8/guide/taskDomain.html
+++ b/guides/grails-htmx/8/guide/taskDomain.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-htmx/8/guide/testing.html b/guides/grails-htmx/8/guide/testing.html
new file mode 100644
index 00000000000..ffa4fe74e9c
--- /dev/null
+++ b/guides/grails-htmx/8/guide/testing.html
@@ -0,0 +1,442 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+ <title>13 Testing the HTMX UI</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
+ <link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
+ <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
+ <script type="text/javascript">
+function addJsClass() {
+ var classes = document.body.className.split(" ");
+ classes.push("js");
+ document.body.className = classes.join(" ");
+}
+ </script>
+</head>
+
+<body class="body" onload="addJsClass();">
+<div id="navigation">
+ <div class="navTitle">
+
+ Grails Framework Guide
+ </div>
+ <div class="navLinks">
+ <ul>
+ <li>
+ <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
+ <a href="../guide/index.html" class="button">Table of contents</a>
+
+ <div id="nav-summary-childs" style="display:none;">
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>1</strong><span>Getting Started</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/createApp.html"><strong>2</strong><span>Creating the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/taskDomain.html"><strong>3</strong><span>The Task Domain Class</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/layoutWithHtmx.html"><strong>4</strong><span>Adding HTMX to the Layout</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/urlMappings.html"><strong>5</strong><span>URL Mappings</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/controller.html"><strong>6</strong><span>The TaskController</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/indexPage.html"><strong>7</strong><span>The Initial Page</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/rowPartial.html"><strong>8</strong><span>The Row Partial</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/inlineEdit.html"><strong>9</strong><span>Inline Edit With Validation</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/liveSearch.html"><strong>10</strong><span>Live Search</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/csrf.html"><strong>11</strong><span>CSRF With HTMX</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
+ </div>
+
+ </div>
+ </div>
+ </li>
+ </ul>
+ </div>
+
+
+</div>
+
+<table id="colset" border="0" cellpadding="0" cellspacing="0">
+ <tr>
+ <td id="col1">
+ <div id="main" class="corner-all">
+
+
+ <div class="toc-item prev-left"><a href="../guide/spaComparison.html"><< <strong>12</strong><span>HTMX vs an SPA</span></a></div>
+
+
+
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span> >></a></div>
+
+
+
+
+
+
+
+<h1 id="testing">13 Testing the HTMX UI</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-htmx/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The sample app is covered at three layers: fast domain unit tests, <code>@Integration</code> tests for the GORM queries the controller relies on, and Geb browser tests that drive the real HTMX interactions. The integration and functional layers run against the in-memory H2 database; the browser layer additionally needs a running Docker daemon for the Selenium container.</p>
+</div>
+<div class="sect1">
+<h2 id="_unit_the_task_domain">Unit: the Task domain</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DomainUnitTest<Task></code> exercises the constraints in milliseconds with no Spring context:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/TaskSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Domain unit tests for Task - constraints and defaults, no Spring context.
+ */</span>
+<span class="type">class</span> <span class="class">TaskSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<Task> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Task t = <span class="keyword">new</span> Task()
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a blank title is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a blank string is assigned directly (the map constructor would null it)</span><span class="delimiter">'</span></span>
+ Task t = <span class="keyword">new</span> Task()
+ t.title = <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a title longer than maxSize is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ Task t = <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">256</span>)
+
+ <span class="key">then</span>:
+ !t.validate()
+ t.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a new task defaults to not done</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ !<span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Something</span><span class="delimiter">'</span></span>).done
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid task validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Buy milk</span><span class="delimiter">'</span></span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_the_queries_behind_the_endpoints">Integration: the queries behind the endpoints</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The live-search action calls <code>Task.findAllByTitleIlike(…​)</code> and the list relies on the <code>dateCreated desc</code> mapping. An <code>@Integration</code> + <code>@Rollback</code> spec pins both against a real database:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/TaskIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full context against the in-memory H2 database.
+ * @Rollback isolates each method and provides an ambient session, so the
+ * GORM queries the TaskController relies on can be exercised directly.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">TaskIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">findAllByTitleIlike matches case-insensitively (the live-search query)</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Walk the dog</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%milk%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>]
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%MILK%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Buy Milk</span><span class="delimiter">'</span></span>]
+ Task.findAllByTitleIlike(<span class="string"><span class="delimiter">'</span><span class="content">%walk%</span><span class="delimiter">'</span></span>)*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Walk the dog</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">tasks list newest first per the domain mapping</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Older</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="predefined-type">Thread</span>.sleep(<span class="integer">20</span>)
+ <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Newer</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Task.list().first().title == <span class="string"><span class="delimiter">'</span><span class="content">Newer</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">toggling done persists</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Task t = <span class="keyword">new</span> Task(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Toggle</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ t.done = <span class="predefined-constant">true</span>
+ t.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">then</span>:
+ Task.get(t.id).done
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_browser_the_htmx_interactions_through_geb">Browser: the HTMX interactions through Geb</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>ContainerGebSpec</code> starts a Selenium-Chrome container via Testcontainers and drives the booted app. Each HTMX swap type is exercised: the create OOB prepend, the toggle and inline-edit <code>outerHTML</code> swaps, the live-search <code>innerHTML</code> swap, and the delete removal. <code>withConfirm(true)</code> answers the <code>hx-confirm</code> dialog on delete:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/TaskTrackerFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.plugin.geb.ContainerGebSpec</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+
+<span class="comment">/**
+ * Browser tests for the htmx interactions, driven by Geb 8 against a real
+ * booted application. ContainerGebSpec starts a Selenium-Chrome container via
+ * Testcontainers, so the only host requirement is a running Docker daemon.
+ *
+ * Each htmx swap type is exercised: the create OOB prepend, the toggle/edit
+ * outerHTML swaps, the live-search innerHTML swap, and the delete removal.
+ * @Rollback is not used (the endpoints commit); tests use unique titles so
+ * they stay independent of rows left by earlier feature methods.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">TaskTrackerFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
+
+ <span class="directive">private</span> <span class="type">void</span> addTaskThroughForm(<span class="predefined-type">String</span> taskTitle) {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).value(taskTitle)
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimiter">'</span><span class="content">submit</span><span class="delimiter">'</span></span>).click()
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(taskTitle) }
+ }
+
+ <span class="directive">private</span> rowFor(<span class="predefined-type">String</span> taskTitle) {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList li</span><span class="delimiter">'</span></span>).findAll { <span class="local-variable">it</span>.text().contains(taskTitle) }[<span class="integer">0</span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">the task page loads with the add form and search box</span><span class="delimiter">'</span></span>() {
+ <span class="key">when</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>:
+ title == <span class="string"><span class="delimiter">'</span><span class="content">HTMX Task Tracker</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">h1</span><span class="delimiter">'</span></span>).text() == <span class="string"><span class="delimiter">'</span><span class="content">Tasks</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">q</span><span class="delimiter">'</span></span>).size() == <span class="integer">1</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">adding a task prepends it to the list via an OOB swap and resets the form</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+
+ <span class="key">when</span>:
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">OOB swap task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the new row is at the top of the list</span><span class="delimiter">'</span></span>
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList li</span><span class="delimiter">'</span></span>, <span class="integer">0</span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">OOB swap task</span><span class="delimiter">'</span></span>) }
+
+ <span class="key">and</span>: <span class="string"><span class="delimiter">'</span><span class="content">the add form input was reset by the swap</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskFormContainer</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).value() == <span class [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">toggling a task applies the done styling</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">clicking the toggle button (first button in the row)</span><span class="delimiter">'</span></span>
+ rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>)[<span class="integer">0</span>].click()
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the swapped-in row carries the done class</span><span class="delimiter">'</span></span>
+ waitFor { rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Toggle styling task</span><span class="delimiter">'</span></span>).classes().contains(<span class="string"><span class="delimiter">'</span><span class="content">text-decoration-line-through</span><span class="delimiter">'</span></span>) }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">clicking a task opens the inline edit form and saving updates the title</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Editable task</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Long</span> id = Task.withNewTransaction { Task.findByTitle(<span class="string"><span class="delimiter">'</span><span class="content">Editable task</span><span class="delimiter">'</span></span>).id }
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">clicking the title button opens the edit form</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">title</span>: <span class="string"><span class="delimit [...]
+
+ <span class="key">then</span>:
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class= [...]
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">editing and saving (the row keeps its id across the swap)</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter [...]
+ <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="key">type</span>: <span class="string"><span class="delimite [...]
+
+ <span class="key">then</span>:
+ waitFor { <span class="error">$</span>(<span class="string"><span class="delimiter">"</span><span class="content">#task-</span><span class="inline"><span class="inline-delimiter">${</span>id<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Edited task title</span><span class="delimiter">'</span></span>) }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">live search filters the list via an innerHTML swap</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Searchable alpha unique</span><span class="delimiter">'</span></span>)
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Searchable beta unique</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">typing a term that matches only one task</span><span class="delimiter">'</span></span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">input</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">q</span><span class="delimiter">'</span></span>).value(<span class="string"><span class="delimiter">'</span><span class="content">alpha unique</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ waitFor {
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Searchable alpha unique</span><span class="delimiter">'</span></span>) &&
+ !<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Searchable beta unique</span><span class="delimiter">'</span></span>)
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">'</span><span class="content">deleting a task removes its row</span><span class="delimiter">'</span></span>() {
+ <span class="key">given</span>:
+ go <span class="string"><span class="delimiter">'</span><span class="content">/tasks</span><span class="delimiter">'</span></span>
+ addTaskThroughForm(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>)
+
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">confirming the delete</span><span class="delimiter">'</span></span>
+ withConfirm(<span class="predefined-constant">true</span>) {
+ rowFor(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>).find(<span class="string"><span class="delimiter">'</span><span class="content">button</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">aria-label</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="con [...]
+ }
+
+ <span class="key">then</span>:
+ waitFor { !<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">#taskList</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">Deletable task</span><span class="delimiter">'</span></span>) }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>A few disciplines keep these browser tests reliable:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>@Rollback</code> is <strong>not</strong> used - the HTMX endpoints commit, so each spec creates its fixture through the UI (or <code>withNewTransaction</code>) and uses unique titles so rows left by earlier feature methods do not interfere.</p>
+</li>
+<li>
+<p><code>waitFor { …​ }</code> wraps every assertion that follows an HTMX request, because the swap happens asynchronously after the AJAX round trip.</p>
+</li>
+<li>
+<p>Rows are targeted by their stable <code>#task-${id}</code> id, which survives the <code>outerHTML</code> swaps, rather than by text that changes mid-edit.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Run it all:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + Geb browser tests - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+ <div style="clear:both;margin-top:15px;"></div>
+
+ <div class="toc-item prev-left"><a href="../guide/spaComparison.html"><< <strong>12</strong><span>HTMX vs an SPA</span></a></div>
+
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span> >></a></div>
+
+ <div style="clear:both"></div>
+ </div>
+ </td>
+ <td id="col2">
+ <div class="local clearfix">
+ <div class="local-title" style="text-align: right"><a href="https://travis-ci.org/grails-guides/grails-htmx"><img src="https://travis-ci.org/grails-guides/grails-htmx.svg?branch=master" /></a></div>
+ <div class="local-title">
+ <a href="https://github.com/grails-guides/grails-htmx">
+ <svg height="35" class="octicon octicon-mark-github" viewBox="0 0 16 16" version="1.1" width="35" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.8 [...]
+ </div>
+ <div class="menu">
+ <div class="input-group">
+ <button href="#" onclick="document.getElementById('github-url').value='git@github.com:grails-guides/grails-htmx.git'" class="codeButton">SSH</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-htmx.git'" class="codeButton">HTTPS</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-htmx'" class="codeButton">Subversion</button>
+ </div>
+
+ <div class="input-group">
+ <!-- Target -->
+ <input id="github-url" value="git@github.com:grails-guides/grails-htmx.git" type="text" />
+
+ <!-- Trigger -->
+ <button class="clipbtn" type="button" data-clipboard-target="#github-url">
+
+ <img width="13" src="../img/clippy.svg" alt="Copy to clipboard">
+ </button>
+
+ </div>
+ <div class="input-group">
+ <a href="https://github.com/grails-guides/grails-htmx/archive/master.zip" class="downloadButton">Download ZIP</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ </tr>
+</table>
+
+<div id="footer">
+
+
+</div>
+
+<script type="text/javascript" src="../js/docs.js"></script>
+
+</body>
+</html>
diff --git a/guides/grails-htmx/8/guide/urlMappings.html b/guides/grails-htmx/8/guide/urlMappings.html
index 9cc0fe8bba6..0e52ef5051f 100644
--- a/guides/grails-htmx/8/guide/urlMappings.html
+++ b/guides/grails-htmx/8/guide/urlMappings.html
@@ -66,7 +66,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -140,6 +143,20 @@ function addJsClass() {
<div class="paragraph">
<p>This is also close to the Grails 8 <code>web</code> profile skeleton, which still shows explicit <code>"/$controller/$action?/$id?(.$format)?"</code> mappings in <code>UrlMappings.groovy</code>.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Because <code>/tasks</code> is shared by <code>index</code> and <code>create</code>, and <code>/tasks/$id</code> by <code>show</code>, <code>update</code>, and <code>delete</code>, Grails' reverse URL mapping cannot unambiguously pick a route from a controller+action pair alone - <code>createLink(controller: 'task', action: 'create')</code> falls back to the default <code>/task/create</code> convention, which no mapping serves, so the HTMX request 404s and nothing swaps. The partials [...]
+</div>
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>Files touched:</p>
</div>
diff --git a/guides/grails-htmx/8/index.html b/guides/grails-htmx/8/index.html
index 8ac99c79cfe..09289ac43b3 100644
--- a/guides/grails-htmx/8/index.html
+++ b/guides/grails-htmx/8/index.html
@@ -131,7 +131,9 @@
<div class="toc-item" style="margin-left:0px"><a href="./guide/spaComparison.html"><strong>12</strong><span>HTMX vs an SPA</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/testing.html"><strong>13</strong><span>Testing the HTMX UI</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>14</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-multi-module/8/guide/index.html b/guides/grails-multi-module/8/guide/index.html
index 9a09136c856..09a0554303b 100644
--- a/guides/grails-multi-module/8/guide/index.html
+++ b/guides/grails-multi-module/8/guide/index.html
@@ -1033,6 +1033,283 @@ subprojects {
</li>
</ul>
</div>
+<div class="sect1">
+<h2 id="_shared_core_the_domain_and_data_service">shared-core: the domain and data service</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The plugin owns the model, so its tests own the model’s behaviour. Both webapps inherit a tested <code>Book</code> and <code>BookService</code> rather than re-testing them:</p>
+</div>
+<div class="listingblock">
+<div class="title">shared-core/src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit test for the Book domain that lives in the shared-core plugin.
+ * Proving the domain's constraints here means both webapps inherit a
+ * tested model - they never redefine it.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<<span class="predefined-type">Book</span>> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title and isbn are required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>()
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must match the ISBN pattern and be unique</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">First</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>).save(<span c [...]
+
+ <span class="key">expect</span>:
+ !<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Bad</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">nope</span><span class="delimiter">'</span></span>).validate()
+
+ <span class="key">and</span>:
+ <span class="predefined-type">Book</span> dup = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dup</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ !dup.validate()
+ dup.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">shared-core/src/test/groovy/example/BookServiceSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">grails.testing.services.ServiceUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit test for the @Service(Book) data service in shared-core. Both
+ * webapps inject this same BookService bean, so testing its query shape
+ * once here covers the admin and customer modules' data access.
+ */</span>
+<span class="type">class</span> <span class="class">BookServiceSpec</span> <span class="directive">extends</span> Specification
+ <span class="directive">implements</span> ServiceUnitTest<BookService>, DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [<span class="predefined-type">Book</span>] }
+
+ <span class="type">void</span> setup() {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Old</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>, <span class= [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Recent</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>, <span class [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">findByIsbn returns the matching book</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>).title == <span class="string"><span class="delimiter">'</span><span class="content">Recent</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">count reflects persisted books</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.count() == <span class="integer">2</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">countByPublishedOnGreaterThanEquals filters by date</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.countByPublishedOnGreaterThanEquals(<span class="predefined-type">Date</span>.parse(<span class="string"><span class="delimiter">'</span><span class="content">yyyy-MM-dd</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">2000-01-01</span><span class="delimiter">'</span></span>)) == <span class="integer">1</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_webapp_admin_the_rest_surface_over_real_http">webapp-admin: the REST surface over real HTTP</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The admin <code>BookController</code> is a <code>RestfulController</code>, so the admin module adds a <code>resources</code> URL mapping to route the REST verbs, then drives it with a functional spec. The <code>Book</code> it persists comes from the plugin - proving the shared model works end to end in a booted app:</p>
+</div>
+<div class="listingblock">
+<div class="title">webapp-admin/grails-app/controllers/example/UrlMappings.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="type">class</span> <span class="class">UrlMappings</span> {
+ <span class="directive">static</span> mappings = {
+ <span class="comment">// REST resource mapping so the admin BookController (a RestfulController)</span>
+ <span class="comment">// routes GET/POST/PUT/DELETE on /books to its CRUD actions.</span>
+ <span class="string"><span class="delimiter">"</span><span class="content">/books</span><span class="delimiter">"</span></span>(<span class="key">resources</span>: <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>namespace</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span clas [...]
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span class="content">?(.</span><span class="inline"><span class="inline-delimiter">$</span>format</span><span class [...]
+ constraints {
+ <span class="comment">// apply constraints here</span>
+ }
+ }
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">"</span><span class="content">/index</span><span class="delimiter">"</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">500</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/error</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">404</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/notFound</span><span class="delimiter">'</span></span>)
+
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">webapp-admin/src/integration-test/groovy/admin/AdminBookFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> admin
+
+<span class="keyword">import</span> <span class="include">example.Book</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonOutput</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional test for the admin webapp's REST CRUD over real HTTP. The
+ * Book domain and BookService it persists through both come from the
+ * shared-core plugin - this proves the cross-module reuse works end to end
+ * in a booted app. @Rollback is not used (the endpoint commits), so the
+ * fixture is read back inside withNewTransaction.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">AdminBookFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="directive">private</span> <span class="predefined-type">URI</span> uri(<span class="predefined-type">String</span> path) { <span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inlin [...]
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /book creates a shared-core Book and returns 201</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">412</span>])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">201</span>
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)?.title == <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span> }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /book lists the shared-core Books as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ }
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books.json</span><span class="delimiter">'</span></span>)).GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ <span class="keyword">def</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /book with a malformed isbn returns 422</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Bad</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">422</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_webapp_customer_the_read_only_catalog">webapp-customer: the read-only catalog</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The customer functional spec drives the hand-rolled <code>CatalogController</code>, which injects the same plugin <code>BookService</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">webapp-customer/src/integration-test/groovy/customer/CatalogFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> customer
+
+<span class="keyword">import</span> <span class="include">example.Book</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional test for the customer webapp's read-only catalog over real
+ * HTTP. The CatalogController injects the shared-core BookService and the
+ * Book domain, proving the same shared module backs the customer app too.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">CatalogFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">412</span>).save( [...]
+ }
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /catalog lists the shared-core Books as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(<span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="content">/catalog.json</span><span class="delimiter">"</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ <span class="keyword">def</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
<div class="paragraph">
<p>Run them granularly during development:</p>
</div>
@@ -1082,6 +1359,8 @@ subprojects {
</li>
</ul>
</div>
+</div>
+</div>
<h1 id="extractingPlugin">9 Extracting a Plugin From a Monolith</h1>
diff --git a/guides/grails-multi-module/8/guide/single.html b/guides/grails-multi-module/8/guide/single.html
index 9a09136c856..09a0554303b 100644
--- a/guides/grails-multi-module/8/guide/single.html
+++ b/guides/grails-multi-module/8/guide/single.html
@@ -1033,6 +1033,283 @@ subprojects {
</li>
</ul>
</div>
+<div class="sect1">
+<h2 id="_shared_core_the_domain_and_data_service">shared-core: the domain and data service</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The plugin owns the model, so its tests own the model’s behaviour. Both webapps inherit a tested <code>Book</code> and <code>BookService</code> rather than re-testing them:</p>
+</div>
+<div class="listingblock">
+<div class="title">shared-core/src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit test for the Book domain that lives in the shared-core plugin.
+ * Proving the domain's constraints here means both webapps inherit a
+ * tested model - they never redefine it.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<<span class="predefined-type">Book</span>> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title and isbn are required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>()
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must match the ISBN pattern and be unique</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">First</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>).save(<span c [...]
+
+ <span class="key">expect</span>:
+ !<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Bad</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">nope</span><span class="delimiter">'</span></span>).validate()
+
+ <span class="key">and</span>:
+ <span class="predefined-type">Book</span> dup = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dup</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ !dup.validate()
+ dup.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">shared-core/src/test/groovy/example/BookServiceSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">grails.testing.services.ServiceUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit test for the @Service(Book) data service in shared-core. Both
+ * webapps inject this same BookService bean, so testing its query shape
+ * once here covers the admin and customer modules' data access.
+ */</span>
+<span class="type">class</span> <span class="class">BookServiceSpec</span> <span class="directive">extends</span> Specification
+ <span class="directive">implements</span> ServiceUnitTest<BookService>, DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [<span class="predefined-type">Book</span>] }
+
+ <span class="type">void</span> setup() {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Old</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>, <span class= [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Recent</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>, <span class [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">findByIsbn returns the matching book</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>).title == <span class="string"><span class="delimiter">'</span><span class="content">Recent</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">count reflects persisted books</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.count() == <span class="integer">2</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">countByPublishedOnGreaterThanEquals filters by date</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.countByPublishedOnGreaterThanEquals(<span class="predefined-type">Date</span>.parse(<span class="string"><span class="delimiter">'</span><span class="content">yyyy-MM-dd</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">2000-01-01</span><span class="delimiter">'</span></span>)) == <span class="integer">1</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_webapp_admin_the_rest_surface_over_real_http">webapp-admin: the REST surface over real HTTP</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The admin <code>BookController</code> is a <code>RestfulController</code>, so the admin module adds a <code>resources</code> URL mapping to route the REST verbs, then drives it with a functional spec. The <code>Book</code> it persists comes from the plugin - proving the shared model works end to end in a booted app:</p>
+</div>
+<div class="listingblock">
+<div class="title">webapp-admin/grails-app/controllers/example/UrlMappings.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="type">class</span> <span class="class">UrlMappings</span> {
+ <span class="directive">static</span> mappings = {
+ <span class="comment">// REST resource mapping so the admin BookController (a RestfulController)</span>
+ <span class="comment">// routes GET/POST/PUT/DELETE on /books to its CRUD actions.</span>
+ <span class="string"><span class="delimiter">"</span><span class="content">/books</span><span class="delimiter">"</span></span>(<span class="key">resources</span>: <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>namespace</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span clas [...]
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span class="content">?(.</span><span class="inline"><span class="inline-delimiter">$</span>format</span><span class [...]
+ constraints {
+ <span class="comment">// apply constraints here</span>
+ }
+ }
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">"</span><span class="content">/index</span><span class="delimiter">"</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">500</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/error</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">404</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/notFound</span><span class="delimiter">'</span></span>)
+
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">webapp-admin/src/integration-test/groovy/admin/AdminBookFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> admin
+
+<span class="keyword">import</span> <span class="include">example.Book</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonOutput</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional test for the admin webapp's REST CRUD over real HTTP. The
+ * Book domain and BookService it persists through both come from the
+ * shared-core plugin - this proves the cross-module reuse works end to end
+ * in a booted app. @Rollback is not used (the endpoint commits), so the
+ * fixture is read back inside withNewTransaction.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">AdminBookFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="directive">private</span> <span class="predefined-type">URI</span> uri(<span class="predefined-type">String</span> path) { <span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inlin [...]
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /book creates a shared-core Book and returns 201</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">412</span>])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">201</span>
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)?.title == <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span> }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /book lists the shared-core Books as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ }
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books.json</span><span class="delimiter">'</span></span>)).GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ <span class="keyword">def</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /book with a malformed isbn returns 422</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Bad</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">422</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_webapp_customer_the_read_only_catalog">webapp-customer: the read-only catalog</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The customer functional spec drives the hand-rolled <code>CatalogController</code>, which injects the same plugin <code>BookService</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">webapp-customer/src/integration-test/groovy/customer/CatalogFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> customer
+
+<span class="keyword">import</span> <span class="include">example.Book</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional test for the customer webapp's read-only catalog over real
+ * HTTP. The CatalogController injects the shared-core BookService and the
+ * Book domain, proving the same shared module backs the customer app too.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">CatalogFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">412</span>).save( [...]
+ }
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /catalog lists the shared-core Books as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(<span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="content">/catalog.json</span><span class="delimiter">"</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ <span class="keyword">def</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
<div class="paragraph">
<p>Run them granularly during development:</p>
</div>
@@ -1082,6 +1359,8 @@ subprojects {
</li>
</ul>
</div>
+</div>
+</div>
<h1 id="extractingPlugin">9 Extracting a Plugin From a Monolith</h1>
diff --git a/guides/grails-multi-module/8/guide/testingPerModule.html b/guides/grails-multi-module/8/guide/testingPerModule.html
index 87228610791..f1cb04f613c 100644
--- a/guides/grails-multi-module/8/guide/testingPerModule.html
+++ b/guides/grails-multi-module/8/guide/testingPerModule.html
@@ -115,6 +115,283 @@ function addJsClass() {
</li>
</ul>
</div>
+<div class="sect1">
+<h2 id="_shared_core_the_domain_and_data_service">shared-core: the domain and data service</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The plugin owns the model, so its tests own the model’s behaviour. Both webapps inherit a tested <code>Book</code> and <code>BookService</code> rather than re-testing them:</p>
+</div>
+<div class="listingblock">
+<div class="title">shared-core/src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DomainUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit test for the Book domain that lives in the shared-core plugin.
+ * Proving the domain's constraints here means both webapps inherit a
+ * tested model - they never redefine it.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<<span class="predefined-type">Book</span>> {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title and isbn are required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>()
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must match the ISBN pattern and be unique</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">First</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>).save(<span c [...]
+
+ <span class="key">expect</span>:
+ !<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Bad</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">nope</span><span class="delimiter">'</span></span>).validate()
+
+ <span class="key">and</span>:
+ <span class="predefined-type">Book</span> dup = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dup</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ !dup.validate()
+ dup.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a valid book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>).validate()
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">shared-core/src/test/groovy/example/BookServiceSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">grails.testing.services.ServiceUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * Unit test for the @Service(Book) data service in shared-core. Both
+ * webapps inject this same BookService bean, so testing its query shape
+ * once here covers the admin and customer modules' data access.
+ */</span>
+<span class="type">class</span> <span class="class">BookServiceSpec</span> <span class="directive">extends</span> Specification
+ <span class="directive">implements</span> ServiceUnitTest<BookService>, DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [<span class="predefined-type">Book</span>] }
+
+ <span class="type">void</span> setup() {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Old</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>, <span class= [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Recent</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>, <span class [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">findByIsbn returns the matching book</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>).title == <span class="string"><span class="delimiter">'</span><span class="content">Recent</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">count reflects persisted books</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.count() == <span class="integer">2</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">countByPublishedOnGreaterThanEquals filters by date</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ service.countByPublishedOnGreaterThanEquals(<span class="predefined-type">Date</span>.parse(<span class="string"><span class="delimiter">'</span><span class="content">yyyy-MM-dd</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">2000-01-01</span><span class="delimiter">'</span></span>)) == <span class="integer">1</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_webapp_admin_the_rest_surface_over_real_http">webapp-admin: the REST surface over real HTTP</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The admin <code>BookController</code> is a <code>RestfulController</code>, so the admin module adds a <code>resources</code> URL mapping to route the REST verbs, then drives it with a functional spec. The <code>Book</code> it persists comes from the plugin - proving the shared model works end to end in a booted app:</p>
+</div>
+<div class="listingblock">
+<div class="title">webapp-admin/grails-app/controllers/example/UrlMappings.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="type">class</span> <span class="class">UrlMappings</span> {
+ <span class="directive">static</span> mappings = {
+ <span class="comment">// REST resource mapping so the admin BookController (a RestfulController)</span>
+ <span class="comment">// routes GET/POST/PUT/DELETE on /books to its CRUD actions.</span>
+ <span class="string"><span class="delimiter">"</span><span class="content">/books</span><span class="delimiter">"</span></span>(<span class="key">resources</span>: <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>namespace</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span clas [...]
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span class="content">?(.</span><span class="inline"><span class="inline-delimiter">$</span>format</span><span class [...]
+ constraints {
+ <span class="comment">// apply constraints here</span>
+ }
+ }
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">"</span><span class="content">/index</span><span class="delimiter">"</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">500</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/error</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">404</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/notFound</span><span class="delimiter">'</span></span>)
+
+ }
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">webapp-admin/src/integration-test/groovy/admin/AdminBookFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> admin
+
+<span class="keyword">import</span> <span class="include">example.Book</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonOutput</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional test for the admin webapp's REST CRUD over real HTTP. The
+ * Book domain and BookService it persists through both come from the
+ * shared-core plugin - this proves the cross-module reuse works end to end
+ * in a booted app. @Rollback is not used (the endpoint commits), so the
+ * fixture is read back inside withNewTransaction.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">AdminBookFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="directive">private</span> <span class="predefined-type">URI</span> uri(<span class="predefined-type">String</span> path) { <span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inlin [...]
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /book creates a shared-core Book and returns 201</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">412</span>])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">201</span>
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)?.title == <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span> }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /book lists the shared-core Books as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ }
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books.json</span><span class="delimiter">'</span></span>)).GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ <span class="keyword">def</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /book with a malformed isbn returns 422</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Bad</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(uri(<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">422</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_webapp_customer_the_read_only_catalog">webapp-customer: the read-only catalog</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The customer functional spec drives the hand-rolled <code>CatalogController</code>, which injects the same plugin <code>BookService</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">webapp-customer/src/integration-test/groovy/customer/CatalogFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> customer
+
+<span class="keyword">import</span> <span class="include">example.Book</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional test for the customer webapp's read-only catalog over real
+ * HTTP. The CatalogController injects the shared-core BookService and the
+ * Book domain, proving the same shared module backs the customer app too.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">CatalogFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Dune</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">412</span>).save( [...]
+ }
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /catalog lists the shared-core Books as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = client.send(
+ HttpRequest.newBuilder(<span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="content">/catalog.json</span><span class="delimiter">"</span></span>))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Accept</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .GET().build(),
+ HttpResponse.BodyHandlers.ofString())
+ <span class="keyword">def</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body())
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+ json*.isbn.contains(<span class="string"><span class="delimiter">'</span><span class="content">9780441013593</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
<div class="paragraph">
<p>Run them granularly during development:</p>
</div>
@@ -163,6 +440,8 @@ function addJsClass() {
<p>webapp-admin/src/integration-test/groovy/**</p>
</li>
</ul>
+</div>
+</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/bulkCreate.html b/guides/grails-rest-library/8/guide/bulkCreate.html
index 697bc7822e2..ac6861e4937 100644
--- a/guides/grails-rest-library/8/guide/bulkCreate.html
+++ b/guides/grails-rest-library/8/guide/bulkCreate.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/controllers.html b/guides/grails-rest-library/8/guide/controllers.html
index 3b8c96ab968..10ede1d7cab 100644
--- a/guides/grails-rest-library/8/guide/controllers.html
+++ b/guides/grails-rest-library/8/guide/controllers.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/createApp.html b/guides/grails-rest-library/8/guide/createApp.html
index 73843bdcff3..d9689681069 100644
--- a/guides/grails-rest-library/8/guide/createApp.html
+++ b/guides/grails-rest-library/8/guide/createApp.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/domainModel.html b/guides/grails-rest-library/8/guide/domainModel.html
index 9ffaa315a1b..3b55be997a6 100644
--- a/guides/grails-rest-library/8/guide/domainModel.html
+++ b/guides/grails-rest-library/8/guide/domainModel.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -210,13 +213,9 @@ function addJsClass() {
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
<span class="keyword">import</span> <span class="include">grails.util.Environment</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.Logger</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.LoggerFactory</span>
<span class="type">class</span> <span class="class">BootStrap</span> {
- <span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">Logger</span> log = LoggerFactory.getLogger(BootStrap)
-
Closure init = { servletContext ->
<span class="keyword">if</span> (Environment.current == Environment.PRODUCTION) {
@@ -267,7 +266,7 @@ function addJsClass() {
</ul>
</div>
<div class="paragraph">
-<p>The <code>@Transactional</code> annotation on the <code>init</code> closure means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state.</p>
+<p>The <code>Author.withTransaction { }</code> wrapper means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state - and a bare <code>save()</code> in <code>BootStrap</code> outside any transaction may not flush at all.</p>
</div>
diff --git a/guides/grails-rest-library/8/guide/gettingStarted.html b/guides/grails-rest-library/8/guide/gettingStarted.html
index 4f08dd28af9..738687eda15 100644
--- a/guides/grails-rest-library/8/guide/gettingStarted.html
+++ b/guides/grails-rest-library/8/guide/gettingStarted.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/helpWithGrails.html b/guides/grails-rest-library/8/guide/helpWithGrails.html
index 7d055ab3c82..4a509d0710a 100644
--- a/guides/grails-rest-library/8/guide/helpWithGrails.html
+++ b/guides/grails-rest-library/8/guide/helpWithGrails.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>12 Do you need help with Grails?</title>
+ <title>13 Do you need help with Grails?</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -81,7 +84,7 @@ function addJsClass() {
<div id="main" class="corner-all">
- <div class="toc-item prev-left"><a href="../guide/runningTheApp.html"><< <strong>11</strong><span>Running the Application</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/runningTheApp.html"><< <strong>12</strong><span>Running the Application</span></a></div>
@@ -91,7 +94,7 @@ function addJsClass() {
-<h1 id="helpWithGrails">12 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/helpWithGrails.adoc"'>
@@ -131,7 +134,7 @@ function addJsClass() {
<div style="clear:both;margin-top:15px;"></div>
- <div class="toc-item prev-left"><a href="../guide/runningTheApp.html"><< <strong>11</strong><span>Running the Application</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/runningTheApp.html"><< <strong>12</strong><span>Running the Application</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-rest-library/8/guide/index.html b/guides/grails-rest-library/8/guide/index.html
index 486ab343c22..180fc99b188 100644
--- a/guides/grails-rest-library/8/guide/index.html
+++ b/guides/grails-rest-library/8/guide/index.html
@@ -131,9 +131,11 @@
<div class="toc-item" style="margin-left:0px"><a href="#versioning"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#runningTheApp"><strong>11</strong><span>Running the Application</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>11</strong><span>Testing the API</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>12</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#runningTheApp"><strong>12</strong><span>Running the Application</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -392,13 +394,9 @@ curl -s http://localhost:8080/v1/books | jq</code></pre>
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
<span class="keyword">import</span> <span class="include">grails.util.Environment</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.Logger</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.LoggerFactory</span>
<span class="type">class</span> <span class="class">BootStrap</span> {
- <span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">Logger</span> log = LoggerFactory.getLogger(BootStrap)
-
Closure init = { servletContext ->
<span class="keyword">if</span> (Environment.current == Environment.PRODUCTION) {
@@ -449,7 +447,7 @@ curl -s http://localhost:8080/v1/books | jq</code></pre>
</ul>
</div>
<div class="paragraph">
-<p>The <code>@Transactional</code> annotation on the <code>init</code> closure means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state.</p>
+<p>The <code>Author.withTransaction { }</code> wrapper means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state - and a bare <code>save()</code> in <code>BootStrap</code> outside any transaction may not flush at all.</p>
</div>
@@ -721,6 +719,7 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Transactional</span>
<span class="keyword">import</span> <span class="include">grails.rest.RestfulController</span>
+<span class="keyword">import</span> <span class="include">org.springframework.context.MessageSource</span>
<span class="keyword">import</span> <span class="include">org.springframework.http.HttpStatus</span>
<span class="keyword">import</span> <span class="include">org.springframework.validation.FieldError</span>
@@ -728,6 +727,8 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
<span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>]
+ MessageSource messageSource
+
BookController() {
<span class="local-variable">super</span>(<span class="predefined-type">Book</span>)
}
@@ -796,7 +797,7 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">Object</span>> payload = [
object : error.objectName,
code : error.code,
- <span class="key">message</span>: message(<span class="key">error</span>: error)
+ <span class="key">message</span>: messageSource.getMessage(error, request.locale)
]
<span class="keyword">if</span> (error <span class="keyword">instanceof</span> FieldError) {
payload.field = error.field
@@ -1022,7 +1023,423 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
</div>
-<h1 id="runningTheApp">11 Running the Application</h1>
+<h1 id="testing">11 Testing the API</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The library API ships with a layered Spock suite: fast domain and controller unit tests, <code>@Integration</code> tests against a real database, and functional HTTP tests that drive the JSON endpoints end to end. The integration and functional layers run against a Testcontainers-managed PostgreSQL database, so a Docker daemon is the only host requirement.</p>
+</div>
+<div class="sect1">
+<h2 id="_test_dependencies">Test dependencies</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Testcontainers artifacts are not in the Grails BOM, so they need an explicit <code>testcontainers-bom</code> to resolve a version. The web testing support is required for <code>ControllerUnitTest</code> even in a <code>rest-api</code> profile app:</p>
+</div>
+<div class="listingblock">
+<div class="title">build.gradle (test dependencies)</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy">testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-datamapping</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-views-gson</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-web</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.spockframework:spock-core</span><span class="delimiter">"</span></span>
+testImplementation platform(<span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:testcontainers-bom:1.20.4</span><span class="delimiter">"</span></span>)
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:postgresql</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:spock</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:testcontainers</span><span class="delimiter">"</span></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Because this app uses the database-migration plugin, an empty <code>changelog.groovy</code> means GORM will not auto-create the schema in the test environment. The test profile therefore turns the migration off and lets GORM create the schema directly:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/resources/application-test.yml</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">dataSource</span>:
+ <span class="key">url</span>: <span class="string"><span class="content">jdbc:tc:postgresql:12:///postgres</span></span>
+ <span class="key">driverClassName</span>: <span class="string"><span class="content">org.testcontainers.jdbc.ContainerDatabaseDriver</span></span>
+ <span class="key">dbCreate</span>: <span class="string"><span class="content">create-drop</span></span>
+<span class="key">grails</span>:
+ <span class="key">plugin</span>:
+ <span class="key">databasemigration</span>:
+ <span class="key">updateOnStart</span>: <span class="string"><span class="content">false</span></span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_unit_domain_constraints_and_controller_paging">Unit: domain constraints and controller paging</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DataTest</code> registers the in-memory datastore for <code>Author</code> and <code>Book</code> so constraint logic runs in milliseconds with no Spring context. <code>Book</code> <code>belongsTo</code> <code>Author</code>, so both classes are mocked:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Book. DataTest mocks both Book and its
+ * owning Author so the belongsTo association can be satisfied without a
+ * Spring context or a real database.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>] }
+
+ <span class="directive">private</span> <span class="predefined-type">Book</span> bookWith(<span class="predefined-type">Map</span> overrides) {
+ Author author = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Author</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>([<span class="key">author</span>: author, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">A Title</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a fully populated book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith([:]).validate()
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">author is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">No Author</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">author</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">title</span>: <span class="predefined-constant">null</span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must match the ISBN pattern</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must be unique</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> dup = bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !dup.validate()
+ dup.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">pageCount #pageCount is #valid</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith(<span class="key">pageCount</span>: pageCount).validate() == valid
+
+ <span class="key">where</span>:
+ pageCount || valid
+ <span class="predefined-constant">null</span> || <span class="predefined-constant">true</span>
+ <span class="integer">1</span> || <span class="predefined-constant">true</span>
+ <span class="integer">500</span> || <span class="predefined-constant">true</span>
+ <span class="integer">0</span> || <span class="predefined-constant">false</span>
+ -<span class="integer">5</span> || <span class="predefined-constant">false</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <code>RestfulController</code> pagination clamping (default 25, hard cap 100, negative treated as default) is pinned with a <code>ControllerUnitTest</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookControllerSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">grails.testing.web.controllers.ControllerUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Controller unit test for the pagination clamping the custom index action
+ * applies before it queries. No Spring context, no real database.
+ */</span>
+<span class="type">class</span> <span class="class">BookControllerSpec</span> <span class="directive">extends</span> Specification
+ <span class="directive">implements</span> ControllerUnitTest<BookController>, DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>] }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">index clamps max #requested to #expected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ controller.index(requested)
+
+ <span class="key">then</span>:
+ controller.params.max == expected
+
+ <span class="key">where</span>:
+ requested || expected
+ <span class="integer">500</span> || <span class="integer">100</span> <span class="comment">// capped at 100</span>
+ <span class="integer">10</span> || <span class="integer">10</span> <span class="comment">// within range, untouched</span>
+ <span class="predefined-constant">null</span> || <span class="integer">25</span> <span class="comment">// default</span>
+ -<span class="integer">5</span> || <span class="integer">25</span> <span class="comment">// negative treated as default</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">index never produces a negative offset</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ controller.params.offset = -<span class="integer">10</span>
+
+ <span class="key">when</span>:
+ controller.index(<span class="integer">25</span>)
+
+ <span class="key">then</span>:
+ controller.params.offset == <span class="integer">0</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_relationships_against_a_real_database">Integration: relationships against a real database</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Integration</code> with <code>@Rollback</code> boots the full context and isolates each method. <code>BootStrap</code> seeds four books outside production, so these specs use ISBNs that do not collide with the seed set and filter queries by an author they create:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/BookIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full Spring context against the Testcontainers
+ * PostgreSQL database. @Rollback isolates each method, so a bare GORM call
+ * runs inside an ambient session.
+ *
+ * BootStrap seeds four books outside production, so these specs use ISBNs
+ * that do not collide with the seed set and filter queries by an author
+ * they create themselves.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">BookIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">books are filtered by author with a where query</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author tolkien = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Tolkien</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ Author leguin = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Le Guin</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: tolkien, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">TT Book</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9783000000010</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: leguin, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">LG Book</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9783000000027</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+
+ <span class="key">when</span>:
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> tolkienBooks = <span class="predefined-type">Book</span>.where { author.id == tolkien.id }.list()
+
+ <span class="key">then</span>:
+ tolkienBooks.size() == <span class="integer">1</span>
+ tolkienBooks.first().title == <span class="string"><span class="delimiter">'</span><span class="content">TT Book</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">pagination returns at most the requested page size</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Prolific</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ (<span class="integer">1</span>..<span class="integer">5</span>).each { <span class="type">int</span> i ->
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">"</span><span class="content">Paged </span><span class="inline"><span class="inline-delimiter">${</span>i<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>, <span class="key">isbn</span>: <span class="predefined-type">String</span>.format(<span cl [...]
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
+
+ <span class="key">when</span>:
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> firstPage = <span class="predefined-type">Book</span>.where { author.id == a.id }.list(<span class="key">max</span>: <span class="integer">2</span>, <span class="key">offset</span>: <span class="integer">0</span>, <span class="key">sort</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>, <span class="key">or [...]
+
+ <span class="key">then</span>:
+ firstPage.size() == <span class="integer">2</span>
+ firstPage*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Paged 1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Paged 2</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author's books collection reflects persisted books</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Author</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">One</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9785000000019</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>))
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Two</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9785000000026</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>))
+ a.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Author.get(a.id).books.size() == <span class="integer">2</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_functional_the_rest_surface_over_real_http">Functional: the REST surface over real HTTP</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The functional spec sends real requests with <code>java.net.http.HttpClient</code> against the booted app (port injected via <code>@Value('${local.server.port}')</code>). It asserts the paginated envelope, the page-size clamp, and - most importantly - the all-or-nothing <code>bulkCreate</code> contract: a request with one invalid entry returns <code>422</code> and persists <strong>nothing</strong>. <code>@Rollback</code> is not used (the endpoints commit), so the fixture is created an [...]
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/BookFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonOutput</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional tests drive the real REST/JSON surface over HTTP with
+ * java.net.http.HttpClient. @Rollback is deliberately NOT used: the
+ * endpoints commit, so the fixture is seeded (and read back) inside
+ * withNewTransaction blocks. BootStrap data is not populated in the
+ * @Integration context, so each spec owns its fixture.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">BookFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="predefined-type">Long</span> authorId
+
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ Author a = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span>) ?: <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ authorId = a.id
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9781111111113</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Seeded One</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9781111111113</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span [...]
+ }
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9782222222226</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Seeded Two</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9782222222226</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span [...]
+ }
+ }
+ }
+
+ <span class="directive">private</span> <span class="predefined-type">URI</span> uri(<span class="predefined-type">String</span> path) { <span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inlin [...]
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> getJson(<span class="predefined-type">String</span> path) {
+ client.send(HttpRequest.newBuilder(uri(path)).GET().build(), HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> postJson(<span class="predefined-type">String</span> path, <span class="predefined-type">String</span> body) {
+ client.send(HttpRequest.newBuilder(uri(path))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/books returns a paginated JSON envelope</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.containsKey(<span class="string"><span class="delimiter">'</span><span class="content">page</span><span class="delimiter">'</span></span>)
+ json.containsKey(<span class="string"><span class="delimiter">'</span><span class="content">pageSize</span><span class="delimiter">'</span></span>)
+ json.total >= <span class="integer">2</span>
+ json.items.size() >= <span class="integer">2</span>
+ json.items.every { <span class="local-variable">it</span>.title && <span class="local-variable">it</span>.isbn && <span class="local-variable">it</span>.author?.name }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/books?max= clamps the page size to 100</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books?max=500</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.pageSize == <span class="integer">100</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /v1/books/bulk creates every book and returns 201</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Two Towers</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928203</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">416</span>, <span class="key">author</span>: [<span class="key">id</span>: au [...]
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Return of the King</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928197</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">432</span>, <span class="key">author</span>: [<span class="key">id</span>: au [...]
+ ])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = postJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books/bulk</span><span class="delimiter">'</span></span>, body)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">201</span>
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928203</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span> && <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928197</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /v1/books/bulk rolls back entirely when any entry is invalid</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">one valid and one invalid entry in the same request</span><span class="delimiter">'</span></span>
+ <span class="type">long</span> before = <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.count() }
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Would Be Valid</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000086</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>, <span class="key">author</span>: [<span class="key">id</span>: authorId]],
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>, <span class="key">author</span>: [<span class="key">id</span>: authorId]]
+ ])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = postJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books/bulk</span><span class="delimiter">'</span></span>, body)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">a 422 reports the failing index and NOTHING is persisted</span><span class="delimiter">'</span></span>
+ resp.statusCode() == <span class="integer">422</span>
+ json.books.size() == <span class="integer">1</span>
+ json.books.first().index == <span class="integer">1</span>
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.count() } == before
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780000000086</span><span class="delimiter">'</span></span>) == <span class="predefined-constant">null</span> }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/authors returns the authors as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/authors</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.total >= <span class="integer">1</span>
+ json.items.any { <span class="local-variable">it</span>.name == <span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span> }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Run the suite:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + functional - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+<h1 id="runningTheApp">12 Running the Application</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/runningTheApp.adoc"'>
@@ -1077,7 +1494,7 @@ curl -s -X POST http://localhost:8080/v1/books/bulk \
</div>
-<h1 id="helpWithGrails">12 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-rest-library/8/guide/jsonViews.html b/guides/grails-rest-library/8/guide/jsonViews.html
index 9956ef3bdc1..2c6a1ccd64b 100644
--- a/guides/grails-rest-library/8/guide/jsonViews.html
+++ b/guides/grails-rest-library/8/guide/jsonViews.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/pages/bootstrapData.html b/guides/grails-rest-library/8/guide/pages/bootstrapData.html
index 0e6f0e4ff13..04117f74083 100644
--- a/guides/grails-rest-library/8/guide/pages/bootstrapData.html
+++ b/guides/grails-rest-library/8/guide/pages/bootstrapData.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -111,13 +114,9 @@ function addJsClass() {
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
<span class="keyword">import</span> <span class="include">grails.util.Environment</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.Logger</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.LoggerFactory</span>
<span class="type">class</span> <span class="class">BootStrap</span> {
- <span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">Logger</span> log = LoggerFactory.getLogger(BootStrap)
-
Closure init = { servletContext ->
<span class="keyword">if</span> (Environment.current == Environment.PRODUCTION) {
@@ -168,7 +167,7 @@ function addJsClass() {
</ul>
</div>
<div class="paragraph">
-<p>The <code>@Transactional</code> annotation on the <code>init</code> closure means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state.</p>
+<p>The <code>Author.withTransaction { }</code> wrapper means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state - and a bare <code>save()</code> in <code>BootStrap</code> outside any transaction may not flush at all.</p>
</div>
diff --git a/guides/grails-rest-library/8/guide/pages/download.html b/guides/grails-rest-library/8/guide/pages/download.html
index b33bdff78b8..acc422c1ac3 100644
--- a/guides/grails-rest-library/8/guide/pages/download.html
+++ b/guides/grails-rest-library/8/guide/pages/download.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/pages/howto.html b/guides/grails-rest-library/8/guide/pages/howto.html
index 1e6064884fe..73920d23b3f 100644
--- a/guides/grails-rest-library/8/guide/pages/howto.html
+++ b/guides/grails-rest-library/8/guide/pages/howto.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/pages/requirements.html b/guides/grails-rest-library/8/guide/pages/requirements.html
index 32da7110a85..f3871f0f7d7 100644
--- a/guides/grails-rest-library/8/guide/pages/requirements.html
+++ b/guides/grails-rest-library/8/guide/pages/requirements.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/pages/whatYouWillBuild.html b/guides/grails-rest-library/8/guide/pages/whatYouWillBuild.html
index c7c5af738d1..dd80c0bf73e 100644
--- a/guides/grails-rest-library/8/guide/pages/whatYouWillBuild.html
+++ b/guides/grails-rest-library/8/guide/pages/whatYouWillBuild.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/pagination.html b/guides/grails-rest-library/8/guide/pagination.html
index df2b0e9f685..04d17467152 100644
--- a/guides/grails-rest-library/8/guide/pagination.html
+++ b/guides/grails-rest-library/8/guide/pagination.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/runningTheApp.html b/guides/grails-rest-library/8/guide/runningTheApp.html
index b55cf0199e7..7f9b5ea41e8 100644
--- a/guides/grails-rest-library/8/guide/runningTheApp.html
+++ b/guides/grails-rest-library/8/guide/runningTheApp.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>11 Running the Application</title>
+ <title>12 Running the Application</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -81,11 +84,11 @@ function addJsClass() {
<div id="main" class="corner-all">
- <div class="toc-item prev-left"><a href="../guide/versioning.html"><< <strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>11</strong><span>Testing the API</span></a></div>
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span> >></a></div>
@@ -93,7 +96,7 @@ function addJsClass() {
-<h1 id="runningTheApp">11 Running the Application</h1>
+<h1 id="runningTheApp">12 Running the Application</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/runningTheApp.adoc"'>
@@ -150,9 +153,9 @@ curl -s -X POST http://localhost:8080/v1/books/bulk \
<div style="clear:both;margin-top:15px;"></div>
- <div class="toc-item prev-left"><a href="../guide/versioning.html"><< <strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>11</strong><span>Testing the API</span></a></div>
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span> >></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-rest-library/8/guide/single.html b/guides/grails-rest-library/8/guide/single.html
index 486ab343c22..180fc99b188 100644
--- a/guides/grails-rest-library/8/guide/single.html
+++ b/guides/grails-rest-library/8/guide/single.html
@@ -131,9 +131,11 @@
<div class="toc-item" style="margin-left:0px"><a href="#versioning"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#runningTheApp"><strong>11</strong><span>Running the Application</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>11</strong><span>Testing the API</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>12</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#runningTheApp"><strong>12</strong><span>Running the Application</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -392,13 +394,9 @@ curl -s http://localhost:8080/v1/books | jq</code></pre>
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
<span class="keyword">import</span> <span class="include">grails.util.Environment</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.Logger</span>
-<span class="keyword">import</span> <span class="include">org.slf4j.LoggerFactory</span>
<span class="type">class</span> <span class="class">BootStrap</span> {
- <span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">Logger</span> log = LoggerFactory.getLogger(BootStrap)
-
Closure init = { servletContext ->
<span class="keyword">if</span> (Environment.current == Environment.PRODUCTION) {
@@ -449,7 +447,7 @@ curl -s http://localhost:8080/v1/books | jq</code></pre>
</ul>
</div>
<div class="paragraph">
-<p>The <code>@Transactional</code> annotation on the <code>init</code> closure means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state.</p>
+<p>The <code>Author.withTransaction { }</code> wrapper means the four <code>save(failOnError: true)</code> calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state - and a bare <code>save()</code> in <code>BootStrap</code> outside any transaction may not flush at all.</p>
</div>
@@ -721,6 +719,7 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Transactional</span>
<span class="keyword">import</span> <span class="include">grails.rest.RestfulController</span>
+<span class="keyword">import</span> <span class="include">org.springframework.context.MessageSource</span>
<span class="keyword">import</span> <span class="include">org.springframework.http.HttpStatus</span>
<span class="keyword">import</span> <span class="include">org.springframework.validation.FieldError</span>
@@ -728,6 +727,8 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
<span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>]
+ MessageSource messageSource
+
BookController() {
<span class="local-variable">super</span>(<span class="predefined-type">Book</span>)
}
@@ -796,7 +797,7 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">Object</span>> payload = [
object : error.objectName,
code : error.code,
- <span class="key">message</span>: message(<span class="key">error</span>: error)
+ <span class="key">message</span>: messageSource.getMessage(error, request.locale)
]
<span class="keyword">if</span> (error <span class="keyword">instanceof</span> FieldError) {
payload.field = error.field
@@ -1022,7 +1023,423 @@ json g.render(<span class="key">template</span>: <span class="string"><span clas
</div>
-<h1 id="runningTheApp">11 Running the Application</h1>
+<h1 id="testing">11 Testing the API</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The library API ships with a layered Spock suite: fast domain and controller unit tests, <code>@Integration</code> tests against a real database, and functional HTTP tests that drive the JSON endpoints end to end. The integration and functional layers run against a Testcontainers-managed PostgreSQL database, so a Docker daemon is the only host requirement.</p>
+</div>
+<div class="sect1">
+<h2 id="_test_dependencies">Test dependencies</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Testcontainers artifacts are not in the Grails BOM, so they need an explicit <code>testcontainers-bom</code> to resolve a version. The web testing support is required for <code>ControllerUnitTest</code> even in a <code>rest-api</code> profile app:</p>
+</div>
+<div class="listingblock">
+<div class="title">build.gradle (test dependencies)</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy">testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-datamapping</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-views-gson</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-web</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.spockframework:spock-core</span><span class="delimiter">"</span></span>
+testImplementation platform(<span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:testcontainers-bom:1.20.4</span><span class="delimiter">"</span></span>)
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:postgresql</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:spock</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:testcontainers</span><span class="delimiter">"</span></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Because this app uses the database-migration plugin, an empty <code>changelog.groovy</code> means GORM will not auto-create the schema in the test environment. The test profile therefore turns the migration off and lets GORM create the schema directly:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/resources/application-test.yml</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">dataSource</span>:
+ <span class="key">url</span>: <span class="string"><span class="content">jdbc:tc:postgresql:12:///postgres</span></span>
+ <span class="key">driverClassName</span>: <span class="string"><span class="content">org.testcontainers.jdbc.ContainerDatabaseDriver</span></span>
+ <span class="key">dbCreate</span>: <span class="string"><span class="content">create-drop</span></span>
+<span class="key">grails</span>:
+ <span class="key">plugin</span>:
+ <span class="key">databasemigration</span>:
+ <span class="key">updateOnStart</span>: <span class="string"><span class="content">false</span></span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_unit_domain_constraints_and_controller_paging">Unit: domain constraints and controller paging</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DataTest</code> registers the in-memory datastore for <code>Author</code> and <code>Book</code> so constraint logic runs in milliseconds with no Spring context. <code>Book</code> <code>belongsTo</code> <code>Author</code>, so both classes are mocked:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Book. DataTest mocks both Book and its
+ * owning Author so the belongsTo association can be satisfied without a
+ * Spring context or a real database.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>] }
+
+ <span class="directive">private</span> <span class="predefined-type">Book</span> bookWith(<span class="predefined-type">Map</span> overrides) {
+ Author author = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Author</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>([<span class="key">author</span>: author, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">A Title</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a fully populated book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith([:]).validate()
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">author is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">No Author</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">author</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">title</span>: <span class="predefined-constant">null</span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must match the ISBN pattern</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must be unique</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> dup = bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !dup.validate()
+ dup.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">pageCount #pageCount is #valid</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith(<span class="key">pageCount</span>: pageCount).validate() == valid
+
+ <span class="key">where</span>:
+ pageCount || valid
+ <span class="predefined-constant">null</span> || <span class="predefined-constant">true</span>
+ <span class="integer">1</span> || <span class="predefined-constant">true</span>
+ <span class="integer">500</span> || <span class="predefined-constant">true</span>
+ <span class="integer">0</span> || <span class="predefined-constant">false</span>
+ -<span class="integer">5</span> || <span class="predefined-constant">false</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <code>RestfulController</code> pagination clamping (default 25, hard cap 100, negative treated as default) is pinned with a <code>ControllerUnitTest</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookControllerSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">grails.testing.web.controllers.ControllerUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Controller unit test for the pagination clamping the custom index action
+ * applies before it queries. No Spring context, no real database.
+ */</span>
+<span class="type">class</span> <span class="class">BookControllerSpec</span> <span class="directive">extends</span> Specification
+ <span class="directive">implements</span> ControllerUnitTest<BookController>, DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>] }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">index clamps max #requested to #expected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ controller.index(requested)
+
+ <span class="key">then</span>:
+ controller.params.max == expected
+
+ <span class="key">where</span>:
+ requested || expected
+ <span class="integer">500</span> || <span class="integer">100</span> <span class="comment">// capped at 100</span>
+ <span class="integer">10</span> || <span class="integer">10</span> <span class="comment">// within range, untouched</span>
+ <span class="predefined-constant">null</span> || <span class="integer">25</span> <span class="comment">// default</span>
+ -<span class="integer">5</span> || <span class="integer">25</span> <span class="comment">// negative treated as default</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">index never produces a negative offset</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ controller.params.offset = -<span class="integer">10</span>
+
+ <span class="key">when</span>:
+ controller.index(<span class="integer">25</span>)
+
+ <span class="key">then</span>:
+ controller.params.offset == <span class="integer">0</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_relationships_against_a_real_database">Integration: relationships against a real database</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Integration</code> with <code>@Rollback</code> boots the full context and isolates each method. <code>BootStrap</code> seeds four books outside production, so these specs use ISBNs that do not collide with the seed set and filter queries by an author they create:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/BookIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full Spring context against the Testcontainers
+ * PostgreSQL database. @Rollback isolates each method, so a bare GORM call
+ * runs inside an ambient session.
+ *
+ * BootStrap seeds four books outside production, so these specs use ISBNs
+ * that do not collide with the seed set and filter queries by an author
+ * they create themselves.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">BookIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">books are filtered by author with a where query</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author tolkien = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Tolkien</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ Author leguin = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Le Guin</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: tolkien, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">TT Book</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9783000000010</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: leguin, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">LG Book</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9783000000027</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+
+ <span class="key">when</span>:
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> tolkienBooks = <span class="predefined-type">Book</span>.where { author.id == tolkien.id }.list()
+
+ <span class="key">then</span>:
+ tolkienBooks.size() == <span class="integer">1</span>
+ tolkienBooks.first().title == <span class="string"><span class="delimiter">'</span><span class="content">TT Book</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">pagination returns at most the requested page size</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Prolific</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ (<span class="integer">1</span>..<span class="integer">5</span>).each { <span class="type">int</span> i ->
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">"</span><span class="content">Paged </span><span class="inline"><span class="inline-delimiter">${</span>i<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>, <span class="key">isbn</span>: <span class="predefined-type">String</span>.format(<span cl [...]
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
+
+ <span class="key">when</span>:
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> firstPage = <span class="predefined-type">Book</span>.where { author.id == a.id }.list(<span class="key">max</span>: <span class="integer">2</span>, <span class="key">offset</span>: <span class="integer">0</span>, <span class="key">sort</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>, <span class="key">or [...]
+
+ <span class="key">then</span>:
+ firstPage.size() == <span class="integer">2</span>
+ firstPage*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Paged 1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Paged 2</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author's books collection reflects persisted books</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Author</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">One</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9785000000019</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>))
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Two</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9785000000026</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>))
+ a.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Author.get(a.id).books.size() == <span class="integer">2</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_functional_the_rest_surface_over_real_http">Functional: the REST surface over real HTTP</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The functional spec sends real requests with <code>java.net.http.HttpClient</code> against the booted app (port injected via <code>@Value('${local.server.port}')</code>). It asserts the paginated envelope, the page-size clamp, and - most importantly - the all-or-nothing <code>bulkCreate</code> contract: a request with one invalid entry returns <code>422</code> and persists <strong>nothing</strong>. <code>@Rollback</code> is not used (the endpoints commit), so the fixture is created an [...]
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/BookFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonOutput</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional tests drive the real REST/JSON surface over HTTP with
+ * java.net.http.HttpClient. @Rollback is deliberately NOT used: the
+ * endpoints commit, so the fixture is seeded (and read back) inside
+ * withNewTransaction blocks. BootStrap data is not populated in the
+ * @Integration context, so each spec owns its fixture.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">BookFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="predefined-type">Long</span> authorId
+
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ Author a = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span>) ?: <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ authorId = a.id
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9781111111113</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Seeded One</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9781111111113</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span [...]
+ }
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9782222222226</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Seeded Two</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9782222222226</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span [...]
+ }
+ }
+ }
+
+ <span class="directive">private</span> <span class="predefined-type">URI</span> uri(<span class="predefined-type">String</span> path) { <span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inlin [...]
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> getJson(<span class="predefined-type">String</span> path) {
+ client.send(HttpRequest.newBuilder(uri(path)).GET().build(), HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> postJson(<span class="predefined-type">String</span> path, <span class="predefined-type">String</span> body) {
+ client.send(HttpRequest.newBuilder(uri(path))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/books returns a paginated JSON envelope</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.containsKey(<span class="string"><span class="delimiter">'</span><span class="content">page</span><span class="delimiter">'</span></span>)
+ json.containsKey(<span class="string"><span class="delimiter">'</span><span class="content">pageSize</span><span class="delimiter">'</span></span>)
+ json.total >= <span class="integer">2</span>
+ json.items.size() >= <span class="integer">2</span>
+ json.items.every { <span class="local-variable">it</span>.title && <span class="local-variable">it</span>.isbn && <span class="local-variable">it</span>.author?.name }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/books?max= clamps the page size to 100</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books?max=500</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.pageSize == <span class="integer">100</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /v1/books/bulk creates every book and returns 201</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Two Towers</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928203</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">416</span>, <span class="key">author</span>: [<span class="key">id</span>: au [...]
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Return of the King</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928197</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">432</span>, <span class="key">author</span>: [<span class="key">id</span>: au [...]
+ ])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = postJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books/bulk</span><span class="delimiter">'</span></span>, body)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">201</span>
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928203</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span> && <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928197</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /v1/books/bulk rolls back entirely when any entry is invalid</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">one valid and one invalid entry in the same request</span><span class="delimiter">'</span></span>
+ <span class="type">long</span> before = <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.count() }
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Would Be Valid</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000086</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>, <span class="key">author</span>: [<span class="key">id</span>: authorId]],
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>, <span class="key">author</span>: [<span class="key">id</span>: authorId]]
+ ])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = postJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books/bulk</span><span class="delimiter">'</span></span>, body)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">a 422 reports the failing index and NOTHING is persisted</span><span class="delimiter">'</span></span>
+ resp.statusCode() == <span class="integer">422</span>
+ json.books.size() == <span class="integer">1</span>
+ json.books.first().index == <span class="integer">1</span>
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.count() } == before
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780000000086</span><span class="delimiter">'</span></span>) == <span class="predefined-constant">null</span> }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/authors returns the authors as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/authors</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.total >= <span class="integer">1</span>
+ json.items.any { <span class="local-variable">it</span>.name == <span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span> }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Run the suite:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + functional - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+<h1 id="runningTheApp">12 Running the Application</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/runningTheApp.adoc"'>
@@ -1077,7 +1494,7 @@ curl -s -X POST http://localhost:8080/v1/books/bulk \
</div>
-<h1 id="helpWithGrails">12 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">13 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/helpWithGrails.adoc"'>
diff --git a/guides/grails-rest-library/8/guide/testing.html b/guides/grails-rest-library/8/guide/testing.html
new file mode 100644
index 00000000000..718454d7521
--- /dev/null
+++ b/guides/grails-rest-library/8/guide/testing.html
@@ -0,0 +1,566 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+ <title>11 Testing the API</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
+ <link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
+ <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
+ <script type="text/javascript">
+function addJsClass() {
+ var classes = document.body.className.split(" ");
+ classes.push("js");
+ document.body.className = classes.join(" ");
+}
+ </script>
+</head>
+
+<body class="body" onload="addJsClass();">
+<div id="navigation">
+ <div class="navTitle">
+
+ Grails Framework Guide
+ </div>
+ <div class="navLinks">
+ <ul>
+ <li>
+ <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
+ <a href="../guide/index.html" class="button">Table of contents</a>
+
+ <div id="nav-summary-childs" style="display:none;">
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>1</strong><span>Getting Started</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/createApp.html"><strong>2</strong><span>Creating the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/domainModel.html"><strong>3</strong><span>The Book and Author Domain Model</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/urlMappings.html"><strong>4</strong><span>URL Mappings and v1 Versioning</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/controllers.html"><strong>5</strong><span>RestfulController With a Hard Page Cap</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/jsonViews.html"><strong>6</strong><span>JSON Views</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/validation.html"><strong>7</strong><span>Structured 422 Validation Responses</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/pagination.html"><strong>8</strong><span>Pagination, Sorting, and Filtering</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/bulkCreate.html"><strong>9</strong><span>All-or-Nothing Bulk Create</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
+ </div>
+
+ </div>
+ </div>
+ </li>
+ </ul>
+ </div>
+
+
+</div>
+
+<table id="colset" border="0" cellpadding="0" cellspacing="0">
+ <tr>
+ <td id="col1">
+ <div id="main" class="corner-all">
+
+
+ <div class="toc-item prev-left"><a href="../guide/versioning.html"><< <strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
+
+
+
+ <div class="toc-item next-right"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span> >></a></div>
+
+
+
+
+
+
+
+<h1 id="testing">11 Testing the API</h1>
+
+<div class='contribute-btn'>
+ <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-rest-library/v8/guide/testing.adoc"'>
+ <i class='fa fa-pencil-square-o'></i> Improve this doc
+ </button>
+</div>
+
+
+<div class="paragraph">
+<p>The library API ships with a layered Spock suite: fast domain and controller unit tests, <code>@Integration</code> tests against a real database, and functional HTTP tests that drive the JSON endpoints end to end. The integration and functional layers run against a Testcontainers-managed PostgreSQL database, so a Docker daemon is the only host requirement.</p>
+</div>
+<div class="sect1">
+<h2 id="_test_dependencies">Test dependencies</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Testcontainers artifacts are not in the Grails BOM, so they need an explicit <code>testcontainers-bom</code> to resolve a version. The web testing support is required for <code>ControllerUnitTest</code> even in a <code>rest-api</code> profile app:</p>
+</div>
+<div class="listingblock">
+<div class="title">build.gradle (test dependencies)</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy">testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-datamapping</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-views-gson</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.apache.grails:grails-testing-support-web</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.spockframework:spock-core</span><span class="delimiter">"</span></span>
+testImplementation platform(<span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:testcontainers-bom:1.20.4</span><span class="delimiter">"</span></span>)
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:postgresql</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:spock</span><span class="delimiter">"</span></span>
+testImplementation <span class="string"><span class="delimiter">"</span><span class="content">org.testcontainers:testcontainers</span><span class="delimiter">"</span></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Because this app uses the database-migration plugin, an empty <code>changelog.groovy</code> means GORM will not auto-create the schema in the test environment. The test profile therefore turns the migration off and lets GORM create the schema directly:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/resources/application-test.yml</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">dataSource</span>:
+ <span class="key">url</span>: <span class="string"><span class="content">jdbc:tc:postgresql:12:///postgres</span></span>
+ <span class="key">driverClassName</span>: <span class="string"><span class="content">org.testcontainers.jdbc.ContainerDatabaseDriver</span></span>
+ <span class="key">dbCreate</span>: <span class="string"><span class="content">create-drop</span></span>
+<span class="key">grails</span>:
+ <span class="key">plugin</span>:
+ <span class="key">databasemigration</span>:
+ <span class="key">updateOnStart</span>: <span class="string"><span class="content">false</span></span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_unit_domain_constraints_and_controller_paging">Unit: domain constraints and controller paging</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>DataTest</code> registers the in-memory datastore for <code>Author</code> and <code>Book</code> so constraint logic runs in milliseconds with no Spring context. <code>Book</code> <code>belongsTo</code> <code>Author</code>, so both classes are mocked:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Domain constraint unit tests for Book. DataTest mocks both Book and its
+ * owning Author so the belongsTo association can be satisfied without a
+ * Spring context or a real database.
+ */</span>
+<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>] }
+
+ <span class="directive">private</span> <span class="predefined-type">Book</span> bookWith(<span class="predefined-type">Map</span> overrides) {
+ Author author = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Author</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>([<span class="key">author</span>: author, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">A Title</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">a fully populated book validates</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith([:]).validate()
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">author is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">No Author</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">author</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">title is required</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">title</span>: <span class="predefined-constant">null</span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must match the ISBN pattern</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">isbn must be unique</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> dup = bookWith(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>)
+
+ <span class="key">then</span>:
+ !dup.validate()
+ dup.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">pageCount #pageCount is #valid</span><span class="delimiter">"</span></span>() {
+ <span class="key">expect</span>:
+ bookWith(<span class="key">pageCount</span>: pageCount).validate() == valid
+
+ <span class="key">where</span>:
+ pageCount || valid
+ <span class="predefined-constant">null</span> || <span class="predefined-constant">true</span>
+ <span class="integer">1</span> || <span class="predefined-constant">true</span>
+ <span class="integer">500</span> || <span class="predefined-constant">true</span>
+ <span class="integer">0</span> || <span class="predefined-constant">false</span>
+ -<span class="integer">5</span> || <span class="predefined-constant">false</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <code>RestfulController</code> pagination clamping (default 25, hard cap 100, negative treated as default) is pinned with a <code>ControllerUnitTest</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/test/groovy/example/BookControllerSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.gorm.DataTest</span>
+<span class="keyword">import</span> <span class="include">grails.testing.web.controllers.ControllerUnitTest</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Unroll</span>
+
+<span class="comment">/**
+ * Controller unit test for the pagination clamping the custom index action
+ * applies before it queries. No Spring context, no real database.
+ */</span>
+<span class="type">class</span> <span class="class">BookControllerSpec</span> <span class="directive">extends</span> Specification
+ <span class="directive">implements</span> ControllerUnitTest<BookController>, DataTest {
+
+ <span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [Author, <span class="predefined-type">Book</span>] }
+
+ <span class="annotation">@Unroll</span>
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">index clamps max #requested to #expected</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ controller.index(requested)
+
+ <span class="key">then</span>:
+ controller.params.max == expected
+
+ <span class="key">where</span>:
+ requested || expected
+ <span class="integer">500</span> || <span class="integer">100</span> <span class="comment">// capped at 100</span>
+ <span class="integer">10</span> || <span class="integer">10</span> <span class="comment">// within range, untouched</span>
+ <span class="predefined-constant">null</span> || <span class="integer">25</span> <span class="comment">// default</span>
+ -<span class="integer">5</span> || <span class="integer">25</span> <span class="comment">// negative treated as default</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">index never produces a negative offset</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ controller.params.offset = -<span class="integer">10</span>
+
+ <span class="key">when</span>:
+ controller.index(<span class="integer">25</span>)
+
+ <span class="key">then</span>:
+ controller.params.offset == <span class="integer">0</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_integration_relationships_against_a_real_database">Integration: relationships against a real database</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Integration</code> with <code>@Rollback</code> boots the full context and isolates each method. <code>BootStrap</code> seeds four books outside production, so these specs use ISBNs that do not collide with the seed set and filter queries by an author they create:</p>
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/BookIntegrationSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="comment">/**
+ * @Integration boots the full Spring context against the Testcontainers
+ * PostgreSQL database. @Rollback isolates each method, so a bare GORM call
+ * runs inside an ambient session.
+ *
+ * BootStrap seeds four books outside production, so these specs use ISBNs
+ * that do not collide with the seed set and filter queries by an author
+ * they create themselves.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="annotation">@Rollback</span>
+<span class="type">class</span> <span class="class">BookIntegrationSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">books are filtered by author with a where query</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author tolkien = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Tolkien</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ Author leguin = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Le Guin</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: tolkien, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">TT Book</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9783000000010</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: leguin, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">LG Book</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9783000000027</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <s [...]
+
+ <span class="key">when</span>:
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> tolkienBooks = <span class="predefined-type">Book</span>.where { author.id == tolkien.id }.list()
+
+ <span class="key">then</span>:
+ tolkienBooks.size() == <span class="integer">1</span>
+ tolkienBooks.first().title == <span class="string"><span class="delimiter">'</span><span class="content">TT Book</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">pagination returns at most the requested page size</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Prolific</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ (<span class="integer">1</span>..<span class="integer">5</span>).each { <span class="type">int</span> i ->
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">"</span><span class="content">Paged </span><span class="inline"><span class="inline-delimiter">${</span>i<span class="inline-delimiter">}</span></span><span class="delimiter">"</span></span>, <span class="key">isbn</span>: <span class="predefined-type">String</span>.format(<span cl [...]
+ .save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ }
+
+ <span class="key">when</span>:
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> firstPage = <span class="predefined-type">Book</span>.where { author.id == a.id }.list(<span class="key">max</span>: <span class="integer">2</span>, <span class="key">offset</span>: <span class="integer">0</span>, <span class="key">sort</span>: <span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>, <span class="key">or [...]
+
+ <span class="key">then</span>:
+ firstPage.size() == <span class="integer">2</span>
+ firstPage*.title == [<span class="string"><span class="delimiter">'</span><span class="content">Paged 1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Paged 2</span><span class="delimiter">'</span></span>]
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">an author's books collection reflects persisted books</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ Author a = <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Integration Author</span><span class="delimiter">'</span></span>).save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">One</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9785000000019</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>))
+ a.addToBooks(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Two</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9785000000026</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>))
+ a.save(<span class="key">flush</span>: <span class="predefined-constant">true</span>, <span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+
+ <span class="key">expect</span>:
+ Author.get(a.id).books.size() == <span class="integer">2</span>
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_functional_the_rest_surface_over_real_http">Functional: the REST surface over real HTTP</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The functional spec sends real requests with <code>java.net.http.HttpClient</code> against the booted app (port injected via <code>@Value('${local.server.port}')</code>). It asserts the paginated envelope, the page-size clamp, and - most importantly - the all-or-nothing <code>bulkCreate</code> contract: a request with one invalid entry returns <code>422</code> and persists <strong>nothing</strong>. <code>@Rollback</code> is not used (the endpoints commit), so the fixture is created an [...]
+</div>
+<div class="listingblock">
+<div class="title">src/integration-test/groovy/example/BookFunctionalSpec.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonOutput</span>
+<span class="keyword">import</span> <span class="include">groovy.json.JsonSlurper</span>
+<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Value</span>
+<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
+
+<span class="keyword">import</span> <span class="include">java.net.http.HttpClient</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpRequest</span>
+<span class="keyword">import</span> <span class="include">java.net.http.HttpResponse</span>
+
+<span class="comment">/**
+ * Functional tests drive the real REST/JSON surface over HTTP with
+ * java.net.http.HttpClient. @Rollback is deliberately NOT used: the
+ * endpoints commit, so the fixture is seeded (and read back) inside
+ * withNewTransaction blocks. BootStrap data is not populated in the
+ * @Integration context, so each spec owns its fixture.
+ */</span>
+<span class="annotation">@Integration</span>
+<span class="type">class</span> <span class="class">BookFunctionalSpec</span> <span class="directive">extends</span> Specification {
+
+ <span class="annotation">@Value</span>(<span class="string"><span class="delimiter">'</span><span class="content">${local.server.port}</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Integer</span> serverPort
+
+ HttpClient client = HttpClient.newHttpClient()
+
+ <span class="predefined-type">Long</span> authorId
+
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ Author a = Author.findByName(<span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span>) ?: <span class="keyword">new</span> Author(<span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span>).save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>)
+ authorId = a.id
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9781111111113</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Seeded One</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9781111111113</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span [...]
+ }
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9782222222226</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">author</span>: a, <span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Seeded Two</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9782222222226</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span [...]
+ }
+ }
+ }
+
+ <span class="directive">private</span> <span class="predefined-type">URI</span> uri(<span class="predefined-type">String</span> path) { <span class="predefined-type">URI</span>.create(<span class="string"><span class="delimiter">"</span><span class="content">http://localhost:</span><span class="inline"><span class="inline-delimiter">${</span>serverPort<span class="inline-delimiter">}</span></span><span class="inline"><span class="inline-delimiter">${</span>path<span class="inlin [...]
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> getJson(<span class="predefined-type">String</span> path) {
+ client.send(HttpRequest.newBuilder(uri(path)).GET().build(), HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="directive">private</span> HttpResponse<<span class="predefined-type">String</span>> postJson(<span class="predefined-type">String</span> path, <span class="predefined-type">String</span> body) {
+ client.send(HttpRequest.newBuilder(uri(path))
+ .header(<span class="string"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>)
+ .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
+ HttpResponse.BodyHandlers.ofString())
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/books returns a paginated JSON envelope</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.containsKey(<span class="string"><span class="delimiter">'</span><span class="content">page</span><span class="delimiter">'</span></span>)
+ json.containsKey(<span class="string"><span class="delimiter">'</span><span class="content">pageSize</span><span class="delimiter">'</span></span>)
+ json.total >= <span class="integer">2</span>
+ json.items.size() >= <span class="integer">2</span>
+ json.items.every { <span class="local-variable">it</span>.title && <span class="local-variable">it</span>.isbn && <span class="local-variable">it</span>.author?.name }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/books?max= clamps the page size to 100</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books?max=500</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.pageSize == <span class="integer">100</span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /v1/books/bulk creates every book and returns 201</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>:
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Two Towers</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928203</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">416</span>, <span class="key">author</span>: [<span class="key">id</span>: au [...]
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Return of the King</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928197</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">432</span>, <span class="key">author</span>: [<span class="key">id</span>: au [...]
+ ])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = postJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books/bulk</span><span class="delimiter">'</span></span>, body)
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">201</span>
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928203</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span> && <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780547928197</span><span class="delimiter">'</span></span>) != <span class="predefined-constant">null</span>
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">POST /v1/books/bulk rolls back entirely when any entry is invalid</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">one valid and one invalid entry in the same request</span><span class="delimiter">'</span></span>
+ <span class="type">long</span> before = <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.count() }
+ <span class="predefined-type">String</span> body = JsonOutput.toJson([
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Would Be Valid</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000086</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>, <span class="key">author</span>: [<span class="key">id</span>: authorId]],
+ [<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">not-an-isbn</span><span class="delimiter">'</span></span>, <span class="key">author</span>: [<span class="key">id</span>: authorId]]
+ ])
+
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = postJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/books/bulk</span><span class="delimiter">'</span></span>, body)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">a 422 reports the failing index and NOTHING is persisted</span><span class="delimiter">'</span></span>
+ resp.statusCode() == <span class="integer">422</span>
+ json.books.size() == <span class="integer">1</span>
+ json.books.first().index == <span class="integer">1</span>
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.count() } == before
+ <span class="predefined-type">Book</span>.withNewTransaction { <span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780000000086</span><span class="delimiter">'</span></span>) == <span class="predefined-constant">null</span> }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /v1/authors returns the authors as JSON</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ HttpResponse<<span class="predefined-type">String</span>> resp = getJson(<span class="string"><span class="delimiter">'</span><span class="content">/v1/authors</span><span class="delimiter">'</span></span>)
+ <span class="predefined-type">Map</span> json = <span class="keyword">new</span> JsonSlurper().parseText(resp.body()) <span class="keyword">as</span> <span class="predefined-type">Map</span>
+
+ <span class="key">then</span>:
+ resp.statusCode() == <span class="integer">200</span>
+ json.total >= <span class="integer">1</span>
+ json.items.any { <span class="local-variable">it</span>.name == <span class="string"><span class="delimiter">'</span><span class="content">Functional Author</span><span class="delimiter">'</span></span> }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Run the suite:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test # unit - milliseconds, no Docker
+./gradlew integrationTest # integration + functional - Docker required</code></pre>
+</div>
+</div>
+</div>
+</div>
+
+
+ <div style="clear:both;margin-top:15px;"></div>
+
+ <div class="toc-item prev-left"><a href="../guide/versioning.html"><< <strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
+
+ <div class="toc-item next-right"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span> >></a></div>
+
+ <div style="clear:both"></div>
+ </div>
+ </td>
+ <td id="col2">
+ <div class="local clearfix">
+ <div class="local-title" style="text-align: right"><a href="https://travis-ci.org/grails-guides/grails-rest-library"><img src="https://travis-ci.org/grails-guides/grails-rest-library.svg?branch=master" /></a></div>
+ <div class="local-title">
+ <a href="https://github.com/grails-guides/grails-rest-library">
+ <svg height="35" class="octicon octicon-mark-github" viewBox="0 0 16 16" version="1.1" width="35" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.8 [...]
+ </div>
+ <div class="menu">
+ <div class="input-group">
+ <button href="#" onclick="document.getElementById('github-url').value='git@github.com:grails-guides/grails-rest-library.git'" class="codeButton">SSH</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-rest-library.git'" class="codeButton">HTTPS</button>
+ <button onclick="document.getElementById('github-url').value='https://github.com/grails-guides/grails-rest-library'" class="codeButton">Subversion</button>
+ </div>
+
+ <div class="input-group">
+ <!-- Target -->
+ <input id="github-url" value="git@github.com:grails-guides/grails-rest-library.git" type="text" />
+
+ <!-- Trigger -->
+ <button class="clipbtn" type="button" data-clipboard-target="#github-url">
+
+ <img width="13" src="../img/clippy.svg" alt="Copy to clipboard">
+ </button>
+
+ </div>
+ <div class="input-group">
+ <a href="https://github.com/grails-guides/grails-rest-library/archive/master.zip" class="downloadButton">Download ZIP</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ </tr>
+</table>
+
+<div id="footer">
+
+
+</div>
+
+<script type="text/javascript" src="../js/docs.js"></script>
+
+</body>
+</html>
diff --git a/guides/grails-rest-library/8/guide/urlMappings.html b/guides/grails-rest-library/8/guide/urlMappings.html
index 8eec42c5bad..7122bf5afa8 100644
--- a/guides/grails-rest-library/8/guide/urlMappings.html
+++ b/guides/grails-rest-library/8/guide/urlMappings.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-rest-library/8/guide/validation.html b/guides/grails-rest-library/8/guide/validation.html
index a3f6c18dcb4..6893de8cd38 100644
--- a/guides/grails-rest-library/8/guide/validation.html
+++ b/guides/grails-rest-library/8/guide/validation.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -112,6 +115,7 @@ function addJsClass() {
<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Transactional</span>
<span class="keyword">import</span> <span class="include">grails.rest.RestfulController</span>
+<span class="keyword">import</span> <span class="include">org.springframework.context.MessageSource</span>
<span class="keyword">import</span> <span class="include">org.springframework.http.HttpStatus</span>
<span class="keyword">import</span> <span class="include">org.springframework.validation.FieldError</span>
@@ -119,6 +123,8 @@ function addJsClass() {
<span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>]
+ MessageSource messageSource
+
BookController() {
<span class="local-variable">super</span>(<span class="predefined-type">Book</span>)
}
@@ -187,7 +193,7 @@ function addJsClass() {
<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">Object</span>> payload = [
object : error.objectName,
code : error.code,
- <span class="key">message</span>: message(<span class="key">error</span>: error)
+ <span class="key">message</span>: messageSource.getMessage(error, request.locale)
]
<span class="keyword">if</span> (error <span class="keyword">instanceof</span> FieldError) {
payload.field = error.field
diff --git a/guides/grails-rest-library/8/guide/versioning.html b/guides/grails-rest-library/8/guide/versioning.html
index 723bfa991b4..f5e81e1fced 100644
--- a/guides/grails-rest-library/8/guide/versioning.html
+++ b/guides/grails-rest-library/8/guide/versioning.html
@@ -60,10 +60,13 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -85,7 +88,7 @@ function addJsClass() {
- <div class="toc-item next-right"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span> >></a></div>
@@ -143,7 +146,7 @@ function addJsClass() {
<div class="toc-item prev-left"><a href="../guide/bulkCreate.html"><< <strong>9</strong><span>All-or-Nothing Bulk Create</span></a></div>
- <div class="toc-item next-right"><a href="../guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>11</strong><span>Testing the API</span> >></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-rest-library/8/index.html b/guides/grails-rest-library/8/index.html
index a6a6d1122b5..6789878910d 100644
--- a/guides/grails-rest-library/8/index.html
+++ b/guides/grails-rest-library/8/index.html
@@ -131,9 +131,11 @@
<div class="toc-item" style="margin-left:0px"><a href="./guide/versioning.html"><strong>10</strong><span>URL-Prefix vs Content-Negotiation Versioning</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="./guide/runningTheApp.html"><strong>11</strong><span>Running the Application</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/testing.html"><strong>11</strong><span>Testing the API</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>12</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/runningTheApp.html"><strong>12</strong><span>Running the Application</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="./guide/helpWithGrails.html"><strong>13</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-spock-test-tour/8/guide/controllerUnitTest.html b/guides/grails-spock-test-tour/8/guide/controllerUnitTest.html
index 2c4ac280dc5..e364f8c48e9 100644
--- a/guides/grails-spock-test-tour/8/guide/controllerUnitTest.html
+++ b/guides/grails-spock-test-tour/8/guide/controllerUnitTest.html
@@ -126,9 +126,10 @@ function addJsClass() {
<span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</sp [...]
.save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>, <span class="key">flush</span>: <span class="predefined-constant">true</span>)
- <span class="key">when</span>:
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">RestfulController.show() reads params.id - it takes no argument</span><span class="delimiter">'</span></span>
request.method = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
- controller.show(b.id)
+ params.id = b.id
+ controller.show()
<span class="key">then</span>:
response.status == HttpStatus.OK.value()
@@ -138,7 +139,8 @@ function addJsClass() {
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /books/{id} for a missing id returns 404</span><span class="delimiter">"</span></span>() {
<span class="key">when</span>:
request.method = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
- controller.show(<span class="integer">99999L</span>)
+ params.id = <span class="integer">99999L</span>
+ controller.show()
<span class="key">then</span>:
response.status == HttpStatus.NOT_FOUND.value()
diff --git a/guides/grails-spock-test-tour/8/guide/dataTest.html b/guides/grails-spock-test-tour/8/guide/dataTest.html
index 6cbbc20e5ee..f336ce73f5e 100644
--- a/guides/grails-spock-test-tour/8/guide/dataTest.html
+++ b/guides/grails-spock-test-tour/8/guide/dataTest.html
@@ -120,10 +120,12 @@ function addJsClass() {
<span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [<span class="predefined-type">Book</span>] }
<span class="type">void</span> setup() {
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Short Story</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">50</span> ).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novella</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">150</span>).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novel</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000003</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">400</span>).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Doorstopper</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000004</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">900</span>).save( [...]
+ <span class="comment">// flush: true forces the in-memory datastore to persist before the</span>
+ <span class="comment">// GORM finders below query it - without it the finders see zero rows.</span>
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Short Story</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">50</span> ).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novella</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">150</span>).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novel</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000003</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">400</span>).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Doorstopper</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000004</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">900</span>).save( [...]
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">countByPageCountGreaterThanEquals returns the right count</span><span class="delimiter">"</span></span>() {
diff --git a/guides/grails-spock-test-tour/8/guide/domainUnitTest.html b/guides/grails-spock-test-tour/8/guide/domainUnitTest.html
index 0ce35992b90..9016d8a5aed 100644
--- a/guides/grails-spock-test-tour/8/guide/domainUnitTest.html
+++ b/guides/grails-spock-test-tour/8/guide/domainUnitTest.html
@@ -119,12 +119,31 @@ function addJsClass() {
<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<<span class="predefined-type">Book</span>> {
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a book with no title</span><span class="delimiter">"</span></span>() {
- <span class="key">when</span>:
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">title is omitted from the map constructor, so it is null</span><span class="delimiter">'</span></span>
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>)
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the nullable constraint - not blank - is what fires for a null value</span><span class="delimiter">'</span></span>
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a blank title</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a blank string is assigned directly (the map constructor would convert it to null)</span><span class="delimiter">'</span></span>
<span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>)
+ b.title = <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">now the blank constraint fires</span><span class="delimiter">'</span></span>
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a title longer than maxSize</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">256</span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span [...]
<span class="key">then</span>:
!b.validate()
- b.errors.fieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a book with a malformed ISBN</span><span class="delimiter">"</span></span>() {
@@ -133,7 +152,7 @@ function addJsClass() {
<span class="key">then</span>:
!b.validate()
- b.errors.fieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">accepts a book with a valid ISBN-13</span><span class="delimiter">"</span></span>() {
@@ -169,7 +188,7 @@ function addJsClass() {
<div class="ulist">
<ul>
<li>
-<p><code>b.errors.fieldError('title').code == 'blank'</code> checks the <strong>constraint code</strong>, not the localised message. Codes are stable across releases and locales; messages are not.</p>
+<p><code>b.errors.getFieldError('title').code</code> checks the <strong>constraint code</strong>, not the localised message. Codes are stable across releases and locales; messages are not. Note the subtlety the spec demonstrates: omitting <code>title</code> from the map constructor leaves it <code>null</code>, so the <code>nullable</code> code fires - not <code>blank</code>. To exercise the <code>blank</code> constraint you must assign <code>b.title = ''</code> <strong>directly</strong>, [...]
</li>
<li>
<p><code>@Unroll</code> plus a <code>where:</code> data table collapses what would otherwise be five copy-pasted tests into one parameterised spec. The <code>#pageCount</code> token in the test name expands to the actual value, so the IDE’s run-tree shows each row separately.</p>
diff --git a/guides/grails-spock-test-tour/8/guide/functionalTest.html b/guides/grails-spock-test-tour/8/guide/functionalTest.html
index edda0e73a3c..d53081aad7d 100644
--- a/guides/grails-spock-test-tour/8/guide/functionalTest.html
+++ b/guides/grails-spock-test-tour/8/guide/functionalTest.html
@@ -118,23 +118,129 @@ function addJsClass() {
* @Integration is mandatory: GrailsContainerGebExtension throws at
* runtime if the annotation is missing. @Rollback is NOT used here -
* functional tests exercise the full HTTP stack and need committed
- * data.
+ * data. The fixture is therefore seeded inside its own
+ * withNewTransaction block; a bare GORM call would fail because an
+ * @Integration spec without @Rollback has no ambient Hibernate session.
*/</span>
<span class="annotation">@Integration</span>
<span class="type">class</span> <span class="class">BookFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
- <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index page renders the seeded books</span><span class="delimiter">"</span></span>() {
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780261103344</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780261103344</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index page renders the committed books</span><span class="delimiter">"</span></span>() {
<span class="key">when</span>:
go <span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>
<span class="key">then</span>:
title.contains(<span class="string"><span class="delimiter">'</span><span class="content">Book</span><span class="delimiter">'</span></span>)
<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table tbody tr</span><span class="delimiter">'</span></span>).size() > <span class="integer">0</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_page_the_test_drives">The page the test drives</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>go '/books'</code> needs a real HTML page with a table. <code>BookController</code> stays a <code>RestfulController</code> for the JSON CRUD surface, but its <code>index</code> action is overridden so the HTML format renders a GSP while JSON clients keep their collection response:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/controllers/example/BookController.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.rest.RestfulController</span>
+
+<span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController<<span class="predefined-type">Book</span>> {
+ <span class="comment">// 'json' keeps the REST CRUD surface; 'html' lets the index action render</span>
+ <span class="comment">// grails-app/views/book/index.gsp so a browser (and the Geb functional</span>
+ <span class="comment">// test) gets a real HTML table at /books.</span>
+ <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">html</span><span class="delimiter">'</span></span>]
+ BookService bookService
+ BookController() { <span class="local-variable">super</span>(<span class="predefined-type">Book</span>) }
+
+ <span class="comment">// Override index so the HTML format renders the GSP table view (through the</span>
+ <span class="comment">// sitemesh layout) while JSON clients still get the REST collection.</span>
+ <span class="keyword">def</span> <span class="function">index</span>(<span class="predefined-type">Integer</span> max) {
+ params.max = <span class="predefined-type">Math</span>.min(max ?: <span class="integer">100</span>, <span class="integer">100</span>)
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> books = listAllResources(params)
+ withFormat {
+ html { [<span class="key">bookList</span>: books, <span class="key">bookCount</span>: countResources()] }
+ json { respond books, [<span class="key">model</span>: [<span class="key">bookCount</span>: countResources()]] }
+ }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>A <code>resources</code> URL mapping exposes the controller at <code>/books</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/controllers/example/UrlMappings.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="type">class</span> <span class="class">UrlMappings</span> {
+ <span class="directive">static</span> mappings = {
+ <span class="string"><span class="delimiter">"</span><span class="content">/books</span><span class="delimiter">"</span></span>(<span class="key">resources</span>: <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>namespace</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span clas [...]
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span class="content">?(.</span><span class="inline"><span class="inline-delimiter">$</span>format</span><span class [...]
+ constraints {
+ <span class="comment">// apply constraints here</span>
+ }
+ }
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">"</span><span class="content">/index</span><span class="delimiter">"</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">500</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/error</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">404</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/notFound</span><span class="delimiter">'</span></span>)
+
}
}</code></pre>
</div>
</div>
<div class="paragraph">
+<p>and a minimal GSP renders the table the spec asserts against:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/views/book/index.gsp</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="html"><span class="doctype"><!DOCTYPE html></span>
+<span class="tag"><html></span>
+<span class="tag"><head></span>
+ <span class="tag"><meta</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">layout</span><span class="delimiter">"</span></span> <span class="attribute-name">content</span>=<span class="string"><span class="delimiter">"</span><span class="content">main</span><span class="delimiter">"</span></span><span class="tag">/></span>
+ <span class="tag"><title></span>Book List<span class="tag"></title></span>
+<span class="tag"></head></span>
+<span class="tag"><body></span>
+<span class="tag"><h1></span>Book List<span class="tag"></h1></span>
+<span class="tag"><table></span>
+ <span class="tag"><thead></span>
+ <span class="tag"><tr></span><span class="tag"><th></span>Title<span class="tag"></th></span><span class="tag"><th></span>ISBN<span class="tag"></th></span><span class="tag"><th></span>Pages<span class="tag"></th></span><span class="tag"></tr></span>
+ <span class="tag"></thead></span>
+ <span class="tag"><tbody></span>
+ <span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${bookList}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">book</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><tr></span>
+ <span class="tag"><td></span>${book.title}<span class="tag"></td></span>
+ <span class="tag"><td></span>${book.isbn}<span class="tag"></td></span>
+ <span class="tag"><td></span>${book.pageCount}<span class="tag"></td></span>
+ <span class="tag"></tr></span>
+ <span class="tag"></g:each></span>
+ <span class="tag"></tbody></span>
+<span class="tag"></table></span>
+<span class="tag"></body></span>
+<span class="tag"></html></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Because the spec is <code>@Integration</code> <strong>without</strong> <code>@Rollback</code>, it seeds its fixture inside a <code>withNewTransaction</code> block so the row is committed and visible to the browser. A bare GORM call in an un-rolled-back <code>@Integration</code> spec has no ambient Hibernate session and would throw. <code>BootStrap</code> seed data is <strong>not</strong> a substitute here: it does not populate the test database in the integration context, so the spec [...]
+</div>
+<div class="paragraph">
<p>Three patterns to highlight:</p>
</div>
<div class="ulist">
@@ -171,6 +277,8 @@ function addJsClass() {
</div>
<div class="paragraph">
<p>The matching <a href="../grails-github-actions-cicd/8/guide/index.html">CI/CD guide</a> models this as a four-stage job graph (validation → unit → integration → functional) so a broken unit test does not waste 60 seconds on functional runs. The CI runner needs Docker available too; GitHub-hosted Linux runners ship with Docker out of the box.</p>
+</div>
+</div>
</div>
diff --git a/guides/grails-spock-test-tour/8/guide/gettingStarted.html b/guides/grails-spock-test-tour/8/guide/gettingStarted.html
index 4845e07107c..185378780dd 100644
--- a/guides/grails-spock-test-tour/8/guide/gettingStarted.html
+++ b/guides/grails-spock-test-tour/8/guide/gettingStarted.html
@@ -137,7 +137,7 @@ function addJsClass() {
<p><code>BookService.groovy</code> - an <code>@Service(Book)</code> GORM data service with <code>findByIsbn</code>, <code>countByPageCountGreaterThanEquals</code>, and the standard CRUD methods.</p>
</li>
<li>
-<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> so the JSON CRUD surface is testable from <code>ControllerUnitTest</code>.</p>
+<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> exposing a JSON CRUD surface (testable from <code>ControllerUnitTest</code>) whose <code>index</code> action also renders an HTML table at <code>/books</code> for the functional test to drive.</p>
</li>
<li>
<p>Five spec files exercising the five test layers:</p>
diff --git a/guides/grails-spock-test-tour/8/guide/index.html b/guides/grails-spock-test-tour/8/guide/index.html
index 357931921ba..97aad7b14df 100644
--- a/guides/grails-spock-test-tour/8/guide/index.html
+++ b/guides/grails-spock-test-tour/8/guide/index.html
@@ -177,7 +177,7 @@
<p><code>BookService.groovy</code> - an <code>@Service(Book)</code> GORM data service with <code>findByIsbn</code>, <code>countByPageCountGreaterThanEquals</code>, and the standard CRUD methods.</p>
</li>
<li>
-<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> so the JSON CRUD surface is testable from <code>ControllerUnitTest</code>.</p>
+<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> exposing a JSON CRUD surface (testable from <code>ControllerUnitTest</code>) whose <code>index</code> action also renders an HTML table at <code>/books</code> for the functional test to drive.</p>
</li>
<li>
<p>Five spec files exercising the five test layers:</p>
@@ -356,12 +356,31 @@ cd grails-spock-test-tour/complete
<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<<span class="predefined-type">Book</span>> {
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a book with no title</span><span class="delimiter">"</span></span>() {
- <span class="key">when</span>:
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">title is omitted from the map constructor, so it is null</span><span class="delimiter">'</span></span>
<span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>)
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the nullable constraint - not blank - is what fires for a null value</span><span class="delimiter">'</span></span>
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a blank title</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a blank string is assigned directly (the map constructor would convert it to null)</span><span class="delimiter">'</span></span>
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>)
+ b.title = <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">now the blank constraint fires</span><span class="delimiter">'</span></span>
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a title longer than maxSize</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">256</span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span [...]
+
<span class="key">then</span>:
!b.validate()
- b.errors.fieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a book with a malformed ISBN</span><span class="delimiter">"</span></span>() {
@@ -370,7 +389,7 @@ cd grails-spock-test-tour/complete
<span class="key">then</span>:
!b.validate()
- b.errors.fieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">accepts a book with a valid ISBN-13</span><span class="delimiter">"</span></span>() {
@@ -406,7 +425,7 @@ cd grails-spock-test-tour/complete
<div class="ulist">
<ul>
<li>
-<p><code>b.errors.fieldError('title').code == 'blank'</code> checks the <strong>constraint code</strong>, not the localised message. Codes are stable across releases and locales; messages are not.</p>
+<p><code>b.errors.getFieldError('title').code</code> checks the <strong>constraint code</strong>, not the localised message. Codes are stable across releases and locales; messages are not. Note the subtlety the spec demonstrates: omitting <code>title</code> from the map constructor leaves it <code>null</code>, so the <code>nullable</code> code fires - not <code>blank</code>. To exercise the <code>blank</code> constraint you must assign <code>b.title = ''</code> <strong>directly</strong>, [...]
</li>
<li>
<p><code>@Unroll</code> plus a <code>where:</code> data table collapses what would otherwise be five copy-pasted tests into one parameterised spec. The <code>#pageCount</code> token in the test name expands to the actual value, so the IDE’s run-tree shows each row separately.</p>
@@ -451,10 +470,12 @@ cd grails-spock-test-tour/complete
<span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [<span class="predefined-type">Book</span>] }
<span class="type">void</span> setup() {
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Short Story</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">50</span> ).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novella</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">150</span>).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novel</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000003</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">400</span>).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Doorstopper</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000004</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">900</span>).save( [...]
+ <span class="comment">// flush: true forces the in-memory datastore to persist before the</span>
+ <span class="comment">// GORM finders below query it - without it the finders see zero rows.</span>
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Short Story</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">50</span> ).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novella</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">150</span>).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novel</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000003</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">400</span>).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Doorstopper</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000004</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">900</span>).save( [...]
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">countByPageCountGreaterThanEquals returns the right count</span><span class="delimiter">"</span></span>() {
@@ -536,9 +557,10 @@ cd grails-spock-test-tour/complete
<span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</sp [...]
.save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>, <span class="key">flush</span>: <span class="predefined-constant">true</span>)
- <span class="key">when</span>:
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">RestfulController.show() reads params.id - it takes no argument</span><span class="delimiter">'</span></span>
request.method = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
- controller.show(b.id)
+ params.id = b.id
+ controller.show()
<span class="key">then</span>:
response.status == HttpStatus.OK.value()
@@ -548,7 +570,8 @@ cd grails-spock-test-tour/complete
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /books/{id} for a missing id returns 404</span><span class="delimiter">"</span></span>() {
<span class="key">when</span>:
request.method = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
- controller.show(<span class="integer">99999L</span>)
+ params.id = <span class="integer">99999L</span>
+ controller.show()
<span class="key">then</span>:
response.status == HttpStatus.NOT_FOUND.value()
@@ -596,7 +619,7 @@ cd grails-spock-test-tour/complete
<div class="paragraph">
-<p><code>@Integration</code> boots the full Spring context against a real datasource (whatever the <code>test</code> environment in <code>application.yml</code> configures - H2 by default). <code>@Rollback</code> rolls back every test method’s database changes so specs stay isolated.</p>
+<p><code>@Integration</code> boots the full Spring context against a real datasource - the <code>test</code> environment here points at a Testcontainers-managed PostgreSQL database (<code>jdbc:tc:postgresql:…​</code> in <code>application-test.yml</code>), so the specs run against the same engine as production. <code>@Rollback</code> rolls back every test method’s database changes so specs stay isolated.</p>
</div>
<div class="listingblock">
<div class="title">src/integration-test/groovy/example/BookIntegrationSpec.groovy</div>
@@ -605,6 +628,7 @@ cd grails-spock-test-tour/complete
<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">grails.validation.ValidationException</span>
<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
<span class="comment">/**
@@ -640,15 +664,17 @@ cd grails-spock-test-tour/complete
reloaded.isbn == <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>
}
- <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">saving a book with a duplicate isbn fails validation</span><span class="delimiter">"</span></span>() {
- <span class="key">given</span>:
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">saving a book with a duplicate isbn is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">a persisted book, flushed so the unique validator can see it</span><span class="delimiter">'</span></span>
bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">First</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>))
+ <span class="predefined-type">Book</span>.withSession { <span class="local-variable">it</span>.flush() }
- <span class="key">when</span>:
- <span class="predefined-type">Book</span> second = bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Second</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class=" [...]
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a second book reuses the isbn</span><span class="delimiter">'</span></span>
+ bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Second</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>))
- <span class="key">then</span>:
- second == <span class="predefined-constant">null</span> || second.hasErrors()
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the @Service save throws a ValidationException (failOnError is implicit) carrying the unique error</span><span class="delimiter">'</span></span>
+ ValidationException ex = thrown()
+ ex.message.contains(<span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>)
}
}</code></pre>
</div>
@@ -665,7 +691,7 @@ cd grails-spock-test-tour/complete
<p><code>@Rollback</code> is non-negotiable. Without it, the second test sees the first test’s data and the third test sees both. Specs become order-dependent and impossible to debug.</p>
</li>
<li>
-<p>The duplicate-ISBN test deliberately catches the constraint failure inside the second <code>save</code> call rather than letting it throw. <code>unique: true</code> constraint failures surface as <code>errors.hasErrors()</code>, not as exceptions, in GORM 7+.</p>
+<p>The duplicate-ISBN test first <strong>flushes</strong> the persisted book (<code>Book.withSession { it.flush() }</code>) so the <code>unique</code> validator can see it - without the flush the second insert is still pending and validation passes. It then expects the second <code>save</code> to throw: a GORM <code>@Service</code> save applies <code>failOnError</code> semantics, so a <code>unique: true</code> violation surfaces as a thrown <code>grails.validation.ValidationException</co [...]
</li>
</ul>
</div>
@@ -705,23 +731,129 @@ cd grails-spock-test-tour/complete
* @Integration is mandatory: GrailsContainerGebExtension throws at
* runtime if the annotation is missing. @Rollback is NOT used here -
* functional tests exercise the full HTTP stack and need committed
- * data.
+ * data. The fixture is therefore seeded inside its own
+ * withNewTransaction block; a bare GORM call would fail because an
+ * @Integration spec without @Rollback has no ambient Hibernate session.
*/</span>
<span class="annotation">@Integration</span>
<span class="type">class</span> <span class="class">BookFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
- <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index page renders the seeded books</span><span class="delimiter">"</span></span>() {
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780261103344</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780261103344</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index page renders the committed books</span><span class="delimiter">"</span></span>() {
<span class="key">when</span>:
go <span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>
<span class="key">then</span>:
title.contains(<span class="string"><span class="delimiter">'</span><span class="content">Book</span><span class="delimiter">'</span></span>)
<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table tbody tr</span><span class="delimiter">'</span></span>).size() > <span class="integer">0</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_page_the_test_drives">The page the test drives</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>go '/books'</code> needs a real HTML page with a table. <code>BookController</code> stays a <code>RestfulController</code> for the JSON CRUD surface, but its <code>index</code> action is overridden so the HTML format renders a GSP while JSON clients keep their collection response:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/controllers/example/BookController.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.rest.RestfulController</span>
+
+<span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController<<span class="predefined-type">Book</span>> {
+ <span class="comment">// 'json' keeps the REST CRUD surface; 'html' lets the index action render</span>
+ <span class="comment">// grails-app/views/book/index.gsp so a browser (and the Geb functional</span>
+ <span class="comment">// test) gets a real HTML table at /books.</span>
+ <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">html</span><span class="delimiter">'</span></span>]
+ BookService bookService
+ BookController() { <span class="local-variable">super</span>(<span class="predefined-type">Book</span>) }
+
+ <span class="comment">// Override index so the HTML format renders the GSP table view (through the</span>
+ <span class="comment">// sitemesh layout) while JSON clients still get the REST collection.</span>
+ <span class="keyword">def</span> <span class="function">index</span>(<span class="predefined-type">Integer</span> max) {
+ params.max = <span class="predefined-type">Math</span>.min(max ?: <span class="integer">100</span>, <span class="integer">100</span>)
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> books = listAllResources(params)
+ withFormat {
+ html { [<span class="key">bookList</span>: books, <span class="key">bookCount</span>: countResources()] }
+ json { respond books, [<span class="key">model</span>: [<span class="key">bookCount</span>: countResources()]] }
+ }
}
}</code></pre>
</div>
</div>
<div class="paragraph">
+<p>A <code>resources</code> URL mapping exposes the controller at <code>/books</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/controllers/example/UrlMappings.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="type">class</span> <span class="class">UrlMappings</span> {
+ <span class="directive">static</span> mappings = {
+ <span class="string"><span class="delimiter">"</span><span class="content">/books</span><span class="delimiter">"</span></span>(<span class="key">resources</span>: <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>namespace</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span clas [...]
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span class="content">?(.</span><span class="inline"><span class="inline-delimiter">$</span>format</span><span class [...]
+ constraints {
+ <span class="comment">// apply constraints here</span>
+ }
+ }
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">"</span><span class="content">/index</span><span class="delimiter">"</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">500</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/error</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">404</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/notFound</span><span class="delimiter">'</span></span>)
+
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>and a minimal GSP renders the table the spec asserts against:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/views/book/index.gsp</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="html"><span class="doctype"><!DOCTYPE html></span>
+<span class="tag"><html></span>
+<span class="tag"><head></span>
+ <span class="tag"><meta</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">layout</span><span class="delimiter">"</span></span> <span class="attribute-name">content</span>=<span class="string"><span class="delimiter">"</span><span class="content">main</span><span class="delimiter">"</span></span><span class="tag">/></span>
+ <span class="tag"><title></span>Book List<span class="tag"></title></span>
+<span class="tag"></head></span>
+<span class="tag"><body></span>
+<span class="tag"><h1></span>Book List<span class="tag"></h1></span>
+<span class="tag"><table></span>
+ <span class="tag"><thead></span>
+ <span class="tag"><tr></span><span class="tag"><th></span>Title<span class="tag"></th></span><span class="tag"><th></span>ISBN<span class="tag"></th></span><span class="tag"><th></span>Pages<span class="tag"></th></span><span class="tag"></tr></span>
+ <span class="tag"></thead></span>
+ <span class="tag"><tbody></span>
+ <span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${bookList}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">book</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><tr></span>
+ <span class="tag"><td></span>${book.title}<span class="tag"></td></span>
+ <span class="tag"><td></span>${book.isbn}<span class="tag"></td></span>
+ <span class="tag"><td></span>${book.pageCount}<span class="tag"></td></span>
+ <span class="tag"></tr></span>
+ <span class="tag"></g:each></span>
+ <span class="tag"></tbody></span>
+<span class="tag"></table></span>
+<span class="tag"></body></span>
+<span class="tag"></html></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Because the spec is <code>@Integration</code> <strong>without</strong> <code>@Rollback</code>, it seeds its fixture inside a <code>withNewTransaction</code> block so the row is committed and visible to the browser. A bare GORM call in an un-rolled-back <code>@Integration</code> spec has no ambient Hibernate session and would throw. <code>BootStrap</code> seed data is <strong>not</strong> a substitute here: it does not populate the test database in the integration context, so the spec [...]
+</div>
+<div class="paragraph">
<p>Three patterns to highlight:</p>
</div>
<div class="ulist">
@@ -759,6 +891,8 @@ cd grails-spock-test-tour/complete
<div class="paragraph">
<p>The matching <a href="../grails-github-actions-cicd/8/guide/index.html">CI/CD guide</a> models this as a four-stage job graph (validation → unit → integration → functional) so a broken unit test does not waste 60 seconds on functional runs. The CI runner needs Docker available too; GitHub-hosted Linux runners ship with Docker out of the box.</p>
</div>
+</div>
+</div>
<h1 id="parameterised">8 Parameterised where: Data Tables</h1>
@@ -857,7 +991,7 @@ cd grails-spock-test-tour/complete
jacocoTestReport {
dependsOn test, integrationTest
- executionData fileTree(buildDir).include(<span class="string"><span class="delimiter">'</span><span class="content">jacoco/*.exec</span><span class="delimiter">'</span></span>)
+ executionData fileTree(layout.buildDirectory.get().asFile).include(<span class="string"><span class="delimiter">'</span><span class="content">jacoco/*.exec</span><span class="delimiter">'</span></span>)
reports {
xml.required = <span class="predefined-constant">true</span> <span class="comment">// for Codecov upload</span>
html.required = <span class="predefined-constant">true</span> <span class="comment">// for human inspection</span>
diff --git a/guides/grails-spock-test-tour/8/guide/integrationTest.html b/guides/grails-spock-test-tour/8/guide/integrationTest.html
index ab3c20cbd9a..d4054e0064c 100644
--- a/guides/grails-spock-test-tour/8/guide/integrationTest.html
+++ b/guides/grails-spock-test-tour/8/guide/integrationTest.html
@@ -97,7 +97,7 @@ function addJsClass() {
<div class="paragraph">
-<p><code>@Integration</code> boots the full Spring context against a real datasource (whatever the <code>test</code> environment in <code>application.yml</code> configures - H2 by default). <code>@Rollback</code> rolls back every test method’s database changes so specs stay isolated.</p>
+<p><code>@Integration</code> boots the full Spring context against a real datasource - the <code>test</code> environment here points at a Testcontainers-managed PostgreSQL database (<code>jdbc:tc:postgresql:…​</code> in <code>application-test.yml</code>), so the specs run against the same engine as production. <code>@Rollback</code> rolls back every test method’s database changes so specs stay isolated.</p>
</div>
<div class="listingblock">
<div class="title">src/integration-test/groovy/example/BookIntegrationSpec.groovy</div>
@@ -106,6 +106,7 @@ function addJsClass() {
<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">grails.validation.ValidationException</span>
<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
<span class="comment">/**
@@ -141,15 +142,17 @@ function addJsClass() {
reloaded.isbn == <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>
}
- <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">saving a book with a duplicate isbn fails validation</span><span class="delimiter">"</span></span>() {
- <span class="key">given</span>:
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">saving a book with a duplicate isbn is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">a persisted book, flushed so the unique validator can see it</span><span class="delimiter">'</span></span>
bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">First</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>))
+ <span class="predefined-type">Book</span>.withSession { <span class="local-variable">it</span>.flush() }
- <span class="key">when</span>:
- <span class="predefined-type">Book</span> second = bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Second</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class=" [...]
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a second book reuses the isbn</span><span class="delimiter">'</span></span>
+ bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Second</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>))
- <span class="key">then</span>:
- second == <span class="predefined-constant">null</span> || second.hasErrors()
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the @Service save throws a ValidationException (failOnError is implicit) carrying the unique error</span><span class="delimiter">'</span></span>
+ ValidationException ex = thrown()
+ ex.message.contains(<span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>)
}
}</code></pre>
</div>
@@ -166,7 +169,7 @@ function addJsClass() {
<p><code>@Rollback</code> is non-negotiable. Without it, the second test sees the first test’s data and the third test sees both. Specs become order-dependent and impossible to debug.</p>
</li>
<li>
-<p>The duplicate-ISBN test deliberately catches the constraint failure inside the second <code>save</code> call rather than letting it throw. <code>unique: true</code> constraint failures surface as <code>errors.hasErrors()</code>, not as exceptions, in GORM 7+.</p>
+<p>The duplicate-ISBN test first <strong>flushes</strong> the persisted book (<code>Book.withSession { it.flush() }</code>) so the <code>unique</code> validator can see it - without the flush the second insert is still pending and validation passes. It then expects the second <code>save</code> to throw: a GORM <code>@Service</code> save applies <code>failOnError</code> semantics, so a <code>unique: true</code> violation surfaces as a thrown <code>grails.validation.ValidationException</co [...]
</li>
</ul>
</div>
diff --git a/guides/grails-spock-test-tour/8/guide/pages/whatYouWillBuild.html b/guides/grails-spock-test-tour/8/guide/pages/whatYouWillBuild.html
index 45760ee9132..41ac5fa3104 100644
--- a/guides/grails-spock-test-tour/8/guide/pages/whatYouWillBuild.html
+++ b/guides/grails-spock-test-tour/8/guide/pages/whatYouWillBuild.html
@@ -106,7 +106,7 @@ function addJsClass() {
<p><code>BookService.groovy</code> - an <code>@Service(Book)</code> GORM data service with <code>findByIsbn</code>, <code>countByPageCountGreaterThanEquals</code>, and the standard CRUD methods.</p>
</li>
<li>
-<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> so the JSON CRUD surface is testable from <code>ControllerUnitTest</code>.</p>
+<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> exposing a JSON CRUD surface (testable from <code>ControllerUnitTest</code>) whose <code>index</code> action also renders an HTML table at <code>/books</code> for the functional test to drive.</p>
</li>
<li>
<p>Five spec files exercising the five test layers:</p>
diff --git a/guides/grails-spock-test-tour/8/guide/platform.html b/guides/grails-spock-test-tour/8/guide/platform.html
index 977414200a2..695eaabfb86 100644
--- a/guides/grails-spock-test-tour/8/guide/platform.html
+++ b/guides/grails-spock-test-tour/8/guide/platform.html
@@ -120,7 +120,7 @@ function addJsClass() {
jacocoTestReport {
dependsOn test, integrationTest
- executionData fileTree(buildDir).include(<span class="string"><span class="delimiter">'</span><span class="content">jacoco/*.exec</span><span class="delimiter">'</span></span>)
+ executionData fileTree(layout.buildDirectory.get().asFile).include(<span class="string"><span class="delimiter">'</span><span class="content">jacoco/*.exec</span><span class="delimiter">'</span></span>)
reports {
xml.required = <span class="predefined-constant">true</span> <span class="comment">// for Codecov upload</span>
html.required = <span class="predefined-constant">true</span> <span class="comment">// for human inspection</span>
diff --git a/guides/grails-spock-test-tour/8/guide/single.html b/guides/grails-spock-test-tour/8/guide/single.html
index 357931921ba..97aad7b14df 100644
--- a/guides/grails-spock-test-tour/8/guide/single.html
+++ b/guides/grails-spock-test-tour/8/guide/single.html
@@ -177,7 +177,7 @@
<p><code>BookService.groovy</code> - an <code>@Service(Book)</code> GORM data service with <code>findByIsbn</code>, <code>countByPageCountGreaterThanEquals</code>, and the standard CRUD methods.</p>
</li>
<li>
-<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> so the JSON CRUD surface is testable from <code>ControllerUnitTest</code>.</p>
+<p><code>BookController.groovy</code> - a <code>RestfulController<Book></code> exposing a JSON CRUD surface (testable from <code>ControllerUnitTest</code>) whose <code>index</code> action also renders an HTML table at <code>/books</code> for the functional test to drive.</p>
</li>
<li>
<p>Five spec files exercising the five test layers:</p>
@@ -356,12 +356,31 @@ cd grails-spock-test-tour/complete
<span class="type">class</span> <span class="class">BookSpec</span> <span class="directive">extends</span> Specification <span class="directive">implements</span> DomainUnitTest<<span class="predefined-type">Book</span>> {
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a book with no title</span><span class="delimiter">"</span></span>() {
- <span class="key">when</span>:
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">title is omitted from the map constructor, so it is null</span><span class="delimiter">'</span></span>
<span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>)
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the nullable constraint - not blank - is what fires for a null value</span><span class="delimiter">'</span></span>
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">nullable</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a blank title</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a blank string is assigned directly (the map constructor would convert it to null)</span><span class="delimiter">'</span></span>
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>)
+ b.title = <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
+
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">now the blank constraint fires</span><span class="delimiter">'</span></span>
+ !b.validate()
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a title longer than maxSize</span><span class="delimiter">"</span></span>() {
+ <span class="key">when</span>:
+ <span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">x</span><span class="delimiter">'</span></span> * <span class="integer">256</span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span [...]
+
<span class="key">then</span>:
!b.validate()
- b.errors.fieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">blank</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">maxSize.exceeded</span><span class="delimiter">'</span></span>
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">rejects a book with a malformed ISBN</span><span class="delimiter">"</span></span>() {
@@ -370,7 +389,7 @@ cd grails-spock-test-tour/complete
<span class="key">then</span>:
!b.validate()
- b.errors.fieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
+ b.errors.getFieldError(<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>).code == <span class="string"><span class="delimiter">'</span><span class="content">matches.invalid</span><span class="delimiter">'</span></span>
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">accepts a book with a valid ISBN-13</span><span class="delimiter">"</span></span>() {
@@ -406,7 +425,7 @@ cd grails-spock-test-tour/complete
<div class="ulist">
<ul>
<li>
-<p><code>b.errors.fieldError('title').code == 'blank'</code> checks the <strong>constraint code</strong>, not the localised message. Codes are stable across releases and locales; messages are not.</p>
+<p><code>b.errors.getFieldError('title').code</code> checks the <strong>constraint code</strong>, not the localised message. Codes are stable across releases and locales; messages are not. Note the subtlety the spec demonstrates: omitting <code>title</code> from the map constructor leaves it <code>null</code>, so the <code>nullable</code> code fires - not <code>blank</code>. To exercise the <code>blank</code> constraint you must assign <code>b.title = ''</code> <strong>directly</strong>, [...]
</li>
<li>
<p><code>@Unroll</code> plus a <code>where:</code> data table collapses what would otherwise be five copy-pasted tests into one parameterised spec. The <code>#pageCount</code> token in the test name expands to the actual value, so the IDE’s run-tree shows each row separately.</p>
@@ -451,10 +470,12 @@ cd grails-spock-test-tour/complete
<span class="predefined-type">Class</span><span class="type">[]</span> getDomainClassesToMock() { [<span class="predefined-type">Book</span>] }
<span class="type">void</span> setup() {
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Short Story</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">50</span> ).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novella</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">150</span>).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novel</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000003</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">400</span>).save( [...]
- <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Doorstopper</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000004</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">900</span>).save( [...]
+ <span class="comment">// flush: true forces the in-memory datastore to persist before the</span>
+ <span class="comment">// GORM finders below query it - without it the finders see zero rows.</span>
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Short Story</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000001</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">50</span> ).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novella</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000002</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">150</span>).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Novel</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000003</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">400</span>).save( [...]
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Doorstopper</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780000000004</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">900</span>).save( [...]
}
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">countByPageCountGreaterThanEquals returns the right count</span><span class="delimiter">"</span></span>() {
@@ -536,9 +557,10 @@ cd grails-spock-test-tour/complete
<span class="predefined-type">Book</span> b = <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</sp [...]
.save(<span class="key">failOnError</span>: <span class="predefined-constant">true</span>, <span class="key">flush</span>: <span class="predefined-constant">true</span>)
- <span class="key">when</span>:
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">RestfulController.show() reads params.id - it takes no argument</span><span class="delimiter">'</span></span>
request.method = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
- controller.show(b.id)
+ params.id = b.id
+ controller.show()
<span class="key">then</span>:
response.status == HttpStatus.OK.value()
@@ -548,7 +570,8 @@ cd grails-spock-test-tour/complete
<span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">GET /books/{id} for a missing id returns 404</span><span class="delimiter">"</span></span>() {
<span class="key">when</span>:
request.method = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
- controller.show(<span class="integer">99999L</span>)
+ params.id = <span class="integer">99999L</span>
+ controller.show()
<span class="key">then</span>:
response.status == HttpStatus.NOT_FOUND.value()
@@ -596,7 +619,7 @@ cd grails-spock-test-tour/complete
<div class="paragraph">
-<p><code>@Integration</code> boots the full Spring context against a real datasource (whatever the <code>test</code> environment in <code>application.yml</code> configures - H2 by default). <code>@Rollback</code> rolls back every test method’s database changes so specs stay isolated.</p>
+<p><code>@Integration</code> boots the full Spring context against a real datasource - the <code>test</code> environment here points at a Testcontainers-managed PostgreSQL database (<code>jdbc:tc:postgresql:…​</code> in <code>application-test.yml</code>), so the specs run against the same engine as production. <code>@Rollback</code> rolls back every test method’s database changes so specs stay isolated.</p>
</div>
<div class="listingblock">
<div class="title">src/integration-test/groovy/example/BookIntegrationSpec.groovy</div>
@@ -605,6 +628,7 @@ cd grails-spock-test-tour/complete
<span class="keyword">import</span> <span class="include">grails.gorm.transactions.Rollback</span>
<span class="keyword">import</span> <span class="include">grails.testing.mixin.integration.Integration</span>
+<span class="keyword">import</span> <span class="include">grails.validation.ValidationException</span>
<span class="keyword">import</span> <span class="include">spock.lang.Specification</span>
<span class="comment">/**
@@ -640,15 +664,17 @@ cd grails-spock-test-tour/complete
reloaded.isbn == <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>
}
- <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">saving a book with a duplicate isbn fails validation</span><span class="delimiter">"</span></span>() {
- <span class="key">given</span>:
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">saving a book with a duplicate isbn is rejected</span><span class="delimiter">"</span></span>() {
+ <span class="key">given</span>: <span class="string"><span class="delimiter">'</span><span class="content">a persisted book, flushed so the unique validator can see it</span><span class="delimiter">'</span></span>
bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">First</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">100</span>))
+ <span class="predefined-type">Book</span>.withSession { <span class="local-variable">it</span>.flush() }
- <span class="key">when</span>:
- <span class="predefined-type">Book</span> second = bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Second</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class=" [...]
+ <span class="key">when</span>: <span class="string"><span class="delimiter">'</span><span class="content">a second book reuses the isbn</span><span class="delimiter">'</span></span>
+ bookService.save(<span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">Second</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780547928227</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">200</span>))
- <span class="key">then</span>:
- second == <span class="predefined-constant">null</span> || second.hasErrors()
+ <span class="key">then</span>: <span class="string"><span class="delimiter">'</span><span class="content">the @Service save throws a ValidationException (failOnError is implicit) carrying the unique error</span><span class="delimiter">'</span></span>
+ ValidationException ex = thrown()
+ ex.message.contains(<span class="string"><span class="delimiter">'</span><span class="content">unique</span><span class="delimiter">'</span></span>)
}
}</code></pre>
</div>
@@ -665,7 +691,7 @@ cd grails-spock-test-tour/complete
<p><code>@Rollback</code> is non-negotiable. Without it, the second test sees the first test’s data and the third test sees both. Specs become order-dependent and impossible to debug.</p>
</li>
<li>
-<p>The duplicate-ISBN test deliberately catches the constraint failure inside the second <code>save</code> call rather than letting it throw. <code>unique: true</code> constraint failures surface as <code>errors.hasErrors()</code>, not as exceptions, in GORM 7+.</p>
+<p>The duplicate-ISBN test first <strong>flushes</strong> the persisted book (<code>Book.withSession { it.flush() }</code>) so the <code>unique</code> validator can see it - without the flush the second insert is still pending and validation passes. It then expects the second <code>save</code> to throw: a GORM <code>@Service</code> save applies <code>failOnError</code> semantics, so a <code>unique: true</code> violation surfaces as a thrown <code>grails.validation.ValidationException</co [...]
</li>
</ul>
</div>
@@ -705,23 +731,129 @@ cd grails-spock-test-tour/complete
* @Integration is mandatory: GrailsContainerGebExtension throws at
* runtime if the annotation is missing. @Rollback is NOT used here -
* functional tests exercise the full HTTP stack and need committed
- * data.
+ * data. The fixture is therefore seeded inside its own
+ * withNewTransaction block; a bare GORM call would fail because an
+ * @Integration spec without @Rollback has no ambient Hibernate session.
*/</span>
<span class="annotation">@Integration</span>
<span class="type">class</span> <span class="class">BookFunctionalSpec</span> <span class="directive">extends</span> ContainerGebSpec {
- <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index page renders the seeded books</span><span class="delimiter">"</span></span>() {
+ <span class="type">void</span> setup() {
+ <span class="predefined-type">Book</span>.withNewTransaction {
+ <span class="keyword">if</span> (!<span class="predefined-type">Book</span>.findByIsbn(<span class="string"><span class="delimiter">'</span><span class="content">9780261103344</span><span class="delimiter">'</span></span>)) {
+ <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>: <span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>, <span class="key">isbn</span>: <span class="string"><span class="delimiter">'</span><span class="content">9780261103344</span><span class="delimiter">'</span></span>, <span class="key">pageCount</span>: <span class="integer">310</span>) [...]
+ }
+ }
+ }
+
+ <span class="type">void</span> <span class="string"><span class="delimiter">"</span><span class="content">the book index page renders the committed books</span><span class="delimiter">"</span></span>() {
<span class="key">when</span>:
go <span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>
<span class="key">then</span>:
title.contains(<span class="string"><span class="delimiter">'</span><span class="content">Book</span><span class="delimiter">'</span></span>)
<span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table tbody tr</span><span class="delimiter">'</span></span>).size() > <span class="integer">0</span>
+ <span class="error">$</span>(<span class="string"><span class="delimiter">'</span><span class="content">table tbody</span><span class="delimiter">'</span></span>).text().contains(<span class="string"><span class="delimiter">'</span><span class="content">The Hobbit</span><span class="delimiter">'</span></span>)
+ }
+}</code></pre>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_page_the_test_drives">The page the test drives</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>go '/books'</code> needs a real HTML page with a table. <code>BookController</code> stays a <code>RestfulController</code> for the JSON CRUD surface, but its <code>index</code> action is overridden so the HTML format renders a GSP while JSON clients keep their collection response:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/controllers/example/BookController.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="keyword">import</span> <span class="include">grails.rest.RestfulController</span>
+
+<span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController<<span class="predefined-type">Book</span>> {
+ <span class="comment">// 'json' keeps the REST CRUD surface; 'html' lets the index action render</span>
+ <span class="comment">// grails-app/views/book/index.gsp so a browser (and the Geb functional</span>
+ <span class="comment">// test) gets a real HTML table at /books.</span>
+ <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">html</span><span class="delimiter">'</span></span>]
+ BookService bookService
+ BookController() { <span class="local-variable">super</span>(<span class="predefined-type">Book</span>) }
+
+ <span class="comment">// Override index so the HTML format renders the GSP table view (through the</span>
+ <span class="comment">// sitemesh layout) while JSON clients still get the REST collection.</span>
+ <span class="keyword">def</span> <span class="function">index</span>(<span class="predefined-type">Integer</span> max) {
+ params.max = <span class="predefined-type">Math</span>.min(max ?: <span class="integer">100</span>, <span class="integer">100</span>)
+ <span class="predefined-type">List</span><<span class="predefined-type">Book</span>> books = listAllResources(params)
+ withFormat {
+ html { [<span class="key">bookList</span>: books, <span class="key">bookCount</span>: countResources()] }
+ json { respond books, [<span class="key">model</span>: [<span class="key">bookCount</span>: countResources()]] }
+ }
}
}</code></pre>
</div>
</div>
<div class="paragraph">
+<p>A <code>resources</code> URL mapping exposes the controller at <code>/books</code>:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/controllers/example/UrlMappings.groovy</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> example
+
+<span class="type">class</span> <span class="class">UrlMappings</span> {
+ <span class="directive">static</span> mappings = {
+ <span class="string"><span class="delimiter">"</span><span class="content">/books</span><span class="delimiter">"</span></span>(<span class="key">resources</span>: <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>namespace</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span clas [...]
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>controller</span><span class="content">/</span><span class="inline"><span class="inline-delimiter">$</span>action</span><span class="content">?/</span><span class="inline"><span class="inline-delimiter">$</span>id</span><span class="content">?(.</span><span class="inline"><span class="inline-delimiter">$</span>format</span><span class [...]
+ constraints {
+ <span class="comment">// apply constraints here</span>
+ }
+ }
+
+ <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">"</span><span class="content">/index</span><span class="delimiter">"</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">500</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/error</span><span class="delimiter">'</span></span>)
+ <span class="string"><span class="delimiter">"</span><span class="content">404</span><span class="delimiter">"</span></span>(<span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">/notFound</span><span class="delimiter">'</span></span>)
+
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>and a minimal GSP renders the table the spec asserts against:</p>
+</div>
+<div class="listingblock">
+<div class="title">grails-app/views/book/index.gsp</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="html"><span class="doctype"><!DOCTYPE html></span>
+<span class="tag"><html></span>
+<span class="tag"><head></span>
+ <span class="tag"><meta</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">layout</span><span class="delimiter">"</span></span> <span class="attribute-name">content</span>=<span class="string"><span class="delimiter">"</span><span class="content">main</span><span class="delimiter">"</span></span><span class="tag">/></span>
+ <span class="tag"><title></span>Book List<span class="tag"></title></span>
+<span class="tag"></head></span>
+<span class="tag"><body></span>
+<span class="tag"><h1></span>Book List<span class="tag"></h1></span>
+<span class="tag"><table></span>
+ <span class="tag"><thead></span>
+ <span class="tag"><tr></span><span class="tag"><th></span>Title<span class="tag"></th></span><span class="tag"><th></span>ISBN<span class="tag"></th></span><span class="tag"><th></span>Pages<span class="tag"></th></span><span class="tag"></tr></span>
+ <span class="tag"></thead></span>
+ <span class="tag"><tbody></span>
+ <span class="tag"><g:each</span> <span class="attribute-name">in</span>=<span class="string"><span class="delimiter">"</span><span class="content">${bookList}</span><span class="delimiter">"</span></span> <span class="attribute-name">var</span>=<span class="string"><span class="delimiter">"</span><span class="content">book</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><tr></span>
+ <span class="tag"><td></span>${book.title}<span class="tag"></td></span>
+ <span class="tag"><td></span>${book.isbn}<span class="tag"></td></span>
+ <span class="tag"><td></span>${book.pageCount}<span class="tag"></td></span>
+ <span class="tag"></tr></span>
+ <span class="tag"></g:each></span>
+ <span class="tag"></tbody></span>
+<span class="tag"></table></span>
+<span class="tag"></body></span>
+<span class="tag"></html></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Because the spec is <code>@Integration</code> <strong>without</strong> <code>@Rollback</code>, it seeds its fixture inside a <code>withNewTransaction</code> block so the row is committed and visible to the browser. A bare GORM call in an un-rolled-back <code>@Integration</code> spec has no ambient Hibernate session and would throw. <code>BootStrap</code> seed data is <strong>not</strong> a substitute here: it does not populate the test database in the integration context, so the spec [...]
+</div>
+<div class="paragraph">
<p>Three patterns to highlight:</p>
</div>
<div class="ulist">
@@ -759,6 +891,8 @@ cd grails-spock-test-tour/complete
<div class="paragraph">
<p>The matching <a href="../grails-github-actions-cicd/8/guide/index.html">CI/CD guide</a> models this as a four-stage job graph (validation → unit → integration → functional) so a broken unit test does not waste 60 seconds on functional runs. The CI runner needs Docker available too; GitHub-hosted Linux runners ship with Docker out of the box.</p>
</div>
+</div>
+</div>
<h1 id="parameterised">8 Parameterised where: Data Tables</h1>
@@ -857,7 +991,7 @@ cd grails-spock-test-tour/complete
jacocoTestReport {
dependsOn test, integrationTest
- executionData fileTree(buildDir).include(<span class="string"><span class="delimiter">'</span><span class="content">jacoco/*.exec</span><span class="delimiter">'</span></span>)
+ executionData fileTree(layout.buildDirectory.get().asFile).include(<span class="string"><span class="delimiter">'</span><span class="content">jacoco/*.exec</span><span class="delimiter">'</span></span>)
reports {
xml.required = <span class="predefined-constant">true</span> <span class="comment">// for Codecov upload</span>
html.required = <span class="predefined-constant">true</span> <span class="comment">// for human inspection</span>
diff --git a/guides/grails-tailwindcss/8/guide/componentLayer.html b/guides/grails-tailwindcss/8/guide/componentLayer.html
index e443de48f84..d83e3391e9e 100644
--- a/guides/grails-tailwindcss/8/guide/componentLayer.html
+++ b/guides/grails-tailwindcss/8/guide/componentLayer.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -76,7 +79,7 @@ function addJsClass() {
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span> >></a></div>
@@ -183,7 +186,7 @@ function addJsClass() {
<div class="toc-item prev-left"><a href="../guide/darkMode.html"><< <strong>7</strong><span>Class-Based Dark Mode</span></a></div>
- <div class="toc-item next-right"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span> >></a></div>
+ <div class="toc-item next-right"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span> >></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/configureTailwind.html b/guides/grails-tailwindcss/8/guide/configureTailwind.html
index d19d3114d9d..ddb2c46267b 100644
--- a/guides/grails-tailwindcss/8/guide/configureTailwind.html
+++ b/guides/grails-tailwindcss/8/guide/configureTailwind.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/createApp.html b/guides/grails-tailwindcss/8/guide/createApp.html
index fbb5cdcffb2..a94ad1581ea 100644
--- a/guides/grails-tailwindcss/8/guide/createApp.html
+++ b/guides/grails-tailwindcss/8/guide/createApp.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/darkMode.html b/guides/grails-tailwindcss/8/guide/darkMode.html
index 63949639903..2d2b656587b 100644
--- a/guides/grails-tailwindcss/8/guide/darkMode.html
+++ b/guides/grails-tailwindcss/8/guide/darkMode.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/firstPaint.html b/guides/grails-tailwindcss/8/guide/firstPaint.html
index 84681371660..e78e2d1fd8c 100644
--- a/guides/grails-tailwindcss/8/guide/firstPaint.html
+++ b/guides/grails-tailwindcss/8/guide/firstPaint.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/gettingStarted.html b/guides/grails-tailwindcss/8/guide/gettingStarted.html
index 0593c97015d..dd8f307b094 100644
--- a/guides/grails-tailwindcss/8/guide/gettingStarted.html
+++ b/guides/grails-tailwindcss/8/guide/gettingStarted.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/gradleWiring.html b/guides/grails-tailwindcss/8/guide/gradleWiring.html
index 862dcceff7c..1244c4847ed 100644
--- a/guides/grails-tailwindcss/8/guide/gradleWiring.html
+++ b/guides/grails-tailwindcss/8/guide/gradleWiring.html
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/helpWithGrails.html b/guides/grails-tailwindcss/8/guide/helpWithGrails.html
index 29bebfc77ad..6e1091064ee 100644
--- a/guides/grails-tailwindcss/8/guide/helpWithGrails.html
+++ b/guides/grails-tailwindcss/8/guide/helpWithGrails.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
- <title>9 Do you need help with Grails?</title>
+ <title>10 Do you need help with Grails?</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/guide.css" type="text/css" media="screen, print" title="Style" charset="utf-8" />
@@ -54,7 +54,10 @@ function addJsClass() {
<div class="toc-item" style="margin-left:0"><a href="../guide/componentLayer.html"><strong>8</strong><span>Reusable Component Classes with @apply</span></a>
</div>
- <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>9</strong><span>Do you need help with Grails?</span></a>
+ <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>9</strong><span>Testing the Tailwind Build</span></a>
+ </div>
+
+ <div class="toc-item" style="margin-left:0"><a href="../guide/helpWithGrails.html"><strong>10</strong><span>Do you need help with Grails?</span></a>
</div>
</div>
@@ -72,7 +75,7 @@ function addJsClass() {
<div id="main" class="corner-all">
- <div class="toc-item prev-left"><a href="../guide/componentLayer.html"><< <strong>8</strong><span>Reusable Component Classes with @apply</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>9</strong><span>Testing the Tailwind Build</span></a></div>
@@ -82,7 +85,7 @@ function addJsClass() {
-<h1 id="helpWithGrails">9 Do you need help with Grails?</h1>
+<h1 id="helpWithGrails">10 Do you need help with Grails?</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/apache/grails-static-website/edit/master/guides/grails-tailwindcss/v8/guide/helpWithGrails.adoc"'>
@@ -132,7 +135,7 @@ function addJsClass() {
<div style="clear:both;margin-top:15px;"></div>
- <div class="toc-item prev-left"><a href="../guide/componentLayer.html"><< <strong>8</strong><span>Reusable Component Classes with @apply</span></a></div>
+ <div class="toc-item prev-left"><a href="../guide/testing.html"><< <strong>9</strong><span>Testing the Tailwind Build</span></a></div>
<div style="clear:both"></div>
</div>
diff --git a/guides/grails-tailwindcss/8/guide/index.html b/guides/grails-tailwindcss/8/guide/index.html
index 461fb07e42a..c1a539e289e 100644
--- a/guides/grails-tailwindcss/8/guide/index.html
+++ b/guides/grails-tailwindcss/8/guide/index.html
@@ -127,7 +127,9 @@
<div class="toc-item" style="margin-left:0px"><a href="#componentLayer"><strong>8</strong><span>Reusable Component Classes with @apply</span></a></div>
- <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>9</strong><span>Do you need help with Grails?</span></a></div>
+ <div class="toc-item" style="margin-left:0px"><a href="#testing"><strong>9</strong><span>Testing the Tailwind Build</span></a></div>
+
+ <div class="toc-item" style="margin-left:0px"><a href="#helpWithGrails"><strong>10</strong><span>Do you need help with Grails?</span></a></div>
<div style="clear:both"></div>
</div>
@@ -1125,7 +1127,133 @@ tasks.named(<span class="string"><span class="delimiter">'</span><span class="co
</div>
-<h1 id="helpWithGrails">9 Do you need help with Grails?</h1>
+<h1 id="testing">9 Testing the Tailwind Build</h1>
+
... 2753 lines suppressed ...