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 }