{"id":15383615,"url":"https://github.com/mvysny/karibu-testing","last_synced_at":"2025-04-04T08:07:07.151Z","repository":{"id":37396666,"uuid":"123093803","full_name":"mvysny/karibu-testing","owner":"mvysny","description":"Vaadin Server-Side Browserless Containerless Unit Testing","archived":false,"fork":false,"pushed_at":"2025-03-20T07:58:11.000Z","size":2946,"stargazers_count":115,"open_issues_count":16,"forks_count":14,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-27T04:12:04.439Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mvysny.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2018-02-27T07:58:35.000Z","updated_at":"2025-03-20T07:58:14.000Z","dependencies_parsed_at":"2023-09-27T21:43:22.998Z","dependency_job_id":"97e2d4d0-7a00-4d64-b9d8-b343ade33004","html_url":"https://github.com/mvysny/karibu-testing","commit_stats":null,"previous_names":[],"tags_count":124,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvysny%2Fkaribu-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvysny%2Fkaribu-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvysny%2Fkaribu-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvysny%2Fkaribu-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mvysny","download_url":"https://codeload.github.com/mvysny/karibu-testing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142065,"owners_count":20890652,"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":[],"created_at":"2024-10-01T14:38:55.113Z","updated_at":"2025-04-04T08:07:07.127Z","avatar_url":"https://github.com/mvysny.png","language":"Kotlin","funding_links":[],"categories":["测试","others"],"sub_categories":[],"readme":"[![CI](https://github.com/mvysny/karibu-testing/actions/workflows/gradle.yml/badge.svg)](https://github.com/mvysny/karibu-testing/actions/workflows/gradle.yml)\n[![Join the chat at https://gitter.im/vaadin/vaadin-on-kotlin](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/vaadin/vaadin-on-kotlin?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![GitHub tag](https://img.shields.io/github/tag/mvysny/karibu-testing.svg)](https://github.com/mvysny/karibu-testing/tags)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.mvysny.kaributesting/karibu-testing-v8/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.mvysny.kaributesting/karibu-testing-v8)\n\n# Karibu-Testing: The Vaadin Unit Testing\n\nThe Unit Testing library for [Vaadin](https://vaadin.com/).\n\nWhen building apps with Vaadin Flow, your app manipulates Vaadin components\nserver-side, while the browser is just a mere \"reflection\" of\nthe server-side state. For example, setting the `Button`'s caption to \"Foo\" updates the `Button`'s\nstate server-side; Vaadin Flow then automatically applies the change in the browser-side `\u003cvaadin-button\u003e` element.\nThis happens automatically, behind-the-scenes; this is tested by the Vaadin company and doesn't need to be\ntested by your app. Therefore, to test your app, you can leave out the \"unimportant\" browser part: you\nwant your tests to focus on the server-side where your logic resides.\n\nKaribu-Testing gives you the ability to call `UI.getCurrent()` straight from your JUnit\ntest methods, and receive a\nmeaningful result in the process. You can call `UI.navigate()` to navigate around in your app;\nyou can instantiate your components and views directly from your JUnit test methods.\nIn order to do so, Karibu-Testing mocks `CurrentRequest`, `VaadinSession` and others in your\ncurrently running JVM (in which your JUnit tests run).\n\nKaribu-Testing only runs in JVM and only tests server-side code. There is no browser running\nand no JavaScript code running, which means that there is no communication between the browser and the server,\nwhich means that you don't even need to run the servlet container. You simply create new instance\nof your Vaadin form, modify the field values directly, then simulate a click to the \"Save\" button\nand see the binder validations running. You can even call `UI.navigate()` to\nnavigate to a view; the navigation is handled completely server-side and adds components to `UI.getCurrent()`.\nYou then assert on the contents of `UI.getCurrent()` to verify that your code ran properly.\n\nIn short, Karibu-Testing is here to perform:\n\n1. *containerless testing*: You don't need to launch the servlet container.\nKaribu-Testing creates Vaadin Session, the UI and other necessary Vaadin classes\nstraight in the JVM which runs your JUnit tests.\n2. *browserless testing*: You look up components straight from\n`UI.getCurrent()`, bypassing browser and the JavaScript-\u003eServer bridge completely.\nYou directly call methods on your server-side View classes and on the server-side Java Vaadin components.\n\n\u003e If you like the library, please star it. The more stars, the more popularity and more maintainenance the library will receive.\n\nCheck out a [30 second video of live coding with Karibu-Testing](https://www.youtube.com/watch?v=znVNEo9cj98) to get a taste\non how simple this library is.\n\nThe library supports Kotlin, Java and Groovy (Groovy support for Vaadin 14+ only).\n\n## News: UI Unit-Testing is being added to TestBench!\n\nThe Vaadin UI Unit-Testing idea, pioneered by Karibu-Testing, proved useful for many Vaadin users.\nVaadin recognized the effort and is adding official support for [UI unit-testing into TestBench](https://vaadin.com/docs/latest/testing/ui-unit).\nThe Vaadin UI Unit-Testing is now available in alpha builds of TestBench for Vaadin 23.1.1;\nstable version will require at least Vaadin 23.2 (maybe higher).\n\nAt the moment the Vaadin API is being prototyped and is not finalized. The Vaadin API\nwill most probably look a bit differently than Karibu-Testing API though:\n\n* Karibu-Testing is Kotlin-first and uses the extension function mechanism heavily.\n  Java has no extension functions though; we chose the mechanism of static methods (`LocatorJ` and others)\n  to make Karibu accessible in Java. While we do offer full support for Java (and a bit limited support for Groovy),\n  we will stay with the static methods solution for Java.\n* TestBench is Java-first and static methods are not offered via auto-complete IDE mechanism,\n  leading to a sub-par experience. Therefore, Vaadin team chose the way of creating wrapper classes.\n  That offers better IDE support in Java but requires a lot of effort creating and managing those wrapper\n  classes.\n\nAt the moment Karibu-Testing classes are included in the Vaadin UI Unit-Testing library (as an implementation detail). However,\nthis can change at any time.\n\nThe development of both products will now happen independently. If the Vaadin guys\nhave a lovely idea, please open a feature request for Karibu so that we can steal those ideas :-D (Did you know that greatest artists steal?)\n\n**Important:** The development of Karibu-Testing will continue as usual; we will\ncontinue supporting both Vaadin 14 and 23, both Kotlin, Groovy and Java, and we will\ncontinue designing the API via the \"extension functions\" mechanism.\n\n## Getting Started / Main Documentation / Full Documentation\n\n### Vaadin 14+\n\n**\u003e\u003e\u003eSee [The main Karibu-Testing documentation for Vaadin 14+](karibu-testing-v10) \u003c\u003c\u003c**.\nKaribu-Testing is compatible with any Vaadin 14+ version (14, 15, 16, 17, 18, 19, 20, 21, 22, 23 etc).\n\n### Vaadin 8\n\n**\u003e\u003e\u003eSee [The main Karibu-Testing documentation for Vaadin 8](../../tree/1.4.x/karibu-testing-v8) \u003c\u003c\u003c**.\nKaribu-Testing is compatible with any Vaadin 8.x version.\n\n**Important:** Vaadin 8 has [reached an end-of-life at Feb 2022](https://vaadin.com/vaadin-8)\nand is no longer maintained by Vaadin for free. You can get new releases of Vaadin 8 but only\nas a commercial offering from Vaadin. There are even Vaadin 8 builds which use the `jakarta` APIs\ninstead of `javax`, but [Karibu-Testing doesn't support jakarta Vaadin 8 at the moment](https://github.com/mvysny/karibu-testing/issues/178).\nKaribu-Testing support for Vaadin 8 javax is currently in hibernation: no maintenance\nis done at this moment.\n\n## Why Unit-testing?\n\nAdvantages over the traditional testing with [Selenium](https://www.seleniumhq.org/)/[TestBench](https://vaadin.com/testbench):\n\n* *Fast*: Browserless tests are typically 100x faster than Selenium-based tests and run in 5-60 milliseconds,\n  depending on their complexity.\n* *Reliable*: We don't need arbitrary sleeps since we're server-side and we can await until the request is fully processed.\n  We don't use Selenium drivers which are known to fail randomly.\n* *Headless*: The tests run headless since there's no browser. There is no need to setup screen in\n  your CI environment.\n* *Simple*: the test runs in the same JVM as the server. You start the server in your `@BeforeClass` and\n  stop the server in your `@AfterClass`. There is no need to use Maven's Integration plugin\n  to start the server in the background (and then remember to kill it afterwards, otherwise all future CI tests\n  will fail to start the server since it's already running).\n* *Robust*: the test runs in the same JVM as the server. If the\n  server fails to start and throws an exception, the test method too will fail with the same exception.\n  No need to go hunting for exceptions in a log located somewhere on a CI server.\n* No need to write\n  [Page Object](https://vaadin.com/docs/v14/tools/testbench/testbench-maintainable-tests-using-page-objects) for every\n  Vaadin component, form and view your app contains, effectively doubling your code-base.\n  Remember - you're already on the server, and you have access to the actual Java components\n  which already are providing you with high-level APIs, exactly as Page Objects do.\n* Full access to the *Database*. You're server-side - you can access the database from your tests the same way your\n  business logic accesses the database. You can run a bunch of SQLs to restore the database to a known state before\n  every test. Even better - you can run the test in a transaction then roll back after the test, to\n  perform fast database revert to a known state.\n\nWith this technique you can run 600 UI tests in 7 seconds, as opposing to 1-2 hours with Selenium-based approach.\nBecause of the speed, you can let the UI tests run after every commit by your continuous integration server.\n\nSince we're bypassing the browser and talking to Vaadin server API directly, you don't even need to start the servlet container -\nyou can just add the server jars onto testing classpath and call Vaadin server API which will in turn invoke your server logic.\n\nA 15-minute [video](https://www.youtube.com/watch?v=XOhv3y2GXIE) explains everything behind the browserless testing technique.\n\n## Kotlin, Java and Groovy support\n\nThe Karibu-Testing library is Standalone and Fully Supports Java and Groovy.\n\nEven though the Karibu-Testing is endorsed by [Vaadin-on-Kotlin](http://vaadinonkotlin.eu), the Karibu-Testing\ndoes not really depend on any other technology than Vaadin. You don't have to use Vaadin-on-Kotlin nor Karibu-DSL to use Karibu-Testing.\nYou don't even need to write your app nor your tests in Kotlin, since the library provides native API\nfor Kotlin, Java and Groovy.\n\nYou can therefore plug this library in into your Java+Vaadin-based project as a test dependency, and write the test code\nin Java, Kotlin or Groovy, whichever suits you more.\n\nKaribu-Testing is published on Maven Central, so it's very easy to add as a Maven dependency.\n\n## Project Status\n\nThe library is mature and stable since 2020. It has been extensively tested and employed in numerous\nreal-world projects. Small features are being added infrequently,\nand compatibility with all latest Vaadin versions is checked on every commit.\n\n## Example Projects\n\nA list of a very simple example projects that employ Karibu Testing:\n\n* Vaadin 24 + Kotlin + Gradle: [karibu-helloworld-application](https://github.com/mvysny/karibu10-helloworld-application)\n* Vaadin 24 + Java + Spring Security + Maven: [vaadin-spring-karibu-testing](https://github.com/mvysny/vaadin-spring-karibu-testing)\n* Vaadin 24 + Vaadin-on-Kotlin + Gradle: [Beverage Buddy VoK](https://github.com/mvysny/beverage-buddy-vok)\n* Vaadin 24 + JOOQ + Gradle: [Beverage Buddy VoK](https://github.com/mvysny/beverage-buddy-jooq)\n* Vaadin 24 + JDBI-ORM + Maven + Junit5: [jdbi-orm-vaadin-crud-demo](https://github.com/mvysny/jdbi-orm-vaadin-crud-demo)\n* Vaadin 24 + Vaadin-on-Kotlin + Gradle: [Bookstore Example](https://github.com/mvysny/bookstore-vok)\n* Vaadin 24 + Vaadin-on-Kotlin + Gradle: [Vaadin Kotlin PWA](https://github.com/mvysny/vaadin-kotlin-pwa)\n* Vaadin 23 + Spring Boot + Java + Maven + JUnit 5: [t-shirt-shop-example](https://github.com/mvysny/t-shirt-shop-example)\n* Vaadin 14 + Java + Maven + JUnit 5: [skeleton-starter-kt](https://github.com/mvysny/skeleton-starter-kt)\n* Vaadin 14 + Java + Maven + JUnit 5: [vaadin10-sqldataprovider-example](https://github.com/mvysny/vaadin10-sqldataprovider-example)\n* Vaadin 14 + Java + Quarkus + Maven: [vaadin-quarkus](https://github.com/mvysny/vaadin-quarkus) (also check the `v19` branch for Vaadin 19).\n* Vaadin 8 + Kotlin + Gradle: [karibu8-helloworld-application](https://github.com/mvysny/karibu-helloworld-application)\n* Vaadin 8 + Java + Maven + JUnit 5: [vaadin8-sqldataprovider-example](https://github.com/mvysny/vaadin8-sqldataprovider-example)\n* Vaadin 8 + Spring Boot + Java + Maven + JUnit 4: [karibu-testing-spring](https://github.com/mvysny/karibu-testing-spring)\n\n## Limitations\n\nKaribu-Testing is designed to bypass browser and the servlet container. It's a double-edged\nsword: while this provides insane speed, it also sets limits what you can do with Karibu-Testing:\n\n* There is no browser: **It's not possible to test nor call JavaScript code**. That also limits\n  testability of your Polymer Templates; see [Testing with Vaadin](karibu-testing-v10) for more details.\n  If you need to test JavaScript code, you need to use Selenium or [TestBench](https://vaadin.com/testbench) in\n  addition to Karibu-Testing.\n* Since your JUnit methods access views which in turn access your business logic beans\n  and your database directly, **You must be able to \"start\" your app in the same JVM which runs the tests.**.\n\nHere are a few tips on how to \"start\" your app in the JUnit JVM:\n\n* For simple apps with just the UI and no database that's very easy: simply call `MockVaadin.setup { MyUI() }` before every test, and `MockVaadin.tearDown()` after every test. That will\ninstantiate your UI along with all necessary Vaadin environment.\n* For more complex apps employing database access (for example [Vaadin-on-Kotlin](http://vaadinonkotlin.eu) apps) you need to bootstrap Vaadin-on-Kotlin. Luckily that's very easy,\nsimply configure your database in `VaadinOnKotlin.dataSourceConfig` and then init vok: `VaadinOnKotlin.init()` before all tests. Or even better,\nsince you typically do this in a `ServletContextListener` such as the `Bootstrap` class, simply call that: `Bootstrap().contextInitialized(null)`. Then, when the app is bootstrapped,\nyou can proceed to setting up your UI by calling `MockVaadin.setup { MyUI() }` before every test, and `MockVaadin.tearDown()` after every test.\n* For more complex apps not using Vaadin-on-Kotlin, just use the same approach of simply calling all `ServletContextListener` which you have in your app, before all tests are executed.\nThen, when the app is bootstrapped,\nyou can proceed to setting up your UI by calling `MockVaadin.setup { MyUI() }` before every test, and `MockVaadin.tearDown()` after every test.\n* For Spring-based apps it's best to use Spring testing capabilities to bootstrap your app with Spring Test. Then, after that's done, use Spring injector to obtain the instance of your UI:\ncall `MockVaadin.setup { beanFactory!!.getBean(MainUI::class.java) }` before every test, and `MockVaadin.tearDown()` after every test. Please see the [karibu-testing-spring](https://github.com/mvysny/karibu-testing-spring) example project\nfor more details.\n* For JavaEE-based apps you need to figure out how to launch your app in some kind of embedded JavaEE container in JUnit's JVM.\n\n## More Resources\n\n* The [video](https://www.youtube.com/watch?v=XOhv3y2GXIE) which explains everything behind the browserless testing technique.\n* The [browserless web testing](https://mvysny.github.io/browserless-web-testing/) article describes this technique in more depth.\n* The [Testing the UI without a browser](https://vaadin.com/blog/testing-the-ui-without-a-browser) blog post summarizes this technique.\n\nThis project also offers a mock/fake servlet API implementation, see [mock-servlet-environment](mock-servlet-environment/) for more details.\n\n## FAQ\n\nQ: I'm getting `java.lang.IllegalStateException: UI.getCurrent() must not be null`\n   or `no VaadinSession bound to current thread`.\n\nA: You probably forgot to call `MockVaadin.setup()` before the test. Just call `MockVaadin.setup()`\n   e.g. from your `@Before`-annotated method if you're using JUnit.\n   \nAlternatively it could be that Spring is instantiating Vaadin component eagerly\n   when the ApplicationContext is constructed. One workaround is to mark\n   Vaadin components with `@Lazy` so that they are instantiated lazily.\n\nQ: I'm getting `RouteNotFoundError`/`NotFoundException` instead of my views (Vaadin 14+)\n\nA: The `@Route`-annotated view classes have not been discovered and registered.\n   Please discover the routes via `new Routes().autoDiscoverViews(\"com.example.yourpackage\")`\n   (make sure to use the correct Java package where all of your views are placed)\n   then call `MockVaadin.setup(routes)`.\n\nAlso when migrating from Karibu-Testing 1.1 to 1.2.x and you're using a custom `VaadinServlet`,\nplease make sure to call `routes.register(service.context as VaadinServletContext)` from the\n`createServletService()` method, as shown in [Issue #60](https://github.com/mvysny/karibu-testing/issues/60).\n\nQ: Can I integrate CDI (e.g. weld?)\n\nA: You can get inspiration [here](https://github.com/mvysny/karibu-testing/issues/60).\n\nQ: Performance speed-up tips?\n\n1. (Vaadin 14+): the view auto-discovery is rather slow: you can discover the routes\n   only once (for example in your `@BeforeClass`-annotated method), then store the `Routes`\n   instance into a static field and reuse it for every call to `MockVaadin.setup(routes)`.\n2. (Vaadin 14+): `new Routes().autoDiscoverViews(\"\")` is slower than\n   `new Routes().autoDiscoverViews(\"com.example.yourpackage\")`\n3. (Vaadin 14+): PWA icon computation is horribly slow (2 seconds per test); make\n   sure it's off (the `Routes.skipPwaInit` should be `true` which is also the default value).\n4. Instead of logging in by filing the login form before every test, you can simply\n   login by placing `User` instance into your session directly (this of course\n   pretty much depends on how security is handled in your app).\n5. The first test is usually slower since all Vaadin-related classes need to be loaded\n   (could take 1-2 seconds to run); however any subsequent tests should be much faster\n   (~5-60 milliseconds).\n\n# License\n\nLicensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.html)\n\nCopyright 2017-2018 Martin Vysny\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this software except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n# Contributing / Developing\n\nSee [Contributing](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmvysny%2Fkaribu-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmvysny%2Fkaribu-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmvysny%2Fkaribu-testing/lists"}