Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
15 changes: 15 additions & 0 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -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
Expand Down
87 changes: 87 additions & 0 deletions buildSrc/src/main/groovy/VerifyTestServices.groovy
Original file line number Diff line number Diff line change
@@ -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 <https://www.gnu.org/licenses/>.
*
* 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() <deadline) {
if (!postgresReady) {
postgresReady = isPostgresReady()
}
if (!keycloakReady) {
keycloakReady = isKeycloakReady()
}
if (!postgresReady || !keycloakReady) {
Thread.sleep(500)
}
}

def unavailable = []
if (!postgresReady) {
unavailable << 'PostgreSQL on 127.0.0.1:5432'
}
if (!keycloakReady) {
unavailable << 'Keycloak at http://127.0.0.1:8081/auth'
}
if (unavailable) {
throw new GradleException("Timed out after ${timeoutSeconds} seconds waiting for ${unavailable.join(' and ')}. Start the test services with `docker compose -f profile/dev-testing.yml -p openremote up -d --no-build`.")
}
}

private static boolean isPostgresReady() {
def socket = new Socket()
try {
socket.connect(new InetSocketAddress('127.0.0.1', 5432), 500)
return true
} catch (IOException ignored) {
return false
} finally {
try {
socket.close()
} catch (IOException ignored) {
}
}
}

private static boolean isKeycloakReady() {
HttpURLConnection connection = null
try {
connection = (HttpURLConnection) new URL('http://127.0.0.1:8081/auth/realms/master/.well-known/openid-configuration').openConnection()
connection.connectTimeout = 500
connection.readTimeout = 500
return connection.responseCode == HttpURLConnection.HTTP_OK
} catch (IOException ignored) {
return false
} finally {
connection?.disconnect()
}
}
}
27 changes: 11 additions & 16 deletions deployment/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,9 @@ dependencies {
managerRuntime libs.openremote.manager
}

tasks.register('license') {
doLast {
def licenseFiles = new ArrayList<>()
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) {
Expand All @@ -37,6 +24,8 @@ tasks.register('installDist', Copy) {
it.project != project
})

dependsOn tasks.named('license')

into("$buildDir")

from "Dockerfile"
Expand All @@ -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')
}
9 changes: 3 additions & 6 deletions project.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down
31 changes: 2 additions & 29 deletions test/build.gradle
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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')
}
Loading
Loading