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
23 changes: 5 additions & 18 deletions .github/workflows/ci_cd.yml
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ jobs:

- name: Check UI dependencies
if: steps.ui-files-changed.outputs.any_modified == 'true' && steps.is_core_repo.outputs.value == 'true'
run: npx knip@5.88.0 -c ui/knip.jsonc
run: yarn knip

- name: Check deployment build.gradle
id: check_deployment_gradle
Expand Down Expand Up @@ -466,16 +466,16 @@ jobs:
- name: Define backend test command
id: test-backend-command
if: ${{ steps.skip-backend-tests.outputs.value != 'true' }}
run: echo "value=./gradlew test -x npmTest" >> $GITHUB_OUTPUT
run: echo "value=./gradlew testBackend" >> $GITHUB_OUTPUT

- name: Define UI component test command
id: test-ui-components-command
if: ${{ steps.skip-ui-component-tests.outputs.value != 'true' }}
run: echo "value=./gradlew -p ui/component npmTest" >> $GITHUB_OUTPUT
run: echo "value=./gradlew testUiComponent -PreuseUiTestArtifacts=true" >> $GITHUB_OUTPUT

- name: Define UI app test command
id: test-ui-apps-command
run: echo "value=./gradlew -p ui/app npmTest" >> $GITHUB_OUTPUT
run: echo "value=./gradlew testUiApp -PreuseUiTestArtifacts=true" >> $GITHUB_OUTPUT

- name: Define manager docker build command
id: manager-docker-command
Expand Down Expand Up @@ -703,20 +703,7 @@ jobs:

- name: Check for outdated translations
if: steps.is_core_repo.outputs.value == 'true'
run: |
set -e

# Run the tests
./gradlew -p ui/app/shared processTranslations --no-parallel

out=$(git status --porcelain | grep "ui/app/shared/locales" || true)
if [[ -z "$out" ]]; then
echo "✅ No pipeline changes detected."
else
echo "❌ Pipeline files have changed. Please run './gradlew -p ui/app/shared processTranslations --no-parallel'"
echo "$out"
exit 1
fi
run: ./gradlew :ui:app:shared:checkTranslations --no-parallel
timeout-minutes: 20

- name: Run backend tests
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/integration-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ jobs:
docker compose -f profile/dev-testing.yml up -d --no-build

# Run the tests
./gradlew :test:test
./gradlew testBackendIntegration
- name: Archive integration test results
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ui-app-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ jobs:
docker compose -f profile/dev-testing.yml up -d --no-build

# Run the tests
./gradlew -p ui/app npmTest -Pargs="--shard=${{ matrix.shardIndex }}/${{ matrix.shardCount }}"
./gradlew testUiApp -PreuseUiTestArtifacts=true -Pargs="--shard=${{ matrix.shardIndex }}/${{ matrix.shardCount }}"
- name: Archive UI app test results
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
Expand Down
16 changes: 1 addition & 15 deletions .github/workflows/ui-check-outdated-translations.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,4 @@ jobs:
cache: "gradle"
- name: Check for outdated translations
timeout-minutes: 20
run: |
# Check Outdated Translations
./gradlew -p ui/app/shared processTranslations --no-parallel

out=$(git status --porcelain | grep "ui/app/shared/locales" || true)
if [[ -z "$out" ]]; then
echo "✅ No pipeline changes detected."
else
echo "❌ Pipeline files have changed. Please run:
\`\`\`sh
./gradlew -p ui/app/shared processTranslations --no-parallel
\`\`\`
$out" >> $GITHUB_STEP_SUMMARY
exit 1
fi
run: ./gradlew :ui:app:shared:checkTranslations --no-parallel
2 changes: 1 addition & 1 deletion .github/workflows/ui-component-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
run: find . -name "*.tsbuildinfo" -exec touch {} +
- name: Run UI component tests
timeout-minutes: 20
run: ./gradlew -p ui/component npmTest
run: ./gradlew testUiComponent -PreuseUiTestArtifacts=true
- name: Archive UI component test results
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
Expand Down
11 changes: 1 addition & 10 deletions .github/workflows/unit-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,9 @@ jobs:
java-version: "21"
cache: "gradle"

- name: Check if core repo
id: is_core_repo
uses: openremote/core/.github/actions/check-if-core-repo@357f1387fbc99e7a59752a62064f0bdade57612d

- name: Run unit tests
timeout-minutes: 20
run: |
if [ "${{ steps.is_core_repo.outputs.value }}" = "true" ]; then
./gradlew test -x :test:test -x npmTest unitTestReport
else
./gradlew test -x :test:test
fi
run: ./gradlew testBackendUnit unitTestReport

- name: Archive unit test results
if: always()
Expand Down
28 changes: 26 additions & 2 deletions AGENTS.md
Comment thread
wborn marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,15 @@ When naming scripts, use \<date>_\<time> as version number, date being YYYYMMDD
## Dev environment

The backend is written in Java, we target JDK 21, use modern language features up to that version during implementation.
Gradle is used as the build system; run `./gradlew clean installDist` for a full clean build.
Gradle is used as the build system:

- `./gradlew assemble` builds normal backend and UI artifacts without verification, installing the distribution, or building Docker images.
- `./gradlew check` runs backend and UI tests, Spotless, UI dependency checks, and translation checks.
- `./gradlew build` builds and verifies the project. Use this as the normal pre-PR command.
- `./gradlew installDist` prepares the runnable distribution in `manager/build/install/manager/` and the deployment Docker build context.

Use `./gradlew clean assemble` for a clean artifact build, or `./gradlew clean build` to also run verification.
Lifecycle tasks compose individual tasks, which remain independently runnable for targeted development and CI checks.
In sandboxed environments, add `--offline` (requires dependencies to already be cached).

## Tests
Expand All @@ -32,7 +40,23 @@ ex.response.withCloseable { r ->

### Running tests

When running integration tests, part of the stack (PostgreSQL and Keycloak) must be running. Start it with `docker compose -f profile/dev-testing.yml -p openremote up -d --no-build`.
- `./gradlew testBackend` runs backend unit tests followed by backend integration tests.
- `./gradlew testBackendUnit` runs backend unit tests only.
- `./gradlew testBackendIntegration` runs backend integration tests only.
- `./gradlew testUi` runs UI component tests followed by UI app end-to-end tests.
- `./gradlew testUiComponent` runs UI component tests only.
- `./gradlew testUiApp` runs UI app end-to-end tests only.
- `./gradlew test` runs `testBackend` followed by `testUi`.

Both `check` and `build` include the complete test sequence.
UI module tasks retain the `npmTest` name alongside `npmBuild`; for example, `./gradlew :ui:component:or-element:npmTest` runs one component package's tests.

Backend integration tests and UI app tests require PostgreSQL and Keycloak. Start them with `docker compose -f profile/dev-testing.yml -p openremote up -d --no-build`.

The same stack is required for `check` and `build`. Gradle waits up to 30 seconds for PostgreSQL and Keycloak before backend integration tests and Manager UI app tests. Gradle also checks that Playwright can launch Chromium before browser-backed test tasks; install it with `./gradlew :ui:test:installBrowsers` if needed.
Gradle app test tasks, including individual `npmTest` tasks, automatically prepare the Manager, Manager UI, and shared UI distributions.
Component test tasks prepare generated TypeScript sources and shared icon fonts without building the Manager application.
Pass `-PreuseUiTestArtifacts=true` only when the required outputs have already been built or downloaded, as in the CI jobs that reuse Install Dist artifacts.

Spock snapshots are stored under `model/src/test/resources/snapshots`. Rewrite them with `./gradlew :model:test -PupdateSnapshots` and review the resulting diff, since a mismatch is only reported as a test failure otherwise.

Expand Down
37 changes: 37 additions & 0 deletions README.md
Comment thread
Ekhorn marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,43 @@ For information and how to set up a development environment, see the [Developer

We work with Java, Groovy, TypeScript, Gradle, Docker, and a wide range of APIs and protocol implementations.

Use JDK 21 and the repository's Yarn version to build from source:

```sh
./gradlew assemble # Build backend and UI artifacts
./gradlew check # Run tests, formatting, dependency, and translation checks
./gradlew build # Build and verify: the normal pre-PR command
./gradlew installDist # Prepare the runnable manager and deployment files
```

For a clean build, use `./gradlew clean assemble`, or `./gradlew clean build` to include verification.
The runnable distribution is installed in `manager/build/install/manager/`; `assemble` does not install it or build Docker images.

Before running `check` or `build`, start PostgreSQL and Keycloak with `docker compose -f profile/dev-testing.yml -p openremote up -d --no-build` and install the Playwright browser with `./gradlew :ui:test:installBrowsers`.
These lifecycle tasks compose individual tasks that remain independently runnable, allowing CI to run checks separately, reuse artifacts, and prepare distributions only where needed.

For targeted test runs:

```sh
./gradlew test # testBackend followed by testUi
./gradlew testBackend # Backend unit tests followed by integration tests
./gradlew testBackendUnit # Backend unit tests only
./gradlew testBackendIntegration # Backend integration tests only
./gradlew testUi # UI component tests followed by app end-to-end tests
./gradlew testUiComponent # UI component tests only
./gradlew testUiApp # UI app end-to-end tests only
```

UI modules retain `npmTest`, alongside `npmBuild`, for individual package tests, e.g. `./gradlew :ui:component:or-element:npmTest`.
Gradle waits up to 30 seconds for PostgreSQL and Keycloak before backend integration tests and Manager UI app tests. If either service is unavailable, it fails with the startup command above.
Gradle checks that Playwright can launch Chromium before running browser-backed test tasks. If it is missing, install it with `./gradlew :ui:test:installBrowsers`.
Gradle app test tasks automatically prepare the Manager, Manager UI, and shared UI distributions.
Component test tasks prepare generated TypeScript sources and shared icon fonts without building the Manager application.
CI jobs that already have build outputs pass `-PreuseUiTestArtifacts=true` to skip this preparation and reuse those outputs.
Both `check` and `build` include the complete test sequence as well as the other verification checks.

UI compiler tasks coordinate access to shared TypeScript outputs, and Knip waits for scheduled writers to finish. See [Parallel UI tasks](ui/AGENTS.md#parallel-ui-tasks) for the reasons and concurrency limits. Run `./gradlew :ui:testUiLocks` or `yarn test:ui-locks` to verify this coordination without starting backend services or a browser.

We follow the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) workflow with tags and releases for published versions of our components; when working on the codebase create descriptive branch names (e.g. `feature/cool_feature_x`, `hotfix/flux_capacitor`, `issue/123`, etc.).

When your changes are complete then create a Pull Request ensuring that your branch is up-to-date with the source branch and that code changes are covered by tests and that the full test suite passes.
Expand Down
Loading
Loading