Berg

Berg is a test-suite for HAL Management Console based on Cypress UI test automation. Berg as a name is heavily inspired by Gutenberg, inventor of printing press :) (printing press -> press -> Cypress).

Technological Stack

NodeJS

Node (https://nodejs.org/en/) is the JavaScript runtime engine used to run Berg, since Cypress is built only for JavaScript.

Cypress

Cypress (https://www.cypress.io) is the main automation framework used for developing, running & reporting tests. Main benefit of Cypress is, that it is bundling the testing code directly into the system (browser) under testing. Since JavaScript is the main language used by modern browsers, the test execution is swift, stable and less environment error-prone as in standard (Selenium + WebDriver) UI automation tools.

TestContainers

TestContainers (https://github.com/testcontainers/testcontainers-node) serves to launch & manage test scoped containers. Currently following containers are being used for testing:

• Standalone HAL image used for most of the UI testing. It is a standalone HAL binary delivered by a container image that will be connected to a running WildFly server (that exposes management interface)
• WildFly Server Image used for resource management. Exposes management interfaces onto which the Standalone HAL Image connects.
• DB Images (such as postgres) serving (mostly) to run DB instances, that are being used in the datasource related tests.

Requirements

Following tools are required to run the test suite

• NodeJS as a runtime environment
  • recommended version is 22.
  • Node Version Manager (nvm) is recommended optional tool to install & manage multiple Node environments
• npx CLI tool used to exeute binaries from project's node_modules directly (instead of providing absolute/relative path to the commannds). It is used in multiple build steps.
• Podman | Docker as a container runtime used by TestContainers. Podman is auto-detected: DOCKER_HOST, TESTCONTAINERS_RYUK_DISABLED, and podman.socket are configured automatically. To override, set the environment variables manually before running the test suite:
  • export TESTCONTAINERS_RYUK_DISABLED=true
  • export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
• Java. Yes we'll need Java to write deployments/applications that will be deployed onto the running WildFly container.
• Maven. Yes, we'll need Maven to ease up the development of the deployed applications & downloading needed JDBC drivers for datasource & drivers UI tests. Maven is mostly used embedded by node-maven JS wrapper to execute Maven & Java related tasks into the build automation.

How to build & run

• Make sure you have all the tools from Requirements installed
• Run

npm install

in the root directory to download all of the NPM dependencies specified in package.json

• If you want to run Cypress developer console with the loaded spec files, run

npm run develop

• If you want to execute whole testsuite execute npm test

• It is also possible to run on specific browser by supplying --browser argument, e.g

npm test -- --browser=chrome

• It is possible to reduce the amount of specs executed by passing --specs flag. It also supports glob patterns, e.g to execute only homepage related tests, run

npm test -- --specs="packages/testsuite/cypress/e2e/homepage/test-homepage.cy.ts"
or
npm test -- --specs="packages/testsuite/cypress/e2e/homepage/*.cy.ts"

• If you want to run tests without cleaning and a resources compilations (useful for CI), use

npm run test:compiled -- --specs="packages/testsuite/cypress/e2e/homepage/test-homepage.cy.ts"

• If you wish to run the test suite against custom HAL or WildFly images, you can use HAL_IMAGE and WILDFLY_IMAGE environment variables to specify custom images, e.g

HAL_IMAGE=quay.io/myorg/hal WILDFLY_IMAGE=quay.io/myorg/wildfly npm test ...

• For debugging purposes videos (and screenshots) of failed tests are stored after the test run (works only with chrome).

Available environment properties

Following is a table of supported environment properties that can be used when running the testsuite.

Property name	Default value	Description
HAL_IMAGE	quay.io/halconsole/hal-development:latest	HAL standalone image to be used
WILDFLY_IMAGE	quay.io/halconsole/wildfly-development:latest	WildFly/JBoss EAP image to be used
KEYCLOAK_IMAGE	quay.io/keycloak/keycloak:latest	Keycloak/RH-SSO image to be used for OIDC tests
POSTGRES_IMAGE	docker.io/library/postgres:latest	PostgreSQL image to be used for datasource tests
MYSQL_IMAGE	docker.io/library/mysql:latest	MySQL image to be used for datasource tests
MARIADB_IMAGE	docker.io/library/mariadb:latest	MariaDB image to be used for datasource tests
MSSQL_IMAGE	mcr.microsoft.com/mssql/server:2022-latest	Microsoft SQL Server image to be used for datasource tests
BERG_VERBOSE	false	Enable verbose Berg logging (debug messages for container setup, CLI commands, etc.)

JDBC drivers

JDBC driver jars are used in datasource tests. They are downloaded automatically by Maven during npm install (via npm run resources) and placed into packages/testsuite/cypress/fixtures/jdbc-drivers/. These jars are .gitignored and built fresh each time.

Where versions are defined

Driver versions are managed in packages/resources/pom.xml under <dependencyManagement>. The download is configured in packages/resources/modules/jdbc-drivers/pom.xml.

How to update

1. Update the version in packages/resources/pom.xml under <dependencyManagement>
2. Run npm install or npm run resources to download the new jars
3. No test spec changes needed -- driver paths are resolved automatically at runtime by the resolve:jdbc:driver Cypress task using the artifact prefix (e.g., postgresql, mysql-connector-j)

Custom method documentation

Documentation can be generated by following command in root of this repository

npm run docs

Contributing

See contributing guide: CONTRIBUTING.md