{"id":29097401,"url":"https://github.com/lambdaisland/kaocha-cljs2","last_synced_at":"2025-07-13T07:38:36.923Z","repository":{"id":47041875,"uuid":"262985426","full_name":"lambdaisland/kaocha-cljs2","owner":"lambdaisland","description":"Run ClojureScript tests from Kaocha (major rewrite)","archived":false,"fork":false,"pushed_at":"2023-08-24T20:27:31.000Z","size":90,"stargazers_count":28,"open_issues_count":10,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-08T21:35:35.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambdaisland.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2020-05-11T08:36:03.000Z","updated_at":"2025-04-30T04:12:00.000Z","dependencies_parsed_at":"2024-04-23T08:49:35.654Z","dependency_job_id":"8f53bf54-0a38-42cb-a391-bccc2e02ffcc","html_url":"https://github.com/lambdaisland/kaocha-cljs2","commit_stats":{"total_commits":60,"total_committers":12,"mean_commits":5.0,"dds":0.5,"last_synced_commit":"cab410faa8bbd49e7ea2d98ad9fca3779cf269e9"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/lambdaisland/kaocha-cljs2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fkaocha-cljs2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fkaocha-cljs2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fkaocha-cljs2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fkaocha-cljs2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdaisland","download_url":"https://codeload.github.com/lambdaisland/kaocha-cljs2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaisland%2Fkaocha-cljs2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259375702,"owners_count":22848023,"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":"2025-06-28T13:42:11.400Z","updated_at":"2025-07-13T07:38:36.917Z","avatar_url":"https://github.com/lambdaisland.png","language":"Clojure","funding_links":["http://opencollective.com/lambda-island"],"categories":[],"sub_categories":[],"readme":"# kaocha-cljs2\n\n\u003c!-- badges --\u003e\n[![cljdoc badge](https://cljdoc.org/badge/lambdaisland/kaocha-cljs2)](https://cljdoc.org/d/lambdaisland/kaocha-cljs2) [![Clojars Project](https://img.shields.io/clojars/v/lambdaisland/kaocha-cljs2.svg)](https://clojars.org/lambdaisland/kaocha-cljs2)\n\u003c!-- /badges --\u003e\n\nRun ClojureScript tests with [Kaocha](https://github.com/lambdaisland/kaocha). New and improved.\n\n\u003c!-- opencollective --\u003e\n\n\u0026nbsp;\n\n\u003cimg align=\"left\" src=\"https://github.com/lambdaisland/open-source/raw/master/artwork/lighthouse_readme.png\"\u003e\n\n\u0026nbsp;\n\n## Support Lambda Island Open Source\n\nkaocha-cljs2 is part of a growing collection of quality Clojure libraries and\ntools released on the Lambda Island label. If you are using this project\ncommercially then you are expected to pay it forward by\n[becoming a backer on Open Collective](http://opencollective.com/lambda-island#section-contribute),\nso that we may continue to enjoy a thriving Clojure ecosystem.\n\n\u0026nbsp;\n\n\u0026nbsp;\n\n\u003c!-- /opencollective --\u003e\n\n## Introduction\n\nRunning ClojureScript tests is fundamentally different from running Clojure\ntests in two ways: ClojureScript needs to be compiled first, and then it needs\nto run inside a JavaScript environment like Node.js or a browser.\n\nSo there is a certain amount of preparation needed. First something invokes the\nClojureScript compiler, which outputs JavaScript, then something needs to launch\na JavaScript runtime (a browser, Node), and make sure that JavaScript gets\nloaded into it.\n\nFinally Kaocha needs to establish communication with that runtime, so that it\ncan invoke tests and collect results.\n\nIn the original `kaocha-cljs` we tried to do all of that. We relied on the\nClojureScript `repl-env` abstraction to do compilation behind the scenes, and to\nlaunch a browser tab or node process, and communicate with it.\n\nIn `kaocha-cljs2` we have chosen a different approach. We no longer care about\nhow you compile your ClojureScript or how you launch your runtime. You can\nautomate that or do it manually, but it's your concern. We will of course\nprovide examples for common tools and use cases.\n\nThis means that we are forward compatible with any ClojureScript build tool,\ncurrent or future. We also no longer care about compiler settings like the\noptimization level or how you manage dependencies and third party JavaScript.\nAll we ask is that you include a `:preload` in your build, so that we are able\nto communicate with it.\n\n## Cast of Characters\n\nBecause we have separated the different responsibilities to separate projects,\nit does make it a little harder to keep track. These are the different pieces\ninvolved.\n\n### [Kaocha](https://github.com/lambdaisland/kaocha)\n\nExtensible test runner. Written in Clojure, so runs on the JVM. Can run test\nsuites of many different types. Has CLI and REPL interfaces, and can be\ncustomized with plugins.\n\n### [Chui](https://github.com/lambdaisland/chui)\n\nTest runner written in ClojureScript. Consists of:\n- `chui-core`: which provides the test runner logic and API\n- `chui-ui`:  which provides a browser-based UI, and\n- `chui-remote`: which connects to and interact with Funnel. By adding\nthe remote to your ClojureScript build you allow it to talk to kaocha-cljs2.\nUsing the UI is optional.\n\n### [Funnel](https://github.com/lambdaisland/funnel)\n\nStand-alone WebSocket message relay. Funnel runs in the background and acts as a\ncommunication hub, providing discoverability (which `chui-remote` processes are\nconnected?), and enabling communication between `chui-remote` and\n`kaocha-cljs2`.\n\n### kaocha-cljs2\n\nA Kaocha test suite type for ClojureScript test suites. Makes the Kaocha\necosystem of tooling available to ClojureScript.\n\nWhen you ask kaocha to run tests of type `:kaocha.type/cljs2`, it\nwould delegate to the implementation of `kaocha-cljs2`, which\nwould connect to funnel and forward the tests to chui-remote (which\nruns in the browser or nodejs).\n\n```\n┌──────────────────────────────┐\n│    KaoCha                    │\n│            ┌─────────────────┤\n│            │   kaocha-cljs2  │\n└────────────┴─────────────────┘\n                      │\n                      ▼\n┌──────────────────────────────┐\n│           Funnel             │\n└──────────────────────────────┘\n                       ▲\n                       │\n                       │\n┌────────────┬────────────────┐\n│   Browser  │chui-remote     │\n│            ├────────────────┤\n│            │chui test-runner│\n│            └────────────────┤\n└─────────────────────────────┘\n```\n\n\n## Installation\n\n### Add `lambdaisland/kaocha-cljs2` as a dependency:\n\n``` clojure\n;; deps.edn\nlambdaisland/kaocha-cljs2 {:mvn/version \"0.2.72\"}\n```\n\n``` clojure\n;; project.clj\n[lambdaisland/kaocha-cljs2 \"0.2.72\"]\n```\n\n### Install Funnel\n\nKaocha-cljs2 relies on Funnel, a websocket message relay, for communicating with\nthe JavaScript runtime.\n\nFollow the instructions for installing and running\n[Funnel](https://github.com/lambdaisland/funnel). We recommend starting Funnel\nin a separate terminal and to leave it running indefinitely. Start it with `-vv`\ninitially so you can see what's going on.\n\n``` shell\n./funnel -vv\nINFO [lambdaisland.funnel] {:started [\"ws://localhost:44220\" \"wss://localhost:44221\"], :line 328}\n```\n\n### Configure your ClojureScript build\n\nAdd `lambdaisland.chui.remote` as a\n[preload](https://cljs.github.io/api/compiler-options/preloads) to your\nClojureScript compiler configuration. This will cause ClojureScript to \"phone\nhome\" when it gets loaded.\n\nWhere this goes exactly depends on the build tool you are using. You are looking\nfor a map containing keys like `:output-to`, `:main`, or `:optimizations`.\n\n``` clojure\n{;; :main foo.bar  ....\n :preloads [lambdaisland.chui.remote]}\n```\n\nHere is an example shadow-cljs configuration:\n```clojure\n{:builds\n {:test-kaocha {:target    :browser-test\n                :runner-ns kaocha.cljs2.shadow-runner\n                :test-dir  \"target/kaocha-test\"\n                :ns-regexp \".*-test$\"\n\n                :devtools {:http-port 1818\n                           :http-root \"target/kaocha-test\"\n\n                           :preloads [lambdaisland.chui.remote]}}}}\n```\n\nNow verify that your ClojureScript build is \"phoning home\". Compile it and run\nit (in a browser, node, ...) and look for a `:connection-opened` message in the\noutput from Funnel.\n\n### Configure your test suite\n\n``` clojure\n;; tests.edn\n#kaocha/v1\n{:tests [{:type :kaocha.type/cljs2}]}\n```\n\nIn principle this is all you need, this will look for any connected\n`chui-remote` clients in the same project directory, so that if you are working\non multiple projects we connect to and run the tests from the right project.\n\nTo do this the current working directory gets injected into the ClojureScript\nbuild, so if you are running the ClojureScript compiler from a separate process\nthen make sure it's running in the same directory where you are running Kaocha.\n\nIf you want Kaocha to kick off the ClojureScript compilation, and to launch a\nJavaScript runtime, then it's recommended you do this with a before hook.\n\n``` clojure\n#kaocha/v1\n{:plugins [:kaocha.plugin/hooks]\n :tests [{:type :kaocha.type/cljs2\n          :kaocha.hooks/before [my.kaocha.hooks/compile-and-launch]}]}\n```\n\nSee the examples directory and [this repository](https://github.com/plexus/cljs-test-example) for specific examples.\n\nWhen kaocha-cljs2 starts executing it will try to find `chui-remote` clients to\ntalk to. If there are none it will wait for a client to connect before\ncontinuing. If there are multiple then it will run tests against all of them.\n\nYou can change this behavior by supplying a `:kaocha.cljs2/clients-hook`. This\nneeds to be fully qualified symbol pointing at a function which takes a test\nsuite map and returns a collection of `:funnel/whoami` maps.\n\n\u003c!-- contributing --\u003e\n## Contributing\n\nEveryone has a right to submit patches to kaocha-cljs2, and thus become a contributor.\n\nContributors MUST\n\n- adhere to the [LambdaIsland Clojure Style Guide](https://nextjournal.com/lambdaisland/clojure-style-guide)\n- write patches that solve a problem. Start by stating the problem, then supply a minimal solution. `*`\n- agree to license their contributions as MPL 2.0.\n- not break the contract with downstream consumers. `**`\n- not break the tests.\n\nContributors SHOULD\n\n- update the CHANGELOG and README.\n- add tests for new functionality.\n\nIf you submit a pull request that adheres to these rules, then it will almost\ncertainly be merged immediately. However some things may require more\nconsideration. If you add new dependencies, or significantly increase the API\nsurface, then we need to decide if these changes are in line with the project's\ngoals. In this case you can start by [writing a pitch](https://nextjournal.com/lambdaisland/pitch-template),\nand collecting feedback on it.\n\n`*` This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.\n\n`**` As long as this project has not seen a public release (i.e. is not on Clojars)\nwe may still consider making breaking changes, if there is consensus that the\nchanges are justified.\n\u003c!-- /contributing --\u003e\n\n\u003c!-- license --\u003e\n## License\n\nCopyright \u0026copy; 2020 Arne Brasseur and Contributors\n\nLicensed under the term of the Mozilla Public License 2.0, see LICENSE.\n\u003c!-- /license --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaisland%2Fkaocha-cljs2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdaisland%2Fkaocha-cljs2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaisland%2Fkaocha-cljs2/lists"}