stianst · Apr 23, 2026 · Apr 21, 2026 · Apr 23, 2026
@@ -43,12 +43,12 @@
 import org.keycloak.testframework.authzen.client.annotations.InjectAuthZenClient;
 import org.keycloak.testframework.oauth.OAuthClient;
 import org.keycloak.testframework.oauth.annotations.InjectOAuthClient;
+import org.keycloak.testframework.realm.ClientBuilder;
 import org.keycloak.testframework.realm.ClientConfig;
-import org.keycloak.testframework.realm.ClientConfigBuilder;
 import org.keycloak.testframework.realm.ManagedClient;
 import org.keycloak.testframework.realm.ManagedRealm;
+import org.keycloak.testframework.realm.RealmBuilder;
 import org.keycloak.testframework.realm.RealmConfig;
-import org.keycloak.testframework.realm.RealmConfigBuilder;
 import org.keycloak.testframework.server.KeycloakUrls;
 import org.keycloak.testsuite.util.oauth.AccessTokenResponse;
 
@@ -748,7 +748,7 @@ private static void createScopePermission(AuthorizationResource authz, String na
 
     public static class TestRealmConfig implements RealmConfig {
         @Override
-        public RealmConfigBuilder configure(RealmConfigBuilder realm) {
+        public RealmBuilder configure(RealmBuilder realm) {
             realm.addRole("admin");
 
             realm.addUser("admin-user")
@@ -770,7 +770,7 @@ public RealmConfigBuilder configure(RealmConfigBuilder realm) {
 
     public static class AuthzClientConfig implements ClientConfig {
         @Override
-        public ClientConfigBuilder configure(ClientConfigBuilder client) {
+        public ClientBuilder configure(ClientBuilder client) {
             return client
                   .secret("secret")
                   .directAccessGrantsEnabled(true)
@@ -780,7 +780,7 @@ public ClientConfigBuilder configure(ClientConfigBuilder client) {
 
     public static class NoAuthzClientConfig implements ClientConfig {
         @Override
-        public ClientConfigBuilder configure(ClientConfigBuilder client) {
+        public ClientBuilder configure(ClientBuilder client) {
             return client
                   .secret("secret")
                   .directAccessGrantsEnabled(true);

@@ -4,6 +4,18 @@
 Breaking changes are identified as those that might require changes for existing users to their configurations or applications.
 In minor or patch releases, {project_name} will only introduce breaking changes to fix bugs.
 
+=== Test Framework representation builders
+
+The test framework provides a number of builders to simplify creating representations. These can be used on their own,
+but are also used by `RealmConfig`, `ClientConfig` and `UserConfig` implementations.
+
+Some builders had the suffix `ConfigBuilder`, while others had the shorter syntax `Builder`. They are all now renamed to use
+the shorter suffix `Builder` to keep things consistently.
+
+Additionally, some methods where updated for consistency across the builders:
+
+* `RoleBuilder` method `setSingleAttribute` was renamed to `attribute`
+
 === Identity Provider alias is now immutable
 
 The alias of an Identity Provider can no longer be changed after creation via the Admin REST API. Attempts to update the alias will result in a `400 Bad Request` error.

@@ -31,8 +31,8 @@
 import org.keycloak.testframework.annotations.TestSetup;
 import org.keycloak.testframework.realm.ManagedClient;
 import org.keycloak.testframework.realm.ManagedRealm;
+import org.keycloak.testframework.realm.RealmBuilder;
 import org.keycloak.testframework.realm.RealmConfig;
-import org.keycloak.testframework.realm.RealmConfigBuilder;
 import org.keycloak.testframework.server.KeycloakServerConfig;
 import org.keycloak.testframework.server.KeycloakServerConfigBuilder;
 
@@ -695,7 +695,7 @@ public KeycloakServerConfigBuilder configure(KeycloakServerConfigBuilder config)
 
     public static class AuthorizationRealmConfig implements RealmConfig {
         @Override
-        public RealmConfigBuilder configure(RealmConfigBuilder realm) {
+        public RealmBuilder configure(RealmBuilder realm) {
             realm.name("authztest");
             realm.adminPermissionsEnabled(true);
             realm.addClient("test-client")

@@ -45,8 +45,8 @@
 import org.keycloak.testframework.annotations.KeycloakIntegrationTest;
 import org.keycloak.testframework.realm.ManagedClient;
 import org.keycloak.testframework.realm.ManagedRealm;
+import org.keycloak.testframework.realm.RealmBuilder;
 import org.keycloak.testframework.realm.RealmConfig;
-import org.keycloak.testframework.realm.RealmConfigBuilder;
 import org.keycloak.testframework.server.KeycloakServerConfig;
 import org.keycloak.testframework.server.KeycloakServerConfigBuilder;
 
@@ -1022,11 +1022,11 @@ public KeycloakServerConfigBuilder configure(KeycloakServerConfigBuilder config)
     public static class NoAccessRealmConfig implements RealmConfig {
 
         @Override
-        public RealmConfigBuilder configure(RealmConfigBuilder realm) {
+        public RealmBuilder configure(RealmBuilder realm) {
             realm.addClient("myclient")
                     .secret("mysecret")
                     .serviceAccountsEnabled(true);
             return realm;
         }
     }
-}
+}
@@ -27,8 +27,8 @@
 import org.keycloak.testframework.annotations.InjectClient;
 import org.keycloak.testframework.annotations.InjectHttpClient;
 import org.keycloak.testframework.annotations.InjectRealm;
+import org.keycloak.testframework.realm.ClientBuilder;
 import org.keycloak.testframework.realm.ClientConfig;
-import org.keycloak.testframework.realm.ClientConfigBuilder;
 import org.keycloak.testframework.realm.ManagedClient;
 import org.keycloak.testframework.realm.ManagedRealm;
 import org.keycloak.testframework.server.KeycloakServerConfig;
@@ -620,7 +620,7 @@ public KeycloakServerConfigBuilder configure(KeycloakServerConfigBuilder config)
 
     public static class TestOidcClient implements ClientConfig {
         @Override
-        public ClientConfigBuilder configure(ClientConfigBuilder client) {
+        public ClientBuilder configure(ClientBuilder client) {
             return client.clientId("test-client-oidc")
                     .enabled(true)
                     .protocol("openid-connect");
@@ -629,7 +629,7 @@ public ClientConfigBuilder configure(ClientConfigBuilder client) {
 
     public static class TestSamlClient implements ClientConfig {
         @Override
-        public ClientConfigBuilder configure(ClientConfigBuilder client) {
+        public ClientBuilder configure(ClientBuilder client) {
             return client.clientId("test-client-saml")
                     .enabled(true)
                     .protocol("saml");

@@ -27,7 +27,7 @@
 import org.keycloak.testframework.annotations.InjectUser;
 import org.keycloak.testframework.annotations.KeycloakIntegrationTest;
 import org.keycloak.testframework.injection.LifeCycle;
-import org.keycloak.testframework.realm.ClientConfigBuilder;
+import org.keycloak.testframework.realm.ClientBuilder;
 import org.keycloak.testframework.realm.ManagedRealm;
 import org.keycloak.testframework.realm.ManagedUser;
 import org.keycloak.testframework.scim.client.annotations.InjectScimClient;
@@ -55,7 +55,7 @@ public class AuthorizationTest extends AbstractScimTest {
 
     @BeforeEach
     public void onBefore() {
-        realm.admin().clients().create(ClientConfigBuilder
+        realm.admin().clients().create(ClientBuilder
                 .create()
                 .clientId("scim-client-restricted")
                 .secret("secret")

@@ -1,12 +1,12 @@
 package org.keycloak.tests.scim.tck;
 
+import org.keycloak.testframework.realm.RealmBuilder;
 import org.keycloak.testframework.realm.RealmConfig;
-import org.keycloak.testframework.realm.RealmConfigBuilder;
 
 public class ScimRealmConfig implements RealmConfig {
 
     @Override
-    public RealmConfigBuilder configure(RealmConfigBuilder realm) {
+    public RealmBuilder configure(RealmBuilder realm) {
         return realm.scimEnabled(true);
     }
 }
@@ -34,9 +34,9 @@
 import org.keycloak.scim.resource.user.User;
 import org.keycloak.testframework.annotations.KeycloakIntegrationTest;
 import org.keycloak.testframework.events.AdminEventAssertion;
-import org.keycloak.testframework.realm.ClientConfigBuilder;
-import org.keycloak.testframework.realm.GroupConfigBuilder;
-import org.keycloak.testframework.realm.UserConfigBuilder;
+import org.keycloak.testframework.realm.ClientBuilder;
+import org.keycloak.testframework.realm.GroupBuilder;
+import org.keycloak.testframework.realm.UserBuilder;
 import org.keycloak.testframework.scim.client.annotations.InjectScimClient;
 import org.keycloak.testframework.util.ApiUtil;
 
@@ -236,7 +236,7 @@ public void testGetById() {
 
     @Test
     public void testGetExisting() {
-        UserRepresentation existing = UserConfigBuilder.create()
+        UserRepresentation existing = UserBuilder.create()
                 .username(KeycloakModelUtils.generateId())
                 .email(KeycloakModelUtils.generateId() + "@keycloak.org")
                 .firstName("f")
@@ -366,7 +366,7 @@ public void testError() {
 
     @Test
     public void testNoManagePermission() {
-        realm.admin().clients().create(ClientConfigBuilder
+        realm.admin().clients().create(ClientBuilder
                 .create()
                 .clientId("noaccess-scim-client")
                 .secret("secret")
@@ -1092,7 +1092,7 @@ private static void assertGroup(List<GroupMembership> groups, GroupRepresentatio
     }
 
     private GroupRepresentation createGroup(String name) {
-        GroupRepresentation group = GroupConfigBuilder.create().name(name).build();
+        GroupRepresentation group = GroupBuilder.create().name(name).build();
         try (Response response = realm.admin().groups().add(group)) {
             group.setId(ApiUtil.getCreatedId(response));
         }
@@ -1101,7 +1101,7 @@ private GroupRepresentation createGroup(String name) {
 
     private GroupRepresentation createSubGroup(GroupRepresentation parent, String name) {
         GroupResource parentApi = realm.admin().groups().group(parent.getId());
-        GroupRepresentation subGroup = GroupConfigBuilder.create().name(name).build();
+        GroupRepresentation subGroup = GroupBuilder.create().name(name).build();
 
         try (Response response = parentApi.subGroup(subGroup)) {
             subGroup.setId(ApiUtil.getCreatedId(response));

@@ -25,5 +25,10 @@
             <artifactId>keycloak-test-framework-core</artifactId>
             <scope>compile</scope>
         </dependency>
+        <dependency>
+            <groupId>org.keycloak.testframework</groupId>
+            <artifactId>keycloak-test-framework-builders</artifactId>
+            <scope>compile</scope>
+        </dependency>
     </dependencies>
 </project>
@@ -17,7 +17,7 @@
 import org.keycloak.testframework.injection.RequestedInstance;
 import org.keycloak.testframework.injection.Supplier;
 import org.keycloak.testframework.injection.SupplierOrder;
-import org.keycloak.testframework.realm.ClientConfigBuilder;
+import org.keycloak.testframework.realm.ClientBuilder;
 import org.keycloak.testframework.realm.ManagedRealm;
 import org.keycloak.testframework.scim.client.annotations.InjectScimClient;
 import org.keycloak.testframework.server.KeycloakServer;
@@ -36,7 +36,7 @@ public ScimClient getValue(InstanceContext<ScimClient, InjectScimClient> instanc
         List<ClientRepresentation> scimClient = managedRealm.admin().clients().findByClientId(config.clientId());
 
         if (scimClient.isEmpty() && config.attachTo().isEmpty()) {
-            try (Response response = managedRealm.admin().clients().create(ClientConfigBuilder.create()
+            try (Response response = managedRealm.admin().clients().create(ClientBuilder.create()
                             .clientId(config.clientId())
                             .secret(config.clientSecret())
                             .serviceAccountsEnabled(true)

@@ -39,6 +39,12 @@
                 <version>${project.version}</version>
                 <scope>test</scope>
             </dependency>
+            <dependency>
+                <groupId>org.keycloak.testframework</groupId>
+                <artifactId>keycloak-test-framework-builders</artifactId>
+                <version>${project.version}</version>
+                <scope>test</scope>
+            </dependency>
             <dependency>
                 <groupId>org.keycloak.testframework</groupId>
                 <artifactId>keycloak-test-framework-junit5-config</artifactId>

@@ -0,0 +1,54 @@
+# Patterns when creating builders
+
+A builder should be named after the representation they are building, replacing the suffix `Representation` with
+`Builder`, for example `RealmRepresentation` builder should be named `RealmBuilder`.
+
+Builders should extend `Builder`, and have the following static methods:
+
+* `TheBuilder create()`
+* `TheBuilder update(TheRepresentation rep)`
+
+When applicable the builder can include overloaded methods with commonly set values:
+
+* `TheBuilder create(String commonValue)`
+
+`Builder` contains a number of convenience methods to help implement `Builders`. Typically any methods implemented in 
+a builder should be 1-2 lines maximum, which is done by using convenience methods.
+
+## Simple values
+
+Methods that set simple values should use the following syntax:
+
+* `TheBuilder something(String something)`
+
+Setting boolean values should use `Boolean` or `boolean` depending on what the representation does:
+
+* `TheBuilder enabled(Boolean enabled)`
+
+When applicable a convinience method can be added to set the boolean to true:
+
+* `TheBuilder enabled()`
+
+## Complex values
+
+Adding complex values are done through:
+
+* `TheBuilder things(ThingRepresentation... things)`
+* `TheBuilder things(ThingBuilder... things)`
+
+In general both representations and builders should be supported.
+
+When applicable adding complex values by passing simple values can be used as well:
+
+* `TheBuilder things(String... things)`
+
+All of the above should append the new complex values to existing values.
+
+If it is required to be able to overwrite complex values that is done by adding:
+
+* `TheBuilder setThings(...)`
+
+If it is required to be able to remove values from complex values, for example removing a list of keys from a map, that
+should be done with:
+
+* `TheBuilder removeThings(String... keys)`
@@ -0,0 +1,76 @@
+<?xml version="1.0"?>
+<!--
+  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
+  ~ and other contributors as indicated by the @author tags.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <parent>
+        <artifactId>keycloak-test-framework-parent</artifactId>
+        <groupId>org.keycloak.testframework</groupId>
+        <version>999.0.0-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>keycloak-test-framework-builders</artifactId>
+    <name>Keycloak Test Framework - Builders</name>
+    <packaging>jar</packaging>
+    <description>Representation builders for Keycloak testing framework</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-core</artifactId>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-server-spi</artifactId>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <dependency>
+            <groupId>org.keycloak</groupId>
+            <artifactId>keycloak-server-spi-private</artifactId>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.jboss.logmanager</groupId>
+            <artifactId>jboss-logmanager</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>