{"id":16895806,"url":"https://github.com/bnorm/kotlin-power-assert","last_synced_at":"2025-04-04T13:14:01.528Z","repository":{"id":37829768,"uuid":"218812060","full_name":"bnorm/kotlin-power-assert","owner":"bnorm","description":"Kotlin compiler plugin to enable diagrammed function calls in the Kotlin programming language","archived":false,"fork":false,"pushed_at":"2024-06-20T19:36:13.000Z","size":533,"stargazers_count":584,"open_issues_count":1,"forks_count":15,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-28T12:09:37.822Z","etag":null,"topics":["assertions","kotlin","kotlin-ir","testing"],"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/bnorm.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,"publiccode":null,"codemeta":null}},"created_at":"2019-10-31T16:36:02.000Z","updated_at":"2025-03-10T08:41:11.000Z","dependencies_parsed_at":"2023-02-18T19:15:33.927Z","dependency_job_id":"5dc1bdef-79e4-45a3-b66b-3053d5d11023","html_url":"https://github.com/bnorm/kotlin-power-assert","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnorm%2Fkotlin-power-assert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnorm%2Fkotlin-power-assert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnorm%2Fkotlin-power-assert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnorm%2Fkotlin-power-assert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bnorm","download_url":"https://codeload.github.com/bnorm/kotlin-power-assert/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247182420,"owners_count":20897381,"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":["assertions","kotlin","kotlin-ir","testing"],"created_at":"2024-10-13T17:26:21.319Z","updated_at":"2025-04-04T13:14:01.502Z","avatar_url":"https://github.com/bnorm.png","language":"Kotlin","readme":"# kotlin-power-assert\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.bnorm.power/kotlin-power-assert-plugin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.bnorm.power/kotlin-power-assert-plugin)\n\n\u003e [!IMPORTANT]\n\u003e Starting with Kotlin 2.0.0, this compiler plugin has been replaced with an official Kotlin Power-Assert compiler\n\u003e plugin. As such, this compiler plugin is no longer supported, and any usage should be replaced with the official\n\u003e plugin. See https://kotl.in/power-assert for more information on build setup.\n\nKotlin Compiler Plugin which high-jacks Kotlin assert function calls and\ntransforms them similar to [Groovy's Power Assert feature][groovy-power-assert].\nThis plugin uses the IR backend for the Kotlin compiler and supports all\nplatforms: JVM, JS, and Native!\n\n## Example\n\nGiven following code:\n\n```kotlin\nval hello = \"Hello\"\nassert(hello.length == \"World\".substring(1, 4).length)\n```\n\nNormally the assertion message would look like:\n\n```text\njava.lang.AssertionError: Assertion failed\n\tat \u003cstacktrace\u003e\n```\n\nA custom assertion message can be provided:\n\n```kotlin\nval hello = \"Hello\"\nassert(hello.length == \"World\".substring(1, 4).length) { \"Incorrect length\" }\n```\n\nBut this just replaces the message:\n\n```text\njava.lang.AssertionError: Incorrect length\n\tat \u003cstacktrace\u003e\n```\n\nWith `kotlin-power-assert` included, the error message for the previous example\nwill be transformed:\n\n```text\njava.lang.AssertionError: Incorrect length\nassert(hello.length == \"World\".substring(1, 4).length)\n       |     |      |          |               |\n       |     |      |          |               3\n       |     |      |          orl\n       |     |      false\n       |     5\n       Hello\n\tat \u003cstacktrace\u003e\n```\n\nComplex, multi-line, boolean expression are also supported:\n\n```text\nAssertion failed\nassert(\n  (text != null \u0026\u0026 text.toLowerCase() == text) ||\n   |    |\n   |    false\n   null\n      text == \"Hello\"\n      |    |\n      |    false\n      null\n)\n```\n\n## Beyond Assert\n\nThe plugin by default will transform `assert` function calls but can also\ntransform other functions like `require`, `check`, `assertTrue`, and many, many\nmore.\n\nFunctions which can be transformed have specific requirements. A function must\nhave a form which allows taking a `String` or `() -\u003e String` value as the last\nparameter. This can either be as an overload or the original function.\n\nFor example, the `assert` function has 2 definitions:\n* `fun assert(value: Boolean)`\n* `fun assert(value: Boolean, lazyMessage: () -\u003e Any)`\n\nIf the first function definition is called, it will be transformed into calling\nthe second definition with the diagram message supplied as the last parameter.\nIf the second definition is called, it will be transformed into calling the same\nfunction but with the diagram message appended to the last parameter.\n\nThis transformed function call doesn't need to throw an exception either. See\n[Advanced Usage](#advanced-usage) for some examples.\n\n## Gradle Plugin\n\nBuilds of the Gradle plugin are available through the\n[Gradle Plugin Portal][kotlin-power-assert-gradle].\n\n```kotlin\nplugins {\n  kotlin(\"multiplatform\") version \"1.8.20\"\n  id(\"com.bnorm.power.kotlin-power-assert\") version \"0.13.0\"\n}\n```\n\nThe Gradle plugin allows configuring the functions which should be transformed\nwith a list of fully-qualified function names.\n\n```kotlin\n// Kotlin DSL\nconfigure\u003ccom.bnorm.power.PowerAssertGradleExtension\u003e {\n  functions = listOf(\"kotlin.assert\", \"kotlin.test.assertTrue\")\n}\n```\n\n```groovy\n// Groovy\nkotlinPowerAssert {\n  functions = [\"kotlin.assert\", \"kotlin.test.assertTrue\"]\n}\n```\n\nYou can also exclude Gradle source sets from being transformed by the plugin,\nwhere those source sets can be specified by name.\n\n```kotlin\n// Kotlin DSL\nconfigure\u003ccom.bnorm.power.PowerAssertGradleExtension\u003e {\n  excludedSourceSets = listOf(\n    \"commonMain\",\n    \"jvmMain\",\n    \"jsMain\",\n    \"nativeMain\"\n  )\n}\n```\n\n```groovy\n// Groovy\nkotlinPowerAssert {\n  excludedSourceSets = [\n    \"commonMain\",\n    \"jvmMain\",\n    \"jsMain\",\n    \"nativeMain\"\n  ]\n}\n```\n\n## Compatibility\n\nThe Kotlin compiler plugin API is unstable and each new version of Kotlin can\nbring breaking changes to the APIs used by this compiler plugin. Make sure you\nare using the correct version of this plugin for whatever version of Kotlin\nused. Check the table below to find when support for a particular version of\nKotlin was first introduced. If a version of Kotlin or this plugin is not listed\nit can be assumed to maintain compatibility with the next oldest version listed.\n\n| Kotlin Version   | Plugin Version                                           |\n|------------------|----------------------------------------------------------|\n| 1.3.60           | 0.1.0                                                    |\n| 1.3.70           | 0.3.0                                                    |\n| 1.4.0            | 0.4.0                                                    |\n| 1.4.20           | 0.6.0                                                    |\n| 1.4.30           | 0.7.0                                                    |\n| 1.5.0            | 0.8.0                                                    |\n| 1.5.10           | 0.9.0                                                    |\n| 1.5.20           | 0.10.0                                                   |\n| 1.6.0            | 0.11.0                                                   |\n| 1.7.0            | 0.12.0                                                   |\n| 1.8.20           | 0.13.0                                                   |\n| 2.0.0 and beyond | Official support by Kotlin: https://kotl.in/power-assert |\n\n## Kotlin IR\n\nThis plugin supports all IR based compiler backends: JVM, JS, and Native! Only\nKotlin/JS still uses the legacy compiler backend by default, use the following\nto make sure IR is enabled.\n\n```kotlin\ntarget {\n  js(IR) {\n  }\n}\n```\n\n## Advanced Usage\n\n### Function Call Tracing\n\nSimilar to Rust's `dbg!` macro, functions which take arbitrary parameters can\nbe transformed. For example:\n\n```kotlin\nfun \u003cT\u003e dbg(value: T): T = value\n\nfun \u003cT\u003e dbg(value: T, msg: String): T {\n  println(msg)\n  return value\n}\n\nfun main() {\n  println(dbg(1 + 2 + 3))\n}\n```\n\nPrints the following:\n\n```text\ndbg(1 + 2 + 3)\n      |   |\n      |   6\n      3\n6\n```\n\n### Soft Assertion\n\nTo achieve soft assertion, the following template can be implemented:\n\n```kotlin\ntypealias LazyMessage = () -\u003e Any\n\ninterface AssertScope {\n  fun assert(assertion: Boolean, lazyMessage: LazyMessage? = null)\n}\n\nfun \u003cR\u003e assertSoftly(block: AssertScope.() -\u003e R): R = TODO(\"implement\")\n```\n\nYou can then use the template as follows:\n\n```kotlin\nval jane: Person = TODO()\nassertSoftly {\n  assert(jane.firstName == \"Jane\")\n  assert(jane.lastName == \"Doe\")\n}\n```\n\nA working example is [available][soft-assert-example] in this repository in the\nsample directory.\n\n[groovy-power-assert]: https://groovy-lang.org/testing.html#_power_assertions\n[kotlin-power-assert-gradle]: https://plugins.gradle.org/plugin/com.bnorm.power.kotlin-power-assert\n[soft-assert-example]: https://github.com/bnorm/kotlin-power-assert/blob/master/sample/src/commonMain/kotlin/com/bnorm/power/AssertScope.kt\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnorm%2Fkotlin-power-assert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbnorm%2Fkotlin-power-assert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnorm%2Fkotlin-power-assert/lists"}