{"id":13711607,"url":"https://github.com/Fredx87/cypress-keycloak-commands","last_synced_at":"2025-05-06T21:31:42.064Z","repository":{"id":39993642,"uuid":"235065719","full_name":"Fredx87/cypress-keycloak-commands","owner":"Fredx87","description":"Cypress commands for login with Keycloak","archived":false,"fork":false,"pushed_at":"2024-04-26T13:48:01.000Z","size":790,"stargazers_count":71,"open_issues_count":39,"forks_count":29,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-04-06T17:12:49.422Z","etag":null,"topics":["auth","cypress","e2e","keycloak","login","oauth","openid","testing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fredx87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-20T09:36:51.000Z","updated_at":"2024-11-18T09:22:31.000Z","dependencies_parsed_at":"2024-05-13T00:44:53.696Z","dependency_job_id":null,"html_url":"https://github.com/Fredx87/cypress-keycloak-commands","commit_stats":{"total_commits":39,"total_committers":4,"mean_commits":9.75,"dds":"0.10256410256410253","last_synced_commit":"1e93f62c0a8cb5f0bd174e6048a9caa801061f35"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fredx87%2Fcypress-keycloak-commands","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fredx87%2Fcypress-keycloak-commands/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fredx87%2Fcypress-keycloak-commands/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fredx87%2Fcypress-keycloak-commands/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fredx87","download_url":"https://codeload.github.com/Fredx87/cypress-keycloak-commands/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252772041,"owners_count":21801836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth","cypress","e2e","keycloak","login","oauth","openid","testing"],"created_at":"2024-08-02T23:01:09.818Z","updated_at":"2025-05-06T21:31:41.667Z","avatar_url":"https://github.com/Fredx87.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# cypress-keycloak-commands\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\nCypress commands for login with [Keycloak](https://www.keycloak.org/).\n\n- Setup Keycloak configuration from Cypress configuration or environment variables\n- Use Fixtures to store users data\n- Returns you the tokens of the logged user for calling backend APIs from your test code\n- Fake login command for integration testing\n- Tested with Keycloak 4.8, 5, 6, 7 and 8\n\n## Usage\n\n### Installing\n\nInstall the package using npm:\n\n```\nnpm i -D cypress-keycloak-commands\n```\n\nor Yarn:\n\n```\nyarn add -D cypress-keycloak-commands\n```\n\nImport the package in the file `cypress/support/commands.js` (or `cypress/support/commands.ts`):\n\n```typescript\nimport \"cypress-keycloak-commands\";\n```\n\n### Setup Keycloak configuration\n\nSetup the Keycloak configuration in `cypress.json` configuration file:\n\n```json\n{\n  \"env\": {\n    \"auth_base_url\": \"https://auth.server/auth\",\n    \"auth_realm\": \"my_realm\",\n    \"auth_client_id\": \"my_client_id\"\n  }\n}\n```\n\nYou can override this settings for some tests using [Enviroment variabiles](https://docs.cypress.io/guides/guides/environment-variables.html).\n\n### Login commands for E2E Tests\n\nFor logging in with Keycloak you must create a [fixture](https://docs.cypress.io/api/commands/fixture.html) containing the user credentials under the directory `cypress/fixtures/users`. For example you can create a file `cypress/fixtures/users/user.json` with this content:\n\n```json\n{\n  \"username\": \"user\",\n  \"password\": \"password\"\n}\n```\n\nWhen you have a fixture you can login using the `kcLogin` command, passing the name of the fixture, and you can perform a logout using the `kcLogout` command:\n\n```typescript\ndescribe(\"Keycloak Login\", () =\u003e {\n  beforeEach(() =\u003e {\n    cy.kcLogout();\n    cy.kcLogin(\"user\");\n    cy.visit(\"/\");\n  });\n});\n```\n\nYou should always perform logout _before_ logging in a user, following the best practice of [cleaning the state in the beforeEach hook](https://docs.cypress.io/guides/references/best-practices.html#Using-after-or-afterEach-hooks).\n\n#### Get user tokens for calling APIs from E2E tests\n\nIf you need to call backend APIs from your tests using the token of the logged user (for example to [set up the state bypassing the UI](https://docs.cypress.io/guides/getting-started/testing-your-app.html#Bypassing-your-UI)) you can get the retrieved user tokes from the kcLogin command:\n\n```typescript\ndescribe(\"Keycloak Login\", () =\u003e {\n  beforeEach(() =\u003e {\n    cy.kcLogout();\n    cy.kcLogin(\"user\").as(\"tokens\");\n    cy.visit(\"/\");\n  });\n\n  it(\"should call an API with the token\", () =\u003e {\n    cy.get(\"@tokens\").then(tokens =\u003e {\n      cy.request({\n        url: \"/my_api\"\n        auth: {\n          bearer: tokens.access_token\n        }\n      });\n    });\n  });\n});\n```\n\nNote: if you use Typescript you have to specify the return type of the `cy.get` command:\n\n```typescript\ncy.get\u003cKcTokens\u003e(\"@tokens\");\n```\n\n### Fake Login for Integration testing\n\nIf you are doing an integration test that doesn't call a real backend API, maybe you don't need to authenticate a real user to a running Keycloak instance, but if your app uses the Keycloak Javascript Adapter to check if a user is logged in, you will need to have a mocked user.\n\nTo create mocked user data, you need three tokens (access token, refresh token, id token) of a real user returned by your Keycloak instance. You can get them for example from the Dev Tools of your browser, searching for calls to the `token` endpoint of Keycloak. If your app calls the `/account` endpoint to retrieve user information you will also need to have the response returned for the API. Then you can create the fixture with the fake user data:\n\n```json\n{\n  \"fakeLogin\": {\n    \"access_token\": \"...\",\n    \"refresh_token\": \"...\",\n    \"id_token\": \"...\",\n    \"account\": {\n      \"username\": \"user\",\n      \"firstName\": \"Sample\",\n      \"lastName\": \"User\",\n      \"email\": \"sample-user@example\",\n      \"emailVerified\": false,\n      \"attributes\": {}\n    }\n  }\n}\n```\n\nWith the fixture in place, you can use the `kcFakeLogin` command to perform a fake login without hitting a real Keycloak instance.\n\nThe Fake Login is performed loading a page and passing some keycloak initialization parameters in the URL. If you need to visit a page different from the homepage you must pass its url to the `kcFakeLogin` command as second parameter (instead of using `cy.visit`):\n\n```typescript\ndescribe(\"Keycloak Fake Login\", () =\u003e {\n  beforeEach(() =\u003e {\n    cy.kcFakeLogin(\"user\", \"pageToVisit\");\n  });\n});\n```\n\n#### Session Status iframe\n\nAt the moment within Cypress is not possible to mock iframe loading and APIs called from an iframe. For this reason, when you use `kcFakeLogin` you have to disable the Session Status iframe, otherwise the Javascript adapter will redirect you to the real Keyacloak instance. You can disable it only when the app is running inside Cypress:\n\n```typescript\nconst checkLoginIframe = window.Cypress ? false : true;\n\nvar initOptions = {\n  responseMode: \"fragment\",\n  flow: \"standard\",\n  onLoad: \"login-required\",\n  checkLoginIframe\n};\n```\n\n## Acknowledgements\n\nOther solutions that have inspired this library:\n\n- https://vrockai.github.io/blog/2017/10/28/cypress-keycloak-intregration/\n- https://www.npmjs.com/package/cypress-keycloak\n\n## License\n\nMIT\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Fredx87\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/13420283?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGianluca Frediani\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#infra-Fredx87\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"#tool-Fredx87\" title=\"Tools\"\u003e🔧\u003c/a\u003e \u003ca href=\"https://github.com/Fredx87/cypress-keycloak-commands/commits?author=Fredx87\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/Fredx87/cypress-keycloak-commands/commits?author=Fredx87\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#ideas-Fredx87\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/Fredx87/cypress-keycloak-commands/commits?author=Fredx87\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/groie\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/5516998?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eIlkka Harmanen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Fredx87/cypress-keycloak-commands/commits?author=groie\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFredx87%2Fcypress-keycloak-commands","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFredx87%2Fcypress-keycloak-commands","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFredx87%2Fcypress-keycloak-commands/lists"}