Preview - Keycloak Test Framework

Signed-off-by: Lukas Hanusovsky <[email protected]>

blog/2024/preview-keycloak-test-framework.adoc

@@ -0,0 +1,40 @@
+:title: "Writing new tests has never been easier than before." Keycloak Test Framework
+:date: 2024-08-28
+:publish: true
+:author: Lukas Hanusovsky
+
+== How It All Started
+
+The idea to replace the current https://github.com/keycloak/keycloak/tree/main/testsuite[test suite] has been on a table for multiple years. Initially it was meant to be only a refactoring of current approach on how to write tests, but after few internal discussions and refactor updates it turned out a new test suite, based on a https://github.com/keycloak/keycloak/tree/main/test-framework[new framework] would be better solution.
+
+It would be good to mention few drawbacks, which stand out, when working with this https://github.com/keycloak/keycloak/tree/main/testsuite[test suite]. First of all is the complexity of various configurations and additions on top of the _Arquillian_  https://arquillian.org/[framework]. These changes helps to do what is the test suite capable off, but the cons is that without a proper documentation for beginners is almost unreadable. Second thing has the same importance, the _Arquillian_ https://arquillian.org/[framework] is not fully supported anymore. Other things to mention are complicated execution system, where you want to specify what exactly should be tested, then abstract classes with shared configurations, missing the option to add a custom extension, and last but not least, massive amount of tests without a knowledge if they are needed anymore.
+
+== Brighter Future?
+
+Keycloak team had started a https://github.com/orgs/keycloak/projects/42[joint effort] between the engineering and quality engineering people to design a new https://github.com/keycloak/keycloak/tree/main/test-framework[test framework] (May 2024). It had been initiated with a prototype to verify, if our thoughts are feasible. The prototype should have been based on the _JUnit5_ testing framework, specifically to implement _JUnit5_ callback classes which extend the default test lifecycle functionality and provide custom inject annotations, like _@KeycloakIntegrationTest_, _@InjectWebDriver_ or _@InjectRealm_.
+
+For our purpose we've https://github.com/keycloak/keycloak/blob/main/test-framework/src/main/java/org/keycloak/test/framework/KeycloakIntegrationTestExtension.java[implemented] these three callback classes:
+----
+BeforeEachCallback
+AfterEachCallback
+AfterAllCallback
+----
+
+After a successful test round, we've continued with a proof of concept extending features list to support multiple server modes, different databases and _WebDrivers_, clients and users setup, _SmallRye_ configuration support, _OAuthClient_ based on https://connect2id.com/products/nimbus-oauth-openid-connect-sdk[_Nimbus SDK_] (this feature is a preview only) etc. The full list of currently implemented features can be found here in the https://github.com/keycloak/keycloak/tree/main/test-framework/src/main/java/org/keycloak/test/framework/annotations[annotations package].
+
+Are you curious where to start?
+We suggest to read the https://github.com/keycloak/keycloak/blob/main/test-framework/README.md[user guide], which will provide a basic overview how the framework works and should be used. If this is not enough, you can also check https://github.com/keycloak/keycloak/tree/main/test-poc/examples[examples module].
+
+Once you find some bug or want to discuss something, or propose a new enhancement, please follow this GitHub feedback https://www.github.com/discussion#blabla[discussion] link.
+
+== What To Expect
+
+Preview - https://github.com/keycloak/keycloak/tree/main/test-framework[_Keycloak Test Framework_] will be introduced in _Keycloak 26_. We plan to add more features, which will cover 80% of functionalities currently available in the https://github.com/keycloak/keycloak/tree/main/testsuite[integration test suite]. Another interesting feature will be _@KeycloakTest_ annotation, which will add an option to test providers without _Keycloak_ server running. It should be based on the _KeycloakSession_ class.
+
+== Acknowledgement
+
+I would like to thanks to all people who put the proof of concept together and made it a real: Miquel, Simon, Filip, Moises, Jon, Pedro. Special thanks goes to Stian, who led the technical design and proposed very nifty things that raised the project to another level.
+
+Thank you for your feedback.
+
+Enjoy!