{"id":23974620,"url":"https://github.com/hal/manatoko","last_synced_at":"2025-04-13T22:37:17.940Z","repository":{"id":37399186,"uuid":"451648662","full_name":"hal/manatoko","owner":"hal","description":"HAL self-contained test suite","archived":false,"fork":false,"pushed_at":"2025-04-09T15:19:09.000Z","size":37317,"stargazers_count":0,"open_issues_count":0,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-09T16:32:59.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hal.github.io/manatoko/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-01-24T22:05:10.000Z","updated_at":"2025-04-09T15:19:12.000Z","dependencies_parsed_at":"2023-10-20T13:39:08.453Z","dependency_job_id":"ad011295-ec99-4dbe-8ea4-2e79d6ec6e63","html_url":"https://github.com/hal/manatoko","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hal%2Fmanatoko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hal%2Fmanatoko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hal%2Fmanatoko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hal%2Fmanatoko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hal","download_url":"https://codeload.github.com/hal/manatoko/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248792966,"owners_count":21162475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-07T05:47:23.187Z","updated_at":"2025-04-13T22:37:17.873Z","avatar_url":"https://github.com/hal.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Verify Codebase](https://github.com/hal/manatoko/actions/workflows/verify.yml/badge.svg)](https://github.com/hal/manatoko/actions/workflows/verify.yml)\n\nManatoko ([Maori](https://maoridictionary.co.nz/search?keywords=manatoko) for verify, test) is a new approach to test the [HAL](https://hal.github.io) management console. It builds on top of\n\n- [Testcontainers](https://www.testcontainers.org/)\n- [Arquillian Graphene 2](http://arquillian.org/arquillian-graphene/) and [Arquillian Drone](http://arquillian.org/arquillian-extension-drone/)\n- [JUnit 5](https://junit.org/junit5/)\n\nThe goal is that tests should be self-contained. Containers are started and stopped when necessary and tests can focus on testing the UI and verifying management model changes. The biggest advantage of this approach is that it is very easy to run UI tests in a CI environment.\n\n**TOC**\n* [Write Tests](#write-tests)\n  * [Operation Mode](#operation-mode)\n* [Test Environment](#test-environment)\n  * [Remote](#remote)\n  * [Local](#local)\n* [Run Tests](#run-tests)\n  * [Run All Tests](#run-all-tests)\n  * [Run Specific Tests](#run-specific-tests)\n* [Test Report](#test-report)\n* [Images](#images)\n* [Modules](#modules)\n* [Scripts](#scripts)\n\n# Write Tests\n\nTests need to be annotated with two annotations (in this order!):\n\n1. `@Manatoko`: This annotation activates two Junit 5 extensions:\n   - `SystemSetupExtension`: Takes care of starting / stopping singleton containers once before / after all tests.\n   - `ArquillianExtension`: Takes care about the Arquillian integration\n2. `@Testcontainers`: Takes care of starting containers marked with `@Container`.\n\nA simple test that tests adding a new system property looks like this:\n\n```java\n@Manatoko\n@Testcontainers\nclass SystemPropertyTest {\n\n   @Container static WildFlyContainer wildFly = WildFlyContainer.standalone(DEFAULT);\n\n   @Page SystemPropertyPage page;\n   @Inject CrudOperations crud;\n   TableFragment table;\n   FormFragment form;\n\n   @BeforeEach\n   void prepare() {\n      page.navigate();\n      form = page.getForm();\n      table = page.getTable();\n      table.bind(form);\n   }\n\n   @Test\n   void create() {\n      crud.create(systemPropertyAddress(CREATE_NAME), table, form -\u003e {\n         form.text(NAME, CREATE_NAME);\n         form.text(VALUE, CREATE_VALUE);\n      });\n   }\n}\n```\n\nSee [`SystemPropertyTest`](test-configuration-systemproperty/src/test/java/org/jboss/hal/testsuite/configuration/systemproperty/SystemPropertyTest.java) for the full code.\n\n## Operation Mode\n\nThe example injects a WildFly standalone container using the default configuration (`standalone.xml`). The enum [`WildFlyConfiguration`](container/src/main/java/org/jboss/hal/testsuite/container/WildFlyConfiguration.java) lists all supported configurations for standalone mode. \n\nIf you want to use the domain mode, inject the WildFly container using \n\n```java\n@Container static WildFlyContainer wildFly = WildFlyContainer.domain();\n```\n\nTests which run in domain mode, make certain assumptions (like the default host). These assumptions rely on the properties defined in [`domain.properties`](management-model/src/main/resources/domain.properties). You can customize these properties using `-D\u003ckey\u003e=\u003cvalue\u003e`.\n\n# Test Environment\n\nTests can be run in two modes, controlled by the system property `test.environment`. Valid values are either `local` or `remote`.\n\n## Remote\n\nThis is the default mode. In this mode a [web driver container](https://www.testcontainers.org/modules/webdriver_containers/) (with support of screen recording) is started before all tests. An Arquillian extension is registered which provides a remote web driver connected to the browser running in this container.\n\n## Local\n\nThis mode is activated by the maven profile `local`. In this mode a browser is started locally and Arquillian Graphene takes care of providing the web driver.\n\n# Images\n\nBy default, the tests will use the following images:\n\n- HAL: [quay.io/halconsole/hal:latest](https://quay.io/repository/halconsole/hal)\n- WildFly standalone: [quay.io/halconsole/wildfly:latest](https://quay.io/repository/halconsole/wildfly)\n- WildFly domain: [quay.io/halconsole/wildfly-domain:latest](https://quay.io/repository/halconsole/wildfly-domain)\n\nThe image names can be customized by overriding the properties defined in [`container.properties`](container/src/main/resources/container.properties). Say you want to use the latest development version of HAL instead of the latest stable release, then use\n\n```shell\n./mvnw test -P all-tests -Dhal.image=quay.io/halconsole/hal-development:latest\n```\n\nIf you want to use a specific WildFly version for the tests, use\n\n```shell\n./mvnw test -P all-tests \\\n  -Dwildfly.standalone.image=quay.io/halconsole/wildfly:23.0.0.Final \\\n  -Dwildfly.domain.image=quay.io/halconsole/wildfly-domain:23.0.0.Final\n```\n\n# Run Tests\n\n## Run All Tests\n\nTo run all tests, simply execute\n\n```shell\n./mvnw test -P all-tests \n```\n\nTo run the tests with a local browser, use \n\n```shell\n./mvnw test -P all-tests,local \n```\n\n## Run Specific Tests\n\nIf you just want to execute tests of one specific module e.g. `test-configuration-systemproperty`, run \n\n```shell\n./mvnw test -P all-tests --projects test-configuration-systemproperty --also-make\n```\n\nIf you want to execute one specific test or test method, use one of the following commands:\n\n```shell\n./mvnw test -P all-tests --projects test-configuration-systemproperty --also-make \\\n    -Dtest=org.jboss.hal.testsuite.configuration.systemproperty.SystemPropertyTest\n  \n./mvnw test -P all-tests --projects test-configuration-systemproperty --also-make \\\n    -Dtest=org.jboss.hal.testsuite.configuration.systemproperty.SystemPropertyTest#create\n```\n\nIf you want to debug a test, append `-Dmaven.surefire.debug` and attach a debugger to port 5005.\n\n# Test Report\n\nAll tests are executed every 24h and the results are aggregated by the `maven-surefire-report-plugin`. The report is then published to GitHub pages: https://hal.github.io/manatoko/surefire-report.html \n\n# Modules\n\nManatoko consists of many modules. Each module has a distinct responsibility. Here's an overview of the modules and its dependencies:\n\n![Manatoko dependencies](dependency-graph.png \"Manatoko dependencies\")\n\n- `manatoko-environment`: Singleton to manage the [test environment](#test-environment) (local or remote) \n- `manatoko-management-model`: Classes for working with the management model and JBoss DMR\n- `manatoko-container`: Classes to start / stop the test containers \n- `manatoko-junit`: Annotations and Junit extensions for writing and running the unit tests \n- `manatoko-ui`: Arquillian fragments and pages\n- `manatoko-fixture`: Constants and test fixtures used by the unit tests\n- `manatoko-arquillian`: Arquillian extension for the integration with Testcontainers\n- `manatoko-command`: Creaper commands to create various management resources\n- `manatoko-test-noop`: Sample test module to verify the Arquillian and Testcontainers wiring\n- `manatoko-test-configuration-*`: Configuration tests\n- `manatoko-test-runtime-*`: Runtime tests\n- `manatoko-test-deployment-*`: Deployment tests\n\n# Scripts\n\nThis repository contains various scripts to automate tasks.\n\n## `depgraph.sh`\n\nCreates the [dependency graph](#modules) of the modules.\n\n## `format.sh`\n\nFormats the codebase by applying the following maven goals:\n\n- [`license-maven-plugin:format`](https://mycila.carbou.me/license-maven-plugin/#goals)\n- [`formatter-maven-plugin:format`](https://code.revelc.net/formatter-maven-plugin/format-mojo.html)\n- [`impsort-maven-plugin:sort`](https://code.revelc.net/impsort-maven-plugin/sort-mojo.html)\n\nThe goals use the plugin configuration in [code-parent/pom.xml](code-parent/pom.xml) and the resources in [build-config/src/main/resources/manatoko](build-config/src/main/resources/manatoko).  \n\n## `validate.sh`\n\nValidates the codebase by applying the following maven goals:\n\n- [`enforcer:enforce`](https://maven.apache.org/enforcer/maven-enforcer-plugin/enforce-mojo.html)\n- [`checkstyle:check`](https://maven.apache.org/plugins/maven-checkstyle-plugin/check-mojo.html)\n- [`license-maven-plugin:check`](https://mycila.carbou.me/license-maven-plugin/#goals)\n- [`formatter-maven-plugin:validate`](https://code.revelc.net/formatter-maven-plugin/validate-mojo.html)\n- [`impsort-maven-plugin:check`](https://code.revelc.net/impsort-maven-plugin/check-mojo.html)\n\nThe goals use the plugin configuration in [code-parent/pom.xml](code-parent/pom.xml) and the resources in [build-config/src/main/resources/manatoko](build-config/src/main/resources/manatoko).\n  \n## `gh-test-all.sh`\n\nRuns all tests in all test modules. This script triggers the workflow defined in [`test-all.yml`](.github/workflows/test-all.yml). The tests are run in parallel, but please note that this might take some time.\n\nThe script uses the latest stable HAL release by default. If you want to use the latest snapshot, please specify `--development`.\n\nThe script requires [GitHub CLI](https://cli.github.com/) to be present and configured on your machine. \n\n## `gh-test-single.sh`\n\nRuns the tests of a single test module given as an argument. This script triggers the workflow defined in [`test-single.yml`](.github/workflows/test-single.yml).\n\nThe script uses the latest stable HAL release by default. If you want to use the latest snapshot, please specify `--development`.\n\nThe script requires [GitHub CLI](https://cli.github.com/) to be present and configured on your machine.\n\n## `tcpm.sh`\n\nIf you're using testcontainers with Podman 3.x on macOS, please start `./tcpm.sh` and make sure to set the following environment variables **before** running the tests.\n\n```sh\nDOCKER_HOST=unix:///tmp/podman.sock\nTESTCONTAINERS_CHECKS_DISABLE=true\nTESTCONTAINERS_RYUK_DISABLED=true\n```\n\nSee https://www.testcontainers.org/features/configuration/ and https://github.com/testcontainers/testcontainers-java/issues/2088#issuecomment-911586506 for details.\n\nFor Podman 4.x, `tcpm.sh` is not necessary. You can either call\n\n```shell\nsudo podman-mac-helper install\n```\n\nor set\n\n```shell\nexport DOCKER_HOST='unix:///~/.local/share/containers/podman/machine/podman-machine-default/podman.sock'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhal%2Fmanatoko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhal%2Fmanatoko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhal%2Fmanatoko/lists"}