{"id":13659158,"url":"https://github.com/mpetuska/klip","last_synced_at":"2025-06-14T07:13:28.182Z","repository":{"id":37078284,"uuid":"371776905","full_name":"mpetuska/klip","owner":"mpetuska","description":"Kotlin Multiplatform snapshot ((c|k)lip) manager for tests.","archived":false,"fork":false,"pushed_at":"2024-09-03T22:09:41.000Z","size":1412,"stargazers_count":26,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-08T05:12:17.566Z","etag":null,"topics":["gradle-plugin","kotlin","kotlin-multiplatform","on-hold","testing"],"latest_commit_sha":null,"homepage":"https://mpetuska.github.io/klip","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mpetuska.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mpetuska"]}},"created_at":"2021-05-28T17:41:46.000Z","updated_at":"2024-07-26T09:00:53.000Z","dependencies_parsed_at":"2024-10-23T04:19:16.544Z","dependency_job_id":"39a6665f-1f9e-499a-89b5-cada57112d67","html_url":"https://github.com/mpetuska/klip","commit_stats":{"total_commits":114,"total_committers":5,"mean_commits":22.8,"dds":"0.27192982456140347","last_synced_commit":"2e5724812c2913cf017627d6b754a66adef40210"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/mpetuska/klip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpetuska%2Fklip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpetuska%2Fklip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpetuska%2Fklip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpetuska%2Fklip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mpetuska","download_url":"https://codeload.github.com/mpetuska/klip/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpetuska%2Fklip/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259775266,"owners_count":22909206,"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":["gradle-plugin","kotlin","kotlin-multiplatform","on-hold","testing"],"created_at":"2024-08-02T05:01:05.756Z","updated_at":"2025-06-14T07:13:28.145Z","avatar_url":"https://github.com/mpetuska.png","language":"Kotlin","funding_links":["https://github.com/sponsors/mpetuska"],"categories":["Libraries"],"sub_categories":["🩺 Test"],"readme":"[![Gitpod ready-to-code](https://img.shields.io/badge/gitpod-ready_to_code-blue?logo=gitpod\u0026style=flat-square)](https://gitpod.io/#https://github.com/mpetuska/klip)\n[![Slack chat](https://img.shields.io/badge/kotlinlang-chat-green?logo=slack\u0026style=flat-square)](https://kotlinlang.slack.com/team/UL1A5BA2X)\n[![Dokka docs](https://img.shields.io/badge/docs-dokka-orange?style=flat-square)](http://mpetuska.github.io/klip)\n[![Version gradle-plugin-portal](https://img.shields.io/maven-metadata/v?label=gradle%20plugin%20portal\u0026style=flat-square\u0026logo=gradle\u0026metadataUrl=https%3A%2F%2Fplugins.gradle.org%2Fm2%2Fdev.petuska%2Fklip-gradle-plugin%2Fmaven-metadata.xml)](https://plugins.gradle.org/plugin/dev.petuska.klip)\n[![Version maven-central](https://img.shields.io/maven-central/v/dev.petuska/klip?logo=apache-maven\u0026style=flat-square)](https://mvnrepository.com/artifact/dev.petuska/klip/latest)\n\n# KLIP\n\nKotlin Multiplatform snapshot ((c|k)lip) manager for tests. Automatically generates and asserts against a\npersistent `@kotlinx.serialization.Serializable` representation of the object until you explicitly trigger an update.\nPowered by kotlin compiler plugin to inject relevant keys and paths.\n\n# Support\n\nThe plugin only works on targets using new IR kotlin compiler (which is pretty much all of them since kotlin 1.5 except\nJS which still defaults to legacy compiler).\n\n# Versions\n\nThe current version was built using the following tooling versions and is guaranteed to work with this setup. Given the\nexperimental nature of kotlin compiler plugin API, the plugin powering this library is likely to stop working on\nprojects using newer/older kotlin versions.\n\n* Kotlin: `1.7.0`\n* Gradle: `7.4.2`\n* JDK: `11`\n\n# Targets\n\nBellow is a list of currently supported targets and planned targets:\n\n- [x] android\n- [x] js\n- [x] jvm\n- [x] linuxX64\n- [x] mingwX64\n- [x] macosX64\n- [x] macosArm64\n- [x] iosArm32\n- [x] iosArm64\n- [x] iosSimulatorArm64\n- [x] iosX64\n- [x] watchosX86\n- [x] watchosX64\n- [x] watchosArm64\n- [x] watchosSimulatorArm64\n- [x] watchosArm32\n- [x] tvosArm64\n- [x] tvosSimulatorArm64\n- [x] tvosX64\n\nThere's also a subset of targets that you currently cannot run tests on (and as such making the library redundant).\nThese targets will use a fallback implementation that throws an error on native api access (since those targets will not\nexecute tests) to enable the general library usage in commonMain source set. If you have a valid use-case of the library\nfor these targets, please raise an issue to discuss a real implementation.\n\n- [x] androidNativeArm32\n- [x] androidNativeX86\n- [x] androidNativeArm64\n- [x] androidNativeX64\n- [x] linuxArm32Hfp\n- [x] linuxMips32\n- [x] linuxMipsel32\n- [x] linuxArm64\n- [x] mingwX86\n\n# Usage\n\n1. Apply the plugin and add a runtime dependency.\n2. If you're not using `dev.petuska:klip` marker dependency, you'll also need to add an appropriate ktor-client-engine\n   for each platform\n\n```kotlin\nplugins {\n  kotlin(\"multiplatform\")\n  id(\"dev.petuska.klip\") version \"\u003c\u003cversion\u003e\u003e\"\n\n  kotlin {\n    sourceSets {\n      commonTest {\n        dependencies {\n          implementation(\"dev.petuska:klip\")\n        }\n      }\n    }\n  }\n}\n```\n\n2. (Optional) Configure the plugin extension (shown with default values). For property descriptions.\n   see [Gradle Properties](#gradle-properties)\n\n```kotlin\nklip {\n  enabled.set(true) // Turns the compiler plugin on/off\n  update.set(false) // Whether to overwrite the existing klips while running tests\n  klipAnnotations.set(setOf(\"dev.petuska.klip.core.Klippable\")) // Takes full control of annotations\n  klipAnnotation(\"dev.petuska.klip.core.Klippable\") // Appends the annotation to the default ones\n  scopeAnnotations.set(\n    setOf(\n      // Takes full control of annotations\n      \"kotlin.test.Test\",\n      \"org.junit.Test\",\n      \"org.junit.jupiter.api.Test\",\n      \"org.testng.annotations.Test\",\n      \"io.kotest.core.spec.style.AnnotationSpec.Test\",\n    )\n  )\n  scopeAnnotation(\"kotlin.test.Test\") // Appends the annotation to the default ones\n  scopeFunctions.set(\n    setOf(\n      // Takes full control of functions\n      \"io.kotest.core.spec.style.scopes.FunSpecRootScope.test\",\n      \"io.kotest.core.spec.style.scopes.DescribeSpecContainerScope.it\",\n      \"io.kotest.core.spec.style.scopes.BehaviorSpecWhenContainerScope.Then\",\n      \"io.kotest.core.spec.style.scopes.BehaviorSpecWhenContainerScope.then\",\n      \"io.kotest.core.spec.style.scopes.WordSpecShouldContainerScope.invoke\",\n      \"io.kotest.core.spec.style.scopes.FreeSpecContainerScope.invoke\",\n      \"io.kotest.core.spec.style.scopes.FeatureSpecContainerScope.scenario\",\n      \"io.kotest.core.spec.style.scopes.ExpectSpecContainerScope.expect\",\n    )\n  )\n  scopeFunction(\"io.kotest.core.spec.style.scopes.FunSpecRootContext.test\") // Appends the function to the default ones\n}\n```\n\n3. Use provided klip assertions anywhere under one of the `scopeAnnotations` or `scopeFunctions`.\n\n```kotlin\nclass MyTest {\n  data class DomainObject(val name: String, val value: String?)\n\n  @Test\n  fun test1() = runTest {\n    assertMatchesKlip(DomainObject(\"Dick\", \"Dickens\"))\n    DomainObject(\"John\", \"Doe\").assertKlip()\n  }\n\n  @Test\n  fun test2() = runTest {\n    doAssertions()\n  }\n\n  private suspend fun doAssertions() {\n    assertMatchesKlip(DomainObject(\"Joe\", \"Mama\"))\n    DomainObject(\"Ben\", \"Dover\").assertKlip()\n  }\n}\n```\n\n## Gradle Properties\n\nMost of the DSL configuration options can also be set/overridden via gradle properties\n`./gradlew \u003csome-task\u003e -Pprop.name=propValue`, `gradle.properties` or `~/.gradle/gradle.properties`. Environment\nvariables are also supported, however gradle properties take precedence over them. Bellow is the full list of supported\nproperties:\n\n* `klip.enabled (KLIP_ENABLED)` - toggles the compiler processing on/off.\n* `klip.update (KLIP_UPDATE)` - if true, will override and update all previous klips during test run.\n\n## Basic Flow\n\n1. Run tests as normal and use generated klip assertions such as `assertMatchesKlip(myObject)`\n   or `myObject.assertKlip()`. New klips will always be written to file, whereas existing ones (identified by test class\n   scope and given id) will be read and used for assertions.\n2. When the actual value changes, tests will fail since they do not match previous klip. In such cases inspect the\n   differences and if everything is as expected, re-run test(s) with klip updates enabled. This is done by either\n   passing a gradle prop `./gradlew test -Pklip.update`,\n   setting an environment variable `KLIP_UPDATE=true ./gradlew test`.\n\n# Modules\n\n* `:library:klip-core` - main runtime library\n* `:library:klip-api` - shared api and utility DSLs\n* `:library:klip-assertions` - assertion api\n* `:library:klip-runner` - abstraction over `kotlinx-coroutines-test` to provide truly multiplatform way to run\n  suspending tests\n* `:plugin:klip-gradle-plugin` - gradle plugin to manage kotlin compiler plugins\n* `:plugin:klip-kotlin-plugin` - kotlin compiler plugin for jvm \u0026 js that does the actual work\n* `:plugin:klip-kotlin-plugin-native` - kotlin compiler plugin for native that does the actual work\n* `klip-sandbox` - a playground to test local changes from consumer end\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpetuska%2Fklip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmpetuska%2Fklip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpetuska%2Fklip/lists"}