mirror of https://github.com/keycloak/keycloak.git synced 2025-12-16 12:05:49 -06:00

Files

Šimon Vacek 175102d03d Migration util imrovements (#39161 )

Closes #37691
Implements #37283



migration util rewrite static imports



migration util add more assert methods



migration util rewrite common statements



migration util fix diff tool usage



Update test migration README



migration util review fixes

Signed-off-by: Simon Vacek <simonvacky@email.cz>

2025-05-19 09:55:25 +02:00

3.3 KiB

Raw Permalink Blame History

How to migrate tests to the new framework?

TLDR

cd into the migration-util module
Use the migration script
```
./migrate.sh SomeTest
```
The script doesn't work? Follow the MANUAL_MIGRATION guide.
Fix the rest of the test class. To speed up the process, use the remote server mode when running the test.
Use the commit-migration script to commit the changes correctly:
```
./commit-migration.sh
```
On the PR on GitHub, review the commit that modifies the files
Do not squash the commits when merging the PR

Migration process

Migrating tests involves doing a lot of repetitive tasks. We made some automation tooling in the migration-util module to make it less annoying.

Migrating test classes

To migrate a test class, you can use the migrate script.

cd into the migration-util module and run:

./migrate.sh SomeTest

The script accepts one parameter that can be either a class name or an absolute path to the file. By default, look-up starts from testsuite/integration-arquillian/tests/base/src/test/java/org/keycloak/testsuite.

When run, the script copies the test class and rewrites or adds common test statements, such as:

adds the @KeycloakIntegrationTest annotation
changes JUnit 4's @Before to JUnit 5's @BeforeEach
updates JUnit 4's assertions with their JUnit 5's counterparts

And more.

Besides the printed logs, you can pass the script a diff tool to see the changes made:

DIFFTOOL="diff --color=always" ./migrate.sh SomeTest

DIFFTOOL="meld" ./migrate.sh SomeTest

If the script fails and throws an exception, you can try to fix it or refer to the MANUAL_MIGRATION guide.

The migrated test shall be in the same package in tests/base/src/test/java/org/keycloak/tests. When migrating tests, use the remote server mode, as this will make it much quicker to run tests than having to start/stop Keycloak when you run the test from the IDE.

Committing changes

Migrating some tests requires changing more than 50% of the test class. For this reason, git thinks a new file was created instead of moved. This causes us to lose the history of the test file. To mitigate this, we have a script to make all commits for you.

In the migration-util module run:

./commit-migration.sh

The script works only with your git staging area. If it detects the same files are marked as deleted and created, it makes one commit where the files are moved unchanged to the new location. Then, it commits the changes with the rest of your staging area. You will be prompted to provide a commit message if you do not wish to use the default one.

When you create a PR and check the "Files changed" tab, you will still see them as deleted and created, which makes the code review hard. Instead, go to the "Commits" tab and review the commit that modifies the already moved file.

Do not squash the commits when merging the PR, or the file history will be lost again.

3.3 KiB Raw Permalink Blame History