### Make bin/kaocha Executable

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This command makes the bin/kaocha wrapper script executable, allowing you to run Kaocha from your project's root directory.

```shell
chmod +x bin/kaocha
```

--------------------------------

### Example Kaocha `tests.edn` Configuration

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Demonstrates a comprehensive `tests.edn` configuration file for Kaocha. It specifies test paths, namespace patterns, and optional reporter and plugin configurations for advanced test running scenarios.

```clojure
#kaocha/v1
{:tests [{:id          :unit
          :test-paths  ["test" "src"]
          :ns-patterns [".*"]}]
          ;; :reporter kaocha.report.progress/report
          ;; :plugins [:kaocha.plugin/profiling :kaocha.plugin/notifier]
 }
```

--------------------------------

### Run Kaocha Tests from Command Line

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Provides common command-line examples for running Kaocha tests. This includes basic execution, running in watch mode, enabling fail-fast behavior, and targeting specific test suites.

```shell
bin/kaocha

# Watch for changes
bin/kaocha --watch

# Exit at first failure
bin/kaocha --fail-fast

# Only run the `unit` suite
bin/kaocha unit
```

--------------------------------

### Configure Kaocha with :exec-fn (Clojure CLI)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This deps.edn configuration demonstrates using the :exec-fn option for invoking Kaocha. It sets up the Kaocha dependency and specifies the 'kaocha.runner/exec-fn' and default 'exec-args'.

```clojure
;; deps.edn
{:deps { ,,, }
 :aliases 
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}}}
```

--------------------------------

### Configure Kaocha Dependencies for Babashka

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

Sets up the `bb.edn` file to include Kaocha as a dependency for Babashka. This allows running Kaocha tests directly within the Babashka environment, which can be beneficial for Babashka compatibility checks or faster test execution due to reduced startup times.

```clojure
{:paths ["src" "test"]
 :deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}}

```

--------------------------------

### Create bin/kaocha Wrapper Script (Clojure CLI)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This bash script creates a convenient executable wrapper for invoking Kaocha with the configured 'test' alias from the Clojure CLI. It passes all arguments through to the kaocha.runner.

```shell
#!/usr/bin/env bash

clojure -M:test "$@"
```

--------------------------------

### Advanced bin/kaocha Wrapper Script (Clojure CLI)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

An advanced version of the bin/kaocha wrapper script that loads secrets from 'secrets.env', sets JVM memory options, and specifies a custom configuration file 'test/tests.edn'.

```shell
#!/usr/bin/env bash

. secrets.env
clojure -J-Xmx512m -M:dev:test --config-file test/tests.edn "$@"
```

--------------------------------

### Create Kaocha Binstub for Boot

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Provides a `bin/kaocha` binstub for Boot projects. This script executes the `boot kaocha` command, simplifying the invocation of Kaocha tests within the Boot environment.

```shell
mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'boot kaocha "$@"' >> bin/kaocha
chmod +x bin/kaocha
```

--------------------------------

### Configure Kaocha with :exec-fn and Custom Args (Clojure CLI)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This deps.edn configuration shows how to set up a specific alias ('watch-test') using :exec-fn, including custom 'exec-args' for options like watch mode, skipping tests, and fail-fast behavior.

```clojure
;; deps.edn
{:deps { ,,, }
 :aliases 
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}
 :watch-test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {:watch? true
	 :skip-meta :slow
	 :fail-fast? true }}}}
```

--------------------------------

### Progress Reporter Output Example

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

This example displays the typical output format of the Kaocha progress reporter. It includes progress bars for each test suite, indicating completion percentage and the number of test vars, and turns red on failure.

```clojure
integration:   100% [==================================================] 1/1
       unit:   100% [==================================================] 18/18

19 test vars, 55 assertions, 0 failures.
```

--------------------------------

### Create Kaocha Binstub for Babashka

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Creates a `bin/kaocha-bb` binstub script for Babashka projects. This script uses `bb -m kaocha.runner/-main` to execute Kaocha tests, providing a convenient way to run tests with Babashka.

```shell
#!/usr/bin/env bash
bb -m kaocha.runner/-main  $@
```

--------------------------------

### Create bin/kaocha Wrapper Script (Leiningen)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This bash script provides a unified way to invoke Kaocha, regardless of the underlying build tool. When used with Leiningen, it calls the 'lein kaocha' alias, passing all arguments through.

```shell
#!/usr/bin/env bash

lein kaocha "$@"
```

--------------------------------

### Configure Boot for Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Integrates Kaocha into a Boot project by adding the Kaocha dependency and importing the Kaocha task in `build.boot`. This allows using Kaocha's testing capabilities within the Boot build process.

```clojure
;; build.boot
(set-env! :source-paths #{"src"}
          :dependencies '[[lambdaisland/kaocha-boot "..."]])

(require '[kaocha.boot-task :refer [kaocha]])
```

--------------------------------

### Create Kaocha Binstub for Clojure CLI

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Creates an executable binstub script named `bin/kaocha` that allows running Kaocha tests using the configured Clojure CLI alias. This simplifies test execution from the command line.

```shell
mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'clojure -M:test "$@"' >> bin/kaocha
chmod +x bin/kaocha
```

--------------------------------

### Configure Kaocha with Leiningen

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This project.clj configuration adds Kaocha to the ':dev' profile and defines a 'kaocha' alias to run the Kaocha test runner. This is the standard way to integrate Kaocha with Leiningen projects.

```clojure
(defproject my-proj "0.1.0"
  :dependencies [,,,]
  :profiles {:dev {:dependencies [,,, [lambdaisland/kaocha "1.91.1392"]]}}
  :aliases {"kaocha" ["run" "-m" "kaocha.runner"]})
```

--------------------------------

### ClojureScript Classpath Configuration Example

Source: https://github.com/lambdaisland/kaocha/blob/main/notes.org

Shows how to manually add a test directory to the classpath for ClojureScript projects using Kaocha.

```clojure
;; Manually add test dir to classpath
;; Example for build.boot or tools.deps
```

--------------------------------

### Example Kaocha Configuration Output (Core Settings)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/print_config.md

An example snippet of the EDN output generated by Kaocha's `--print-config` command, showcasing core configuration settings. This includes randomization status, reporter, colorization, and fail-fast behavior.

```clojure
{
 :kaocha.plugin.randomize/randomize? false,
 :kaocha/reporter [kaocha.report/dots],
 :kaocha/color? false,
 :kaocha/fail-fast? false
}
```

--------------------------------

### Invoke Kaocha with Clojure CLI (deps.edn)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This snippet shows how to invoke Kaocha directly from the command line using the Clojure CLI by specifying the dependency in the command. It's a quick way to run Kaocha without modifying project files.

```shell
clojure -Sdeps '{:deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}}' -m kaocha.runner --test-help
```

--------------------------------

### Create Kaocha Binstub for Leiningen

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Generates a `bin/kaocha` binstub for Leiningen projects. This script executes the Leiningen Kaocha alias, making it convenient to run tests from the project's root directory.

```shell
mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'lein kaocha "$@"' >> bin/kaocha
chmod +x bin/kaocha
```

--------------------------------

### Configure Kaocha with Clojure CLI (deps.edn)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

This code configures a 'test' alias in deps.edn to include the Kaocha dependency and set the main namespace for running tests. This is the recommended approach for using Kaocha with the Clojure CLI.

```clojure
;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:main-opts ["-m" "kaocha.runner"]
         :extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}}}}
```

--------------------------------

### Configure Babashka for Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Integrates Kaocha with Babashka by specifying the dependency in `bb.edn`. This enables running Kaocha tests within the Babashka environment, leveraging its fast startup times.

```clojure
{:paths ["src" "test"]
 :deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}}
```

--------------------------------

### Create Babashka Kaocha Runner Script

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

Provides a shell script that acts as a command-line interface for running Kaocha tests using Babashka. This script utilizes `bb -m kaocha.runner/-main` to invoke the Kaocha runner, accepting any additional arguments passed to the script.

```shell
#!/usr/bin/env bash
bb -m kaocha.runner/-main  $@

```

--------------------------------

### Full Kaocha Test Configuration Example

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

An example of a complete Kaocha test configuration in EDN format. It specifies test suites, failure behavior, color output, reporters, and various plugins with their specific settings. This serves as a detailed reference for all possible configuration options.

```clojure
{
 :kaocha/tests                       [ {:kaocha.testable/type :kaocha.type/clojure.test
   :kaocha.testable/id   :unit
   :kaocha/ns-patterns   ["-test$"]
   :kaocha/source-paths  ["src"]
   :kaocha/test-paths    ["test/unit"]}]
 :kaocha/fail-fast?                  false
 :kaocha/color?                      true
 :kaocha/reporter                    [kaocha.report/dots]
 :kaocha/plugins                     [:kaocha.plugin/randomize
                                      :kaocha.plugin/filter
                                      :kaocha.plugin/capture-output
                                      :kaocha.plugin/profiling]
 :kaocha.plugin.randomize/seed       950716166
 :kaocha.plugin.randomize/randomize? true
 :kaocha.plugin.profiling/count      3
 :kaocha.plugin.profiling/profiling? true
}
```

--------------------------------

### Configure Kaocha Leiningen Profile and Alias

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/02_installing.md

Defines a separate `:kaocha` profile in `project.clj` to include Kaocha dependencies and creates a `kaocha` alias to activate this profile and run the Kaocha test runner. This allows for conditional usage of Kaocha without cluttering the default `:dev` profile.

```clojure
(defproject my-proj "0.1.0"
  :dependencies [,,,]
  :profiles {:kaocha {:dependencies [[lambdaisland/kaocha "1.91.1392"]]}}
  :aliases {"kaocha" ["with-profile" "+kaocha" "run" "-m" "kaocha.runner"]})
```

--------------------------------

### Example Kaocha Configuration Output (Test Definitions)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/print_config.md

An example snippet of the EDN output from Kaocha's `--print-config` command, detailing the test definition settings. This includes the type of tests, their IDs, namespace patterns, source paths, test paths, and skip metadata.

```clojure
{
 :kaocha/tests
 [
  {:kaocha.testable/type :kaocha.type/clojure.test,
   :kaocha.testable/id :unit,
   :kaocha/ns-patterns ["-test$"],
   :kaocha/source-paths ["src"],
   :kaocha/test-paths ["test"],
   :kaocha.filter/skip-meta [:kaocha/skip]}
 ]
}
```

--------------------------------

### Kaocha Configuration Example

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

This snippet shows a basic Kaocha configuration using the `#kaocha/v1` reader macro. It defines a test suite with source and test paths, namespace patterns, and configures plugins for printing invocations and profiling. It also sets options for colored output, file watching, output capturing, and specifies the documentation reporter.

```clojure
#kaocha/v1
{:tests [{;; Every suite must have an :id
          :id :unit

          ;; Directories containing files under test. This is used to
          ;; watch for changes, and when doing code coverage analysis
          ;; through Cloverage. These directories are *not* automatically
          ;; added to the classpath.
          :source-paths ["src"]

          ;; Directories containing tests. These will automatically be
          ;; added to the classpath when running this suite.
          :test-paths ["test"]

          ;; Regex strings to determine whether a namespace contains
          ;; tests. (use strings, not actual regexes, due to a limitation of Aero)
          :ns-patterns ["-test$"]}]

 :plugins [:kaocha.plugin/print-invocations
           :kaocha.plugin/profiling]

 ;; Colorize output (use ANSI escape sequences).
 :color?      true

 ;; Watch the file system for changes and re-run. You can change this here to be
 ;; on by default, then disable it when necessary with `--no-watch`.
 :watch?      false

 ;; Specifiy the reporter function that generates output. Must be a namespaced
 ;; symbol, or a vector of symbols. The symbols must refer to vars, which Kaocha
 ;; will make sure are loaded. When providing a vector of symbols, or pointing
 ;; at a var containing a vector, then kaocha will call all referenced functions
 ;; for reporting.
 :reporter    kaocha.report/documentation

 ;; Enable/disable output capturing.
 :capture-output? true

 ;; Plugin specific configuration. Show the 10 slowest tests of each type, rather
 ;; than only 3.
 :kaocha.plugin.profiling/count 10}
```

--------------------------------

### Clojure Skip/Focus Metadata Example

Source: https://github.com/lambdaisland/kaocha/blob/main/notes.org

Illustrates how to use metadata like `:skip-meta`, `:exclude-meta`, and `:focus-meta` to control test execution in Kaocha.

```clojure
(defn my-test []
  (println "This test runs")
  (is (= 1 1))) 

(defn skipped-test []
  #meta {:kaocha/skip true}
  (println "This test is skipped")
  (is (= 1 1)))
```

--------------------------------

### Configure Kaocha Test Suites with EDN

Source: https://context7.com/lambdaisland/kaocha/llms.txt

Set up Kaocha's test configuration using EDN files. This example demonstrates minimal configuration, defining multiple test suites with custom paths and namespaces, and incorporating profile-based settings for different environments.

```clojure
;; tests.edn - Minimal configuration
#kaocha/v1 {}

;; tests.edn - Multiple test suites with custom paths
#kaocha/v1
{:tests [{:id :unit
          :test-paths ["test/unit"]
          :source-paths ["src"]}
         {:id :integration
          :test-paths ["test/integration"]
          :ns-patterns [ ".*-integration-test$"]}]
 :plugins [:kaocha.plugin/profiling
           :kaocha.plugin/notifier]
 :reporter kaocha.report/documentation
 :color? true
 :fail-fast? false
 :kaocha.plugin.profiling/count 10}

;; tests.edn - Profile-based configuration
#kaocha/v1
{:reporter #profile {:default kaocha.report.progress/report
                     :ci kaocha.report/documentation}
 :color? #profile {:default true :ci false}
 :plugins [:profiling :capture-output]}
```

--------------------------------

### Specify Profile with --profile CLI Option (Clojure)

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/profile.md

Demonstrates how to use the `--profile` flag in the Kaocha CLI to select a specific configuration profile from `tests.edn`. The example shows a Clojure setup where different reporters are used for CI environments versus default local runs. Assumes a `tests.edn` file and a Clojure test file are present.

```clojure
#kaocha/v1
{:reporter #profile {:ci kaocha.report/documentation
                     :default kaocha.report/dots}}
```

```clojure
(ns my.project.my-test
  (:require [clojure.test :refer :all]))

(deftest test-1
  (is true))
```

```bash
bin/kaocha --profile :ci
```

```text
---
--- unit (clojure.test) ---
my.project.my-test
  test-1
```

--------------------------------

### Setup Kaocha with deps.edn using :main-opts

Source: https://context7.com/lambdaisland/kaocha/llms.txt

Configures Kaocha aliases in deps.edn for running tests, watch mode, and CI using `:main-opts`. This approach is suitable for standard command-line test execution.

```clojure
;; deps.edn
{:paths ["src" "resources"]
 :deps {org.clojure/clojure {:mvn/version "1.11.1"}}

 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :main-opts ["-m" "kaocha.runner"]} ; Run tests

  :test-watch {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
               :main-opts ["-m" "kaocha.runner" "--watch"]} ; Run tests with watch mode

  :test-ci {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
            :main-opts ["-m" "kaocha.runner"
                        "--reporter" "documentation"
                        "--no-color"]}}}
```

--------------------------------

### Configure :kaocha.type/clojure.test Suite Options

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

Illustrates how to configure options for the `:kaocha.type/clojure.test` suite type, such as namespace patterns, source paths, and test paths. This example explicitly sets these values.

```clojure
{:kaocha.testable/type :kaocha.type/clojure.test,
 :kaocha.testable/id   :my-suite,
 :kaocha/ns-patterns   ["my-tests$" "custom-utils"],
 :kaocha/source-paths  ["lib"],
 :kaocha/test-paths    ["tests/my-suite"]}
```

--------------------------------

### Define Kaocha Plugin using defplugin macro

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/09_extending.md

This example showcases the `defplugin` macro for creating Kaocha plugins, which simplifies boilerplate code. It illustrates how to implement various hooks like `cli-options`, `config`, `pre-load`, `post-load`, `pre-run`, `post-load-test`, `pre-test`, `post-test`, `post-run`, `wrap-run`, `pre-report`, `main`, and `post-summary`. Each hook typically returns its first argument, possibly modified.

```clojure
(ns my.kaocha.plugin
  (:require [kaocha.plugin :as p]))

(p/defplugin my.kaocha/plugin
  ;; Install extra CLI options and flags.
  (cli-options [opts]
    (conj opts [nil "--my-plugin-option" "Does something plugin specific."]))

  ;; Alter the configuration. Useful for setting default values and processing cli-options.
  (config [config]
    (if (:my-plugin-option (:kaocha/cli-options config))
      (assoc config ::some-flag true)
      config))

  ;; Runs before the load step
  (pre-load [config]
    config)

  ;; Runs after the load step
  (post-load [test-plan]
    test-plan)

  ;; Runs before the run step
  (pre-run [test-plan]
    test-plan)

  ;; Runs before each individual test gets loaded, gets passed the testable
  (pre-load-test [testable config]
    testable)

  ;; Runs after each individual test has been loaded, gets passed the testable
  (post-load-test [testable config]
    testable)

  ;; Runs before each individual test
  (pre-test [test test-plan]
    test)

  ;; Runs after each individual test
  (post-test [test test-plan]
    test)

  ;; Runs after the run step
  (post-run [result]
    result)

  ;; Allows "wrapping" the run function
  (wrap-run [run test-plan]
    run)

  ;; Runs before the reporter
  (pre-report [event]
    event)

  ;; Runs right before kaocha.runner calls kaocha.api/run. This is for plugins
  ;; that optionally do something else besides running tests, like printing
  ;; informational messages and then exiting. For this throw+ a
  ;; {:kaocha/early-exit}.
  (main [config]
    (if (:do-other-thing (:kaocha/cli-options config))
      (do
        (... do other thing ...)
        (throw+ {:kaocha/early-exit 0}))
      config))

  ;; Gets called after the run is finished and the summary has been printed/reported.
  ;; Gets passed the test result map (test plan with results).
  (post-summary [test-result]
    ))
```

--------------------------------

### Configure Clojure CLI (tools.deps) with exec-fn for Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Sets up Kaocha using the `:exec-fn` option in `deps.edn` for the Clojure CLI. This alternative method allows invoking Kaocha directly via `clojure -X` and passing configuration arguments through `:exec-args`.

```clojure
;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}}}
```

--------------------------------

### Configure Clojure CLI (tools.deps) for Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Adds Kaocha as a dependency using an alias in `deps.edn`. It specifies the version and configures a main option to run the Kaocha runner. This setup is for the Clojure CLI `tools.deps` build tool.

```clojure
;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :main-opts ["-m" "kaocha.runner"]}}}
```

--------------------------------

### Invoking Plugin Configuration Hook

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/09_extending.md

An example of how to manually invoke the `config` hook of a plugin within the REPL to inspect its behavior.

```clojure
(my.kaocha.plugin/plugin-config-hook (kaocha.repl/config))
;; => ???

```

--------------------------------

### Setup Kaocha with deps.edn using :exec-fn

Source: https://context7.com/lambdaisland/kaocha/llms.txt

Configures Kaocha aliases in deps.edn for running tests and watch mode using `:exec-fn`. This method allows for more programmatic control and is often used for interactive REPL-driven development or specific script execution.

```clojure
;; deps.edn
{:aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}} ; Run tests

  :test-watch {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
               :exec-fn kaocha.runner/exec-fn
               :exec-args {:watch? true
                           :fail-fast? true}}}} ; Run tests with watch and fail-fast
```

--------------------------------

### Configure Clojure CLI (tools.deps) with exec-fn and custom args for Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/README.md

Extends the `:exec-fn` configuration in `deps.edn` to include a specific alias (`:watch-test`) with custom execution arguments. This allows pre-defined configurations for tasks like watching for changes and failing fast.

```clojure
;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}} 
 :watch-test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {:watch? true
	 :skip-meta :slow
	 :fail-fast? true }}}}
```

--------------------------------

### Run Kaocha with a shorthand reporter name

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/reporter.md

This command shows how to use the shorthand notation for specifying a reporter in Kaocha. When a reporter is part of the `kaocha.report` namespace, its namespace prefix can be omitted. This example uses the `documentation` reporter, and the command expects an exit code of 2, indicating test failures.

```bash
bin/kaocha --reporter documentation
```

--------------------------------

### Define a Clojure test file for reporter examples

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/reporter.md

This Clojure code defines a sample test file named 'test/my/project/reporter_test.clj'. It includes three test cases: one that fails, one that throws an exception (error), and one that passes. This file serves as the basis for demonstrating different reporter functionalities.

```clojure
 (ns my.project.reporter-test
  (:require [clojure.test :refer :all]))

(deftest test-1
  (is (= 1 0)))

(deftest test-2
  (is true)
  (is (throw (Exception. "")))
  (is true))

(deftest test-3
  (is true))

```

--------------------------------

### Define Tests with Version Constraints in Clojure

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/plugins/version_filter.md

This example demonstrates how to define Clojure tests with version-specific metadata. It showcases tests that are designed to be skipped based on Java version and tests that will run based on Clojure version constraints.

```clojure
(ns my.sample-test
  (:require [clojure.test :refer :all]))

(deftest ^{:max-java-version "1.7"} this-test-gets-skipped
  (is false))

(deftest ^{:min-clojure-version "1.6.0"} this-test-runs
  (is true))
```

--------------------------------

### Skeleton Example of a Custom Kaocha Test Suite Type

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/09_extending.md

This Clojure code provides a skeleton for implementing a custom Kaocha test suite type. It demonstrates the necessary namespace requirements and the implementation of the `-load` and `-run` multimethods for handling test loading and execution.

```clojure
(ns kaocha.type.clojure.test
  (:require [clojure.spec.alpha :as s]
            [kaocha.testable :as testable]
            [kaocha.load :as load]
            [clojure.test :as t]))

(defmethod testable/-load :kaocha.type/clojure.test [testable]
  (assoc :kaocha.testable test-plan/tests (load-tests ...)))

(defmethod testable/-run :kaocha.type/clojure.test [testable test-plan]
  (t/do-report {:type :begin-test-suite})
  (let [results (testable/run-testables (:kaocha.test-plan/tests testable) test-plan)
        testable (-> testable
                     (dissoc :kaocha.test-plan/tests)
                     (assoc :kaocha.result/tests results))]
    (t/do-report {:type :end-test-suite
                  :kaocha/testable testable})
    testable))

(s/def :kaocha.type/clojure.test (s/keys :req [:kaocha/source-paths
                                               :kaocha/test-paths
                                               :kaocha/ns-patterns]))


(hierarchy/derive! :kaocha.type/clojure.test :kaocha.testable.type/suite)
```

--------------------------------

### Clojure: Declare suite-level pre-load-test hook

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/10_hooks.md

This example demonstrates how to declare a `pre-load-test` hook directly on a test suite within the Kaocha configuration. This allows for suite-specific setup before test loading.

```clojure
#kaocha/v1
{:tests [{:kaocha.hooks/pre-load-test [...]}]}
```

--------------------------------

### Plugin Configuration Best Practice

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/09_extending.md

Shows the recommended pattern for handling plugin configuration, prioritizing CLI options over configuration file settings.

```clojure
;; In config hook:
(if-let [cli-opts (:kaocha/cli-options config)]
  (update config :some-plugin-setting (fnil conj []) cli-opts)
  config)

```

--------------------------------

### Enable Kaocha Plugin from Command Line

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

Demonstrates enabling a Kaocha plugin directly from the command line interface. This is useful for quick testing or when modifying the configuration file is not desired. The namespace can sometimes be omitted for plugins in the 'kaocha.plugin' namespace.

```shell
bin/kaocha --plugin kaocha.plugin/profiling
```

```shell
bin/kaocha --plugin profiling
```

--------------------------------

### Enable Kaocha Reporter from Command Line

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

Illustrates how to specify a Kaocha reporter using the command line interface. This allows for easy switching between different output formats without modifying configuration files.

```shell
bin/kaocha --reporter kaocha.report/dots
```

--------------------------------

### Implement Test-Suite Specific Hooks with Clojure

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/plugins/hooks_plugin.md

This example shows how to implement test-suite specific hooks in Kaocha using the Hooks plugin. Hooks like 'before' and 'after' are defined within a test suite configuration in 'tests.edn'. The actual hook functions are implemented in a separate Clojure namespace. This enables targeted execution of functions before and after a specific test suite runs, useful for setup and teardown operations.

```clojure
#kaocha/v1
{:plugins [:kaocha.plugin/hooks]
 :tests [{:id :unit
          :kaocha.hooks/before [my.kaocha.hooks/sample-before-hook]
          :kaocha.hooks/after  [my.kaocha.hooks/sample-after-hook]}]}
```

```clojure
(ns my.kaocha.hooks)

(defn sample-before-hook [suite test-plan]
  (println "before suite:" (:kaocha.testable/id suite))
  suite)

(defn sample-after-hook [suite test-plan]
  (println "after suite:" (:kaocha.testable/id suite))
  suite)
```

```clojure
(ns sample-test
  (:require [clojure.test :refer :all]))

(deftest stdout-pass-test
  (println "You peng zi yuan fang lai")
  (is (= :same :same)))
```

--------------------------------

### Kaocha Plugin Definition with Hooks

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/09_extending.md

Demonstrates defining a Kaocha plugin with specific hooks for command-line options, configuration, and pre-load actions. It also shows the generated hook functions and the method registration.

```clojure
(defplugin my.kaocha/plugin
  "Docstring"
  (cli-options [opts] opts)
  (config [config] config)
  (pre-load [config] config))

;; This defines
(defn plugin-cli-options-hook [opts] opts)
(defn plugin-config-hook [config] config)
(defn plugin-pre-load-hook [config] config)

(def plugin-hooks
  {:kaocha.plugin/id :my.kaocha/plugin
   :kaocha.plugin/description "Docstring"
   :kaocha.hooks/cli-options plugin-cli-options-hook
   :kaocha.hooks/config plugin-config-hook
   :kaocha.hooks/pre-load plugin-pre-load-hook})

(defmethod kaocha.plugin/-register :my.kaocha/plugin [chain]
  (conj chain plugin-hooks))

```

--------------------------------

### Focus Tests via Command Line using :xxx Metadata

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/filtering/focus_meta.md

Demonstrates running Kaocha tests using the `--focus-meta` command-line flag to target tests with a specific metadata key (:xxx). The output shows only the tests associated with that metadata.

```bash
bin/kaocha --focus-meta :xxx --reporter documentation
```

--------------------------------

### Configure Preloads Plugin in Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/08_plugins.md

Configures the preloads plugin in Kaocha to load specified Clojure namespaces before running tests. This is useful for loading specs or installing instrumentation.

```clojure
{:plugins [:preloads]
 :kaocha.plugin.preloads/ns-names [my.acme.specs]}
```

--------------------------------

### Define Clojure Tests

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/filtering/focusing.md

Defines two test cases within a Clojure namespace using the standard clojure.test library. These tests serve as examples for demonstrating filtering capabilities.

```clojure
(ns my.project.sample-test
  (:require [clojure.test :refer :all]))

(deftest some-test
  (is (= 1 1)))

(deftest other-test
  (is (= 2 2)))
```

```clojure
(ns my.project.other-sample-test
  (:require [clojure.test :refer :all]))

(deftest other-test
  (is (= 1 2)))
```

--------------------------------

### Define Test Case in tests/bbb/bbb_test.clj

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/suite_names.md

A simple test case for the ':bbb' test suite. This file serves as an example of a test file for a different suite, illustrating how Kaocha differentiates between them.

```clojure
(ns bbb-test (:require [clojure.test :refer :all]))
(deftest bbb-test (is true))
```

--------------------------------

### Focus Tests via Command Line using :yyy Metadata

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/filtering/focus_meta.md

Illustrates using the `--focus-meta` command-line flag to execute Kaocha tests tagged with the :yyy metadata key. The expected output lists only the relevant tests.

```bash
bin/kaocha --focus-meta :yyy --reporter documentation
```

--------------------------------

### Defining Custom Test Event Types in Clojure

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/09_extending.md

This example illustrates how to define custom event types for a specific test type (e.g., 'foo-test') and derive them from Kaocha's common event types like `:kaocha/begin-suite`, `:kaocha/fail-type`, and `:kaocha/known-key`.

```clojure
:foo-test/begin-suite   :kaocha/begin-suite
:foo-test/begin-ns      :kaocha/begin-group

:foo-test/begin-test    :kaocha/begin-test
:foo-test/assert-failed :kaocha/fail-type
:foo-test/precondition-failed :kaocha/fail-type
:foo-test/end-test      :kaocha/end-test

:foo-test/begin-test    :kaocha/begin-test
:pass                   :kaocha/known-key
:foo-test/end-test      :kaocha/end-test

:foo-test/end-ns        :kaocha/end-group
:foo-test/end-suite     :kaocha/end-suite
```

--------------------------------

### Focusing on a Specific Test Var by Fully Qualified Name

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/06_focusing_and_skipping.md

This shell command demonstrates how to focus on a single test var using its fully qualified name. The example targets the 'foo-test' var within the 'com.my.project-test' namespace.

```shell
bin/kaocha --focus com.my.project-test/foo-test
```

--------------------------------

### Run Kaocha with a fully qualified reporter function

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/command_line/reporter.md

This command demonstrates how to run Kaocha tests using a specific reporter function specified by its fully qualified name. The `kaocha.report/documentation` reporter is used here to format the test output, showing the status of each test case.

```bash
bin/kaocha --reporter kaocha.report/documentation
```

--------------------------------

### Orchestra Spec Failure Output

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/plugins/orchestra_plugin.md

This is an example of the output generated when a function's return value fails to conform to its spec, as instrumented by the Orchestra plugin. It clearly indicates the test case, the function call, the non-conforming value, and the expected spec.

```nil
ERROR in orchestra-test/spec-fail-test (orchestra_test.clj:11)
Just testing simple-fn
Call to orchestra-test/simple-fn did not conform to spec.
orchestra_test.clj:11

-- Spec failed --------------------

Return value

  "x"

should satisfy

  int?

-- Relevant specs -------

:simple/int:
  clojure.core/int?

-------------------------
Detected 1 error
```

--------------------------------

### Kaocha Configuration with #meta-merge and #include

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

Illustrates an advanced Kaocha configuration strategy using #kaocha/v1, #meta-merge, and #include. This allows for a base configuration to be extended by user-specific settings in 'tests.user.edn', facilitating customization of test suites and plugins.

```clojure
#kaocha/v1
#meta-merge [{:tests [{:id         :unit
              :test-paths ["test/unit"]}
             {:id         :features
              :test-paths ["test/features"]}]
             :kaocha/plugins [:kaocha.plugin.some.required/plugin
                              ,,,
                              ]
             }

        #include "tests.user.edn"]
```

--------------------------------

### Example Test Case for Notifier Plugin

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/plugins/notifier_plugin.md

A simple Clojure test case designed to fail, demonstrating the 'Failing' notification output from the Kaocha Notifier plugin. This test uses `clojure.test` and includes a basic assertion that is expected to fail.

```clojure
(ns sample-test
  (:require [clojure.test :refer :all]))

(deftest simple-fail-test
  (is (= :same :not-same)))
```

--------------------------------

### Minimal Kaocha Configuration with #kaocha/v1

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/03_configuration.md

Demonstrates the simplest possible Kaocha configuration using the #kaocha/v1 tagged reader literal. This configuration assumes default settings for source paths, test paths, and namespace patterns, suitable for projects with a standard structure.

```clojure
#kaocha/v1 {}
```

--------------------------------

### Define and Add a Pre-Load Hook in Kaocha

Source: https://github.com/lambdaisland/kaocha/blob/main/doc/10_hooks.md

This demonstrates how to add a 'pre-load' hook to Kaocha. The hook function `myproject.kaocha-hooks/start-load-message` is specified in the configuration and will be executed before Kaocha starts loading tests. The hook function receives the configuration and is expected to return it, potentially modified.

```clojure
#kaocha/v1
{:plugins [:hooks]
 :kaocha.hooks/pre-load [myproject.kaocha-hooks/start-load-message]}
```

```clojure
(ns myproject.kaocha-hooks)

(defn start-load-message [config]
  (println "About to start loading!")
  config)
```

--------------------------------

### Run Kaocha Tests from Command Line

Source: https://context7.com/lambdaisland/kaocha/llms.txt

Execute Kaocha tests using various command-line options. This covers basic test execution, running specific suites, enabling watch mode, fail-fast behavior, focusing or skipping tests by ID or metadata, and customizing configuration and reporters.

```bash
# Run all test suites
bin/kaocha

# Run specific test suite
bin/kaocha unit

# Watch mode - rerun tests on file changes
bin/kaocha --watch

# Fail fast - stop at first failure
bin/kaocha --fail-fast

# Focus on specific tests
bin/kaocha --focus my.app.foo-test/bar-test

# Skip tests by ID
bin/kaocha --skip :integration

# Focus on tests with metadata
bin/kaocha --focus-meta :quick

# Skip tests with metadata
bin/kaocha --skip-meta :slow

# Use custom config file
bin/kaocha --config-file tests_ci.edn

# Print resolved configuration
bin/kaocha --print-config

# Print test plan
bin/kaocha --print-test-plan

# Change reporter
bin/kaocha --reporter kaocha.report/documentation

# Add plugin
bin/kaocha --plugin profiling

# Use specific profile
bin/kaocha --profile :ci

# Combine multiple options
bin/kaocha unit --watch --fail-fast --focus-meta :wip
```