feat(keycloak): add getGroupsOfUser function (#53)

This change adds an additional function to get the effective groups of a
user by username so that tests that need to query the state of users and
groups can retrieve the groups that a user is part of.  This is done by
matching the username currently instead of exposign the keycloak user ID
given that the current default test user set consists of unique user
names.

Assisted-By: Cursor Desktop

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED

Author: gashcrumb

docs/api/deployment/keycloak-helper.md

@@ -150,6 +150,23 @@ async getGroups(realm: string): Promise<GroupRepresentation[]>
 
 Get all groups in a realm.
 
+### `getGroupsOfUser()`
+
+```typescript
+async getGroupsOfUser(realm: string, username: string): Promise<KeycloakGroupConfig[]>
+```
+
+Get the list of groups for a user in a realm. The user is resolved by `username`; no user id is exposed. Useful for assertions in e2e tests (e.g. verifying Backstage user page shows the same groups as Keycloak).
+
+| Parameter | Type     | Description                    |
+| --------- | -------- | ------------------------------ |
+| `realm`   | `string` | Realm name                     |
+| `username`| `string` | Username of the user           |
+
+**Returns:** `KeycloakGroupConfig[]` (at least `name`).
+
+Requires `connect()` or `deploy()` to have been called first.
+
 ### `deleteUser()`
 
 ```typescript

docs/changelog.md

@@ -2,7 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.1.16] - Current
+## [1.1.17] - Current
+
+### Added
+
+- **KeycloakHelper.getGroupsOfUser(realm, username)**: Returns groups for a user in a realm; the user is resolved by `username` (id is resolved internally). Intended for e2e assertions that compare Backstage UI to Keycloak data (e.g. catalog users page).
+
+## [1.1.16]
 
 ### Fixed
 

docs/guide/deployment/keycloak-deployment.md

@@ -171,6 +171,25 @@ const groups = await keycloak.getGroups("rhdh");
 await keycloak.deleteGroup("rhdh", "testers");
 ```
 
+### Using getUsers and getGroupsOfUser in tests
+
+When testing against an existing Keycloak (e.g. RHDH with Keycloak auth), use `connect(config)` with base URL, realm, and client id/secret (or username/password). Then use `getUsers(realm)` to get the list of users and `getGroupsOfUser(realm, user.username)` to get each user's groups for UI assertions (e.g. catalog users page):
+
+```typescript
+await keycloak.connect({
+  baseUrl: process.env.KEYCLOAK_BASE_URL!,
+  realm: process.env.KEYCLOAK_REALM!,
+  clientId: process.env.KEYCLOAK_CLIENT_ID!,
+  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET!,
+});
+
+const users = await keycloak.getUsers(realm);
+for (const user of users) {
+  const groups = await keycloak.getGroupsOfUser(realm, user.username);
+  // Assert Backstage UI shows same groups for this user
+}
+```
+
 ### Realm Management
 
 ```typescript

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@red-hat-developer-hub/e2e-test-utils",
-  "version": "1.1.16",
+  "version": "1.1.17",
   "description": "Test utilities for RHDH E2E tests",
   "license": "Apache-2.0",
   "repository": {

src/deployment/keycloak/deployment.ts

@@ -299,6 +299,27 @@ export class KeycloakHelper {
     return groups.map((g) => ({ name: g.name! }));
   }
 
+  /**
+   * Get groups for a user in a realm (user resolved by username).
+   */
+  async getGroupsOfUser(
+    realm: string,
+    username: string,
+  ): Promise<KeycloakGroupConfig[]> {
+    await this._ensureAdminClient();
+    this._adminClient!.setConfig({ realmName: realm });
+
+    const users = await this._adminClient!.users.find({ username });
+    if (users.length === 0) {
+      return [];
+    }
+    const user = users[0];
+    const groups = await this._adminClient!.users.listGroups({
+      id: user.id!,
+    });
+    return groups.map((g) => ({ name: g.name! }));
+  }
+
   /**
    * Delete a user from a realm
    */

src/deployment/keycloak/index.ts

@@ -1 +1,2 @@
 export { KeycloakHelper } from "./deployment.js";
+export type { KeycloakUserConfig, KeycloakGroupConfig } from "./types.js";