Deprecating Arquillian Testsuite, Keycloak Test Framework Full Support

February 25 2026 by Lukas Hanusovsky

What’s changing?

The testsuite module, with all related dependents, like Arquillian testsuite, is now officially deprecated.

At the same time Test Framework full support is starting from the upcoming Keycloak 26.6.0 release.

The New Test Framework

Based on JUnit 6, the Keycloak Test Framework makes it easy to write tests for Keycloak and extensions. Behind the scenes the framework handles the lifecycle of Keycloak, the database, and any injected resources such as realms and clients.

Tests simply declare what they want, including specific configuration, and the framework takes care of the rest.

Contributors are asked to start using new Test Framework and write tests within the new tests module.

What’s new?

Since the initial announcement these new features have been added:

  • Improved documentation

  • Improved registry with dependency graph

  • Hot deploy with external providers

  • Re-use support for distribution server, for faster execution times

  • Re-use support for H2 database, for faster execution times

  • Managed OAuth client

  • Managed Admin client factory

  • Support for conditional execution (e.g.disable tests for certain databases)

  • @TestSetup and @TestCleanup method annotation to configure a specific test class

  • TimeOffset support

  • Test framework unit and integration tests

  • Test framework injection validation

  • Run on Server functionality

  • TLS and mTLS with managed certificates

  • FIPS with managed crypto keys

  • Managed Infinispan server

  • Managed Email server

  • Managed HTTP client and HTTP server

  • Events and Admin Events assertions

  • Custom providers support

  • GitHub Actions summary report

  • Test suites support

  • Clustering support

  • WebAuthn support

  • Migration util

On top of that, the whole admin tests package has been migrated.

My first test

The following shows a very simply test that deploys a realm to Keycloak and creates a user within the realm.

@KeycloakIntegrationTest
public class MyInitialTest {

    @InjectRealm
    ManagedRealm realm;

    @InjectUser
    ManagedUser user;

    @Test
    public void myFirstTest() {
        Assertions.assertNotNull(realm.admin().users().get(user.getId()));
    }
}

OAuth Access Token Request example

This test shows on how to use the newly created user to get an access or refresh token, with checking the latest fired event.

@KeycloakIntegrationTest
public class OAuthRefreshTokenTest {

    @InjectRealm
    ManagedRealm realm;

    @InjectUser(config = OAuthUserConf.class)
    ManagedUser user;

    @InjectOAuthClient
    OAuthClient oAuthClient;

    @InjectEvents
    Events events;

    @Test
    public void testTokenRefresh() {
        AuthorizationEndpointResponse response = oAuthClient
            .doLogin(user.getUsername(), user.getPassword());

        AccessTokenResponse accessTokenResponse = oAuthClient
            .doAccessTokenRequest(response.getCode());

        EventAssertion.assertSuccess(events.poll()).userId(user.getId()).hasSessionId();

        AccessTokenResponse refreshTokenResponse = oAuthClient
            .doRefreshTokenRequest(accessTokenResponse.getRefreshToken());

        EventAssertion.assertSuccess(events.poll()).userId(user.getId()).hasSessionId();

        oAuthClient.doLogout(refreshTokenResponse.getRefreshToken());

        EventAssertion.assertSuccess(events.poll()).userId(user.getId()).hasSessionId();
    }

    private static class OAuthUserConf implements UserConfig {

        @Override
        public UserConfigBuilder configure(UserConfigBuilder builder) {
            return builder.username("oauth-user").name("OAuth", "User")
                    .password("strong-password").email("oauth@user")
                    .emailVerified(true);
        }
    }
}

Looking for help?

Meet us on Slack or Email:

Github Discussion:

Guidelines: