diff --git a/README.md b/README.md
index 18f4a83d9..4e938d79d 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,51 @@ Follow the initial guides on the OpenRemote documentation on [preparing the envi
_(Please describe the steps necessary to run this custom project locally.)_
+### Building and testing
+
+Use JDK 21 and the Yarn version configured in `package.json`.
+The project uses the same lifecycle and targeted test tasks as OpenRemote Core:
+
+```sh
+./gradlew assemble # Build backend JARs and UI bundles
+./gradlew check # Run tests and Spotless checks
+./gradlew build # Build and verify the project
+./gradlew installDist # Prepare the deployment Docker build context
+./gradlew test # Run backend tests followed by UI tests
+./gradlew testBackend # Run backend unit tests followed by integration tests
+./gradlew testBackendUnit # Run backend unit tests only
+./gradlew testBackendIntegration # Run backend integration tests only
+./gradlew testUi # Run UI component tests followed by app tests
+./gradlew testUiComponent # Run registered UI component tests only
+./gradlew testUiApp # Run registered UI app tests only
+```
+
+Use `./gradlew clean assemble` for a clean artifact build, or `./gradlew clean build` to include verification.
+`assemble` does not prepare the deployment or build Docker images.
+`installDist` prepares the Docker build context in `deployment/build/` without running verification.
+
+Run `./gradlew testBackendUnit unitTestReport` to run backend unit tests and generate a combined HTML report at `build/reports/tests/test/aggregated-results/index.html`.
+The report excludes integration tests and UI tests.
+Shared test groups, unit test reporting, and integration test configuration are defined in `testing.gradle`.
+
+Before running backend integration tests, start PostgreSQL and Keycloak:
+
+```sh
+docker compose -f profile/dev-testing.yml -p openremote up -d --no-build
+```
+
+Gradle waits up to 30 seconds for PostgreSQL and Keycloak before backend integration tests, including direct `:test:test` runs.
+If either service is unavailable, the build fails before test preparation and reports the startup command above.
+Backend unit tests and the template's UI component tests do not require these services.
+
+UI tests are included when their module registers an `npmTest` task.
+The template's component test scripts are placeholders; app tests must be added by the custom project.
+UI component test tasks prepare generated TypeScript sources automatically, and UI app test tasks prepare the deployment.
+Pass `-PreuseUiTestArtifacts=true` only when the required build outputs already exist, such as after downloading CI artifacts.
+Individual UI test tasks accept `-Pargs` for test runner options, for example `-Pargs="--shard=1/4"` for Playwright.
+When an app test requires local PostgreSQL and Keycloak, add `dependsOn rootProject.tasks.named('verifyTestServices')` to its `npmTest` task.
+Declare browser installation and availability checks on tasks that use a browser test runner.
+
### Docker Compose files
In the `profile` directory you can find different Docker Compose files, each serving a different purpose. To be able to use them, you'll need to download a copy of the `deploy.yml` file from the main OpenRemote repository and place it in the `openremote/profile` directory, to ensure you always have the latest version of the file:
diff --git a/build.gradle b/build.gradle
index 04873d17f..585e76f52 100644
--- a/build.gradle
+++ b/build.gradle
@@ -4,6 +4,8 @@ import static org.apache.tools.ant.taskdefs.condition.Os.FAMILY_WINDOWS
import static org.apache.tools.ant.taskdefs.condition.Os.isFamily
plugins {
+ id 'base'
+ id 'test-report-aggregation'
alias libs.plugins.axionRelease
alias libs.plugins.fileEncrypt apply false
}
@@ -26,6 +28,19 @@ allprojects {
apply from: "${rootDir}/project.gradle"
}
+// build combines assemble (backend and UI artifacts) and check (tests and Spotless).
+// installDist prepares the deployment without running verification.
+apply from: "${rootDir}/testing.gradle"
+
+tasks.named('assemble') {
+ dependsOn subprojects.collect { it.tasks.matching { t -> t.name == 'assemble' } }
+}
+
+tasks.named('check') {
+ dependsOn tasks.named('test')
+ dependsOn subprojects.collect { it.tasks.matching { t -> t.name == 'check' } }
+}
+
// Uncomment the following to configure files to be encrypted/decrypted
// Each file must be explicitly added to .gitignore otherwise git commit will fail
// When using encryption the the GFE_PASSWORD environment variable must be set or the build will fail
diff --git a/buildSrc/src/main/groovy/VerifyTestServices.groovy b/buildSrc/src/main/groovy/VerifyTestServices.groovy
new file mode 100644
index 000000000..4bcbbe089
--- /dev/null
+++ b/buildSrc/src/main/groovy/VerifyTestServices.groovy
@@ -0,0 +1,87 @@
+/*
+ * Copyright 2026, OpenRemote Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see .
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import java.util.concurrent.TimeUnit
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.tasks.TaskAction
+import org.gradle.work.DisableCachingByDefault
+
+@DisableCachingByDefault(because = 'Checks the current availability of external test services')
+class VerifyTestServices extends DefaultTask {
+
+ @TaskAction
+ void verifyServices() {
+ def timeoutSeconds = 30L
+ def deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(timeoutSeconds)
+ def postgresReady = false
+ def keycloakReady = false
+ while ((!postgresReady || !keycloakReady) && System.nanoTime() ()
- licenseFiles.add("${rootDir}/LICENSE.txt")
-
- def toConcatenate = files(licenseFiles.toArray())
- def outputFileName = "${buildDir}/image/manager/app/LICENSE.txt"
- def output = new File(outputFileName)
- if (output.exists()) {
- output.delete()
- }
- output.getParentFile().mkdirs()
- output.createNewFile()
- output.write('') // truncate output if needed
- toConcatenate.each { f -> output << f.text }
- }
+tasks.register('license', Copy) {
+ from(rootProject.layout.projectDirectory.file("LICENSE.txt"))
+ into(layout.buildDirectory.dir("image/manager/app"))
}
tasks.register('installDist', Copy) {
@@ -37,6 +24,8 @@ tasks.register('installDist', Copy) {
it.project != project
})
+ dependsOn tasks.named('license')
+
into("$buildDir")
from "Dockerfile"
@@ -60,3 +49,9 @@ tasks.register('installDist', Copy) {
}
}
}
+
+// installDist writes into build/, which also contains the deployment JAR's inputs.
+// Keep the tasks ordered when assembling and installing in the same invocation.
+tasks.named('jar') {
+ mustRunAfter tasks.named('installDist')
+}
diff --git a/project.gradle b/project.gradle
index 09ed099ba..cdee457ea 100644
--- a/project.gradle
+++ b/project.gradle
@@ -344,11 +344,6 @@ tasks.register('npmClean', Exec) {
dependsOn getYarnInstallTask()
commandLine npmCommand("yarn"), "run", "clean"
}
-tasks.register('npmBuild', Exec) {
- mustRunAfter npmClean
- dependsOn getYarnInstallTask()
- commandLine npmCommand("yarn"), "run", "build"
-}
tasks.register('npmServe', Exec) {
dependsOn getYarnInstallTask()
commandLine npmCommand("yarn"), "run", "serve"
@@ -368,7 +363,9 @@ tasks.register('npmServeProduction', Exec) {
// Add typescript tasks
tasks.register('tscWatch', Exec) {
- commandLine npmCommand("npx"), "tsc", "-b", "--watch"
+ dependsOn getYarnInstallTask()
+ // TypeScript is a root workspace dependency; keep the build target in this project.
+ commandLine npmCommand("yarn"), "run", "--top-level", "tsc", "-b", projectDir.absolutePath, "--watch"
}
// Configure Java build
diff --git a/test/build.gradle b/test/build.gradle
index 1a9cf1ee5..2d2ff8174 100644
--- a/test/build.gradle
+++ b/test/build.gradle
@@ -1,6 +1,3 @@
-import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-import org.gradle.api.tasks.testing.logging.TestLogEvent
-
plugins {
id 'java-library'
id 'groovy'
@@ -16,32 +13,8 @@ dependencies {
tasks.withType(Test).configureEach {
environment("LOGGING_CONFIG_FILE", "test/src/logging-test.properties")
- addTestListener(new TestSummaryListener())
}
-test {
- workingDir = findProject(":openremote") != null ? project(":openremote").projectDir : rootProject.projectDir
- useJUnitPlatform()
- testLogging {
- // set options for log level LIFECYCLE
- events = [TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED]
- exceptionFormat = TestExceptionFormat.FULL
- showExceptions = true
- showCauses = true
- showStackTraces = true
-
- // set options for log level DEBUG and INFO
- debug {
- events = [
- TestLogEvent.STARTED,
- TestLogEvent.FAILED,
- TestLogEvent.PASSED,
- TestLogEvent.SKIPPED,
- TestLogEvent.STANDARD_ERROR
- ]
- exceptionFormat = TestExceptionFormat.FULL
- }
- info.events = debug.events
- info.exceptionFormat = debug.exceptionFormat
- }
+tasks.named('test') {
+ dependsOn rootProject.tasks.named('verifyTestServices')
}
diff --git a/testing.gradle b/testing.gradle
new file mode 100644
index 000000000..db8f7af31
--- /dev/null
+++ b/testing.gradle
@@ -0,0 +1,158 @@
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+import org.gradle.api.tasks.testing.logging.TestLogEvent
+
+tasks.register('testBackendUnit') {
+ group = 'verification'
+ description = 'Runs backend unit tests'
+}
+
+tasks.register('testBackendIntegration') {
+ group = 'verification'
+ description = 'Runs backend integration tests'
+}
+
+tasks.register('testBackend') {
+ group = 'verification'
+ description = 'Runs backend unit tests followed by backend integration tests'
+ dependsOn tasks.named('testBackendUnit'), tasks.named('testBackendIntegration')
+}
+
+tasks.register('testUiComponent') {
+ group = 'verification'
+ description = 'Runs UI component tests'
+}
+
+tasks.register('testUiApp') {
+ group = 'verification'
+ description = 'Runs UI app end-to-end tests'
+}
+
+tasks.register('testUi') {
+ group = 'verification'
+ description = 'Runs UI component tests followed by UI app end-to-end tests'
+ dependsOn tasks.named('testUiComponent'), tasks.named('testUiApp')
+}
+
+tasks.register('test') {
+ group = 'verification'
+ description = 'Runs testBackend followed by testUi for all backend and UI tests'
+ dependsOn tasks.named('testBackend'), tasks.named('testUi')
+}
+
+def verifyTestServices = tasks.register('verifyTestServices', VerifyTestServices) {
+ group = 'verification'
+ description = 'Waits for PostgreSQL and Keycloak before service-backed tests'
+}
+
+// Ordering does not schedule the check for tasks that do not depend on it.
+allprojects {
+ tasks.configureEach { task ->
+ if (task.path != ':verifyTestServices') {
+ task.mustRunAfter verifyTestServices
+ }
+ }
+}
+
+gradle.projectsEvaluated {
+ def unitTests = subprojects.findAll { it.path != ':test' && !it.path.startsWith(':ui') }
+ .collect { it.tasks.matching { t -> t.name == 'test' } }
+
+ def integrationTests = subprojects.findAll { it.path == ':test' }
+ .collect { it.tasks.matching { t -> t.name == 'test' } }
+
+ def uiComponentTests = subprojects.findAll { it.path.startsWith(':ui:component') }
+ .collect { it.tasks.matching { t -> t.name == 'npmTest' } }
+
+ def uiAppTests = subprojects.findAll { it.path.startsWith(':ui:app') }
+ .collect { it.tasks.matching { t -> t.name == 'npmTest' } }
+
+ tasks.named('testBackendUnit').configure {
+ dependsOn unitTests
+ }
+
+ tasks.named('testBackendIntegration').configure {
+ dependsOn integrationTests
+ }
+
+ tasks.named('testUiComponent').configure {
+ dependsOn uiComponentTests
+ }
+
+ tasks.named('testUiApp').configure {
+ dependsOn uiAppTests
+ }
+
+ // Order test execution without making standalone UI test commands run backend tests.
+ integrationTests.forEach { group ->
+ group.configureEach { it.mustRunAfter(unitTests) }
+ }
+
+ uiComponentTests.forEach { group ->
+ group.configureEach { it.mustRunAfter(unitTests, integrationTests) }
+ }
+
+ uiAppTests.forEach { group ->
+ group.configureEach { it.mustRunAfter(unitTests, integrationTests, uiComponentTests) }
+ }
+}
+
+dependencies {
+ subprojects.findAll { !it.path.startsWith(':ui') && it.path != ':test' }.each { subproject ->
+ subproject.pluginManager.withPlugin('java') {
+ // Aggregate unit test results spread over different projects
+ testReportAggregation project(subproject.path)
+ }
+ }
+}
+
+reporting {
+ reports {
+ // Task which generates an aggregated unit test report
+ unitTestReport(AggregateTestReport) {
+ testSuiteName = 'test'
+ }
+ }
+}
+
+tasks.named('unitTestReport').configure {
+ doLast {
+ def htmlIndex = new File(destinationDirectory.get().asFile, "index.html")
+ println "Aggregated Unit Test Results: file://${htmlIndex.absolutePath}"
+ }
+}
+
+project(':test') {
+ tasks.withType(Test).configureEach {
+ useJUnitPlatform()
+ addTestListener(new TestSummaryListener())
+
+ testLogging {
+ // set options for log level LIFECYCLE
+ events = [TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED]
+ exceptionFormat = TestExceptionFormat.FULL
+ showExceptions = true
+ showCauses = true
+ showStackTraces = true
+
+ // set options for log level DEBUG and INFO
+ debug {
+ events = [
+ TestLogEvent.STARTED,
+ TestLogEvent.FAILED,
+ TestLogEvent.PASSED,
+ TestLogEvent.SKIPPED,
+ TestLogEvent.STANDARD_ERROR
+ ]
+ exceptionFormat = TestExceptionFormat.FULL
+ }
+ info.events = debug.events
+ info.exceptionFormat = debug.exceptionFormat
+ }
+ }
+
+ afterEvaluate {
+ tasks.withType(Test).configureEach {
+ workingDir = rootProject.projectDir
+ }
+ }
+}
diff --git a/ui/app/custom-react/build.gradle b/ui/app/custom-react/build.gradle
index 510fcb8ff..6a19c1e25 100644
--- a/ui/app/custom-react/build.gradle
+++ b/ui/app/custom-react/build.gradle
@@ -1,5 +1,7 @@
-tasks.register('clean', Delete) {
- delete layout.buildDirectory
+tasks.register('npmBuild', Exec) {
+ mustRunAfter npmClean
+ dependsOn getYarnInstallTask()
+ commandLine npmCommand("yarn"), "run", "build"
}
tasks.register('installDist', Copy) {
diff --git a/ui/app/custom/build.gradle b/ui/app/custom/build.gradle
index 510fcb8ff..6a19c1e25 100644
--- a/ui/app/custom/build.gradle
+++ b/ui/app/custom/build.gradle
@@ -1,5 +1,7 @@
-tasks.register('clean', Delete) {
- delete layout.buildDirectory
+tasks.register('npmBuild', Exec) {
+ mustRunAfter npmClean
+ dependsOn getYarnInstallTask()
+ commandLine npmCommand("yarn"), "run", "build"
}
tasks.register('installDist', Copy) {
diff --git a/ui/build.gradle b/ui/build.gradle
index 6b5908279..8ca4b3cb8 100644
--- a/ui/build.gradle
+++ b/ui/build.gradle
@@ -1,16 +1,101 @@
-afterEvaluate {
- // Add dependencies on model and rest typescript generation
- rootProject.getTasksByName('prepareUi', true).forEach {
- it.dependsOn ":ui:component:model:generateTypeScript", ":ui:component:rest:generateTypeScript"
+import groovy.json.JsonParserType
+import groovy.json.JsonSlurper
+import org.gradle.api.services.BuildService
+import org.gradle.api.services.BuildServiceParameters
+
+plugins {
+ id 'base'
+}
+
+abstract class TypeScriptOutputLock implements BuildService {}
+
+def generatedUiSources = [':ui:component:model:generateTypeScript', ':ui:component:rest:generateTypeScript']
+def uiTestDistTasks = [':deployment:installDist']
+def reuseUiTestArtifacts = providers.gradleProperty('reuseUiTestArtifacts').map {
+ it.toBoolean()
+}.getOrElse(false)
+
+// Each tsc -b or ts-loader process builds its own reference graph. For example,
+// custom can compile model while model's own npmBuild runs tsc -b --force.
+// Waiting for Java-to-TypeScript source generation does not coordinate these
+// later writes to JavaScript, declarations, and .tsbuildinfo files.
+// Collect transitive references, including projects without an npmBuild task,
+// so every compiler that can touch the same outputs uses the same resource.
+def typeScriptProjects = [:]
+def collectTypeScriptProjects
+collectTypeScriptProjects = { File target ->
+ def configFile = (target.directory ? new File(target, 'tsconfig.json') : target).canonicalFile
+ if (!configFile.exists()) {
+ return [] as Set
}
- rootProject.getTasksByName('publishUi', true).forEach {
- it.dependsOn ":ui:component:model:generateTypeScript", ":ui:component:rest:generateTypeScript"
+ if (!typeScriptProjects.containsKey(configFile)) {
+ def projects = [configFile] as Set
+ typeScriptProjects[configFile] = projects
+ // Track the file read so reference changes invalidate the configuration cache.
+ def config = new JsonSlurper().setType(JsonParserType.LAX).parseText(configFile.getText('UTF-8'))
+ // The LAX parser can produce string entries for trailing commas in arrays.
+ config.references?.findAll { it instanceof Map }?.each { reference ->
+ projects.addAll(collectTypeScriptProjects(new File(configFile.parentFile, reference.path)))
+ }
}
- rootProject.getTasksByName('npmBuild', true).forEach {
- it.dependsOn ":ui:component:model:generateTypeScript", ":ui:component:rest:generateTypeScript"
+ typeScriptProjects[configFile]
+}
+
+rootProject.allprojects {
+ tasks.matching {
+ it.name in ['prepareUi', 'publishUi', 'npmBuild']
+ }.configureEach {
+ dependsOn generatedUiSources
+ }
+}
+
+subprojects { uiProject ->
+ apply plugin: 'base'
+
+ tasks.matching { it.name in ['assemble', 'npmBuild', 'npmPrepare', 'npmPublish'] }.configureEach {
+ mustRunAfter tasks.named('clean')
+ }
+
+ tasks.matching { it.name in ['npmPrepare', 'npmPublish'] }.configureEach {
+ mustRunAfter tasks.named('assemble')
+ }
+
+ // npmTest also compiles TypeScript before running Playwright. Gradle cannot
+ // infer these shared outputs from Exec commands, so declare exclusive resources
+ // for each referenced project. The lock covers the entire task, including tests;
+ // independent reference graphs can still run in parallel.
+ tasks.matching { it.name in ['npmBuild', 'npmTest'] }.configureEach {
+ collectTypeScriptProjects(uiProject.projectDir).each { configFile ->
+ def outputLock = gradle.sharedServices.registerIfAbsent("typescript:${configFile.path}", TypeScriptOutputLock) {
+ maxParallelUsages = 1
+ }
+ usesService outputLock
+ }
+ }
+
+ tasks.named('assemble') {
+ dependsOn tasks.matching { it.name == 'npmBuild' }
+ }
+
+ def npmTestTasks = tasks.matching { it.name == 'npmTest' }
+ npmTestTasks.configureEach {
+ mustRunAfter generatedUiSources
+ mustRunAfter uiTestDistTasks
+ // CI can reuse outputs downloaded or built earlier in the job.
+ if (!reuseUiTestArtifacts) {
+ if (uiProject.path.startsWith(':ui:component:')) {
+ dependsOn generatedUiSources
+ } else if (uiProject.path.startsWith(':ui:app:')) {
+ dependsOn uiTestDistTasks
+ }
+ }
+ }
+
+ tasks.named('check') {
+ dependsOn npmTestTasks
}
}
tasks.register('modelWatch') {
- dependsOn ":ui:component:model:build", ":ui:component:rest:build"
+ dependsOn ":ui:component:model:assemble", ":ui:component:rest:assemble"
}
diff --git a/ui/component/model/build.gradle b/ui/component/model/build.gradle
index 53c5abc56..d0b976c26 100644
--- a/ui/component/model/build.gradle
+++ b/ui/component/model/build.gradle
@@ -15,22 +15,21 @@ dependencies {
generateTypeScript createTSGeneratorConfigForModel("src/model.ts", findProject(":model"))
-def generateTypeScriptTask = tasks.named("generateTypeScript") {
+tasks.named("generateTypeScript") {
// Work around typescript-generator exposing non-serializable configuration objects as Gradle task inputs.
doNotTrackState("typescript-generator uses non-serializable task input types")
}
-tasks.named("build") {
- dependsOn generateTypeScriptTask, tasks.named("npmBuild")
-}
-
-tasks.named("npmBuild") {
- dependsOn generateTypeScriptTask
+tasks.register('npmBuild', Exec) {
+ mustRunAfter npmClean
+ dependsOn getYarnInstallTask()
+ commandLine npmCommand("yarn"), "run", "build"
}
tasks.register('npmTest', Exec) {
dependsOn getYarnInstallTask()
commandLine npmCommand("yarn"), "run", "test"
+ args((findProperty('args')?.toString()?.tokenize()) ?: [])
}
tasks.register('prepareUi') {
diff --git a/ui/component/rest/build.gradle b/ui/component/rest/build.gradle
index cbd8b680c..dc37de3e6 100644
--- a/ui/component/rest/build.gradle
+++ b/ui/component/rest/build.gradle
@@ -17,7 +17,7 @@ generateTypeScript createTSGeneratorConfigForClient("src/restclient.ts", new Fil
def resourceJavaFilesCount = countResourceJavaFiles()
-def generateTypeScriptTask = tasks.named("generateTypeScript") {
+tasks.named("generateTypeScript") {
// Work around typescript-generator exposing non-serializable configuration objects as Gradle task inputs.
doNotTrackState("typescript-generator uses non-serializable task input types")
dependsOn ":ui:component:model:generateTypeScript"
@@ -43,24 +43,23 @@ def countResourceJavaFiles() {
return count
}
-tasks.named("build") {
- dependsOn generateTypeScriptTask, tasks.named("npmBuild")
-}
-
-tasks.named("npmBuild") {
- dependsOn generateTypeScriptTask
+tasks.register('npmBuild', Exec) {
onlyIf { resourceJavaFilesCount> 0 }
+ mustRunAfter npmClean
+ dependsOn getYarnInstallTask()
+ commandLine npmCommand("yarn"), "run", "build"
}
tasks.register('npmTest', Exec) {
dependsOn getYarnInstallTask()
commandLine npmCommand("yarn"), "run", "test"
+ args((findProperty('args')?.toString()?.tokenize()) ?: [])
}
tasks.register('prepareUi') {
- dependsOn clean, build, npmPrepare
+ dependsOn clean, assemble, npmPrepare
}
tasks.register('publishUi') {
- dependsOn clean, build, npmPublish
+ dependsOn clean, assemble, npmPublish
}