The new tests parent module incorporate:

• tests written in Keycloak Test Framework: base, clustering, webauthn
• support modules for utilities and extensions: utils, utils-shared, custom-providers, custom-scripts
• migration utility (from Arquillian to Keycloak Test Framework)

Keep attention where a particular test belong, most of the tests are placed in the base module, but some require very specific configuration, like clusterting or webauthn.

Support for test suites:

• Based on JUnit Platform Suite
• All currently available suites are in the suites package
• Part of the GitHub Actions CI worklow

Useful guides:

• Keycloak Test Framework
• FIPS tests execution - how to set up a local machine to successfully execute the FIPS tests.

Some test classes need complex executions and use a logic, which can be reused over and over. To remove a boilerplate code, this is the place - the utils module, where some static utilities can be placed.

Are you thinking of adding a new util class?

1. Always check if this functionality is part of the test framework.
2. Check the existing util classes.
3. If none of them are sufficient, then create a new one, but:
   1. Be cautious, since it creates a new complexity.
   2. Be as specific with the names as possible => clear package and class name.

The utils-shared module is for migration purpose only and will be removed once the migration is over! Meaningful utilities will be refactored and moved to utils.

It prevents the new tests to be dependent on the old Arquillian testsuite and in the same time, it simplifies the overall migration. Is a util class (in the old testsuite) shared by multiple test cases?

• Migrate util class into this module first.
• Then migrate your test.

The custom-providers module is used within tests to specify a custom extension, built on top of the Keycloak SPI. Every custom extension with particular factory must be stored in this module!

Same applies for the custom-scripts module, it deploys custom authenticators (feature scripts) written in JavaScript. Every such script must be stored in this separate module!

All of them can be deployed as a dependency within the KeycloakServerConfig implementation, please check the Keycloak Test Framework docs.

The migration-util is a tool, written in Java, to simplify the overall migration. It can be executed via migrate.sh script. Its purpose is to copy/paste selected test case, and parse and replace patterns to follow the Keycloak Test Framework.

Pay attention! It doesn't support every pattern just speed up the initial phase, before digging into a manual migration.

Example of usage: ./migrate.sh AttributesTest

Please, consider using this script for making a commit, because it allows to preserve a history tree for a specific test case: commit-migration.sh

Available guides, which cover the required knowledge to successfully migrate a single test case:

• Migrating tests - Quick start for a single test migration (includes the migration utility best practice)
• Manual migration - Guide with recommendations on how to fully migrate a test

Once the migration is over the migration-util module will be removed!