{"id":13537075,"url":"https://github.com/willowtreeapps/assertk","last_synced_at":"2026-01-11T16:57:59.248Z","repository":{"id":39419717,"uuid":"88210079","full_name":"willowtreeapps/assertk","owner":"willowtreeapps","description":"assertions for kotlin inspired by assertj","archived":false,"fork":false,"pushed_at":"2024-12-03T21:48:15.000Z","size":15804,"stargazers_count":799,"open_issues_count":61,"forks_count":89,"subscribers_count":127,"default_branch":"main","last_synced_at":"2025-05-07T08:50:49.858Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willowtreeapps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"Contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","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}},"created_at":"2017-04-13T22:02:40.000Z","updated_at":"2025-05-06T07:42:34.000Z","dependencies_parsed_at":"2024-03-25T18:08:17.145Z","dependency_job_id":"d2ab2670-3a77-4a4b-95e1-39ec0d187d53","html_url":"https://github.com/willowtreeapps/assertk","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willowtreeapps%2Fassertk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willowtreeapps%2Fassertk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willowtreeapps%2Fassertk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willowtreeapps%2Fassertk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willowtreeapps","download_url":"https://codeload.github.com/willowtreeapps/assertk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198514,"owners_count":22030965,"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-08-01T09:00:54.640Z","updated_at":"2025-05-14T18:06:37.308Z","avatar_url":"https://github.com/willowtreeapps.png","language":"Kotlin","readme":"# assertk\n\n[![CircleCI](https://circleci.com/gh/willowtreeapps/assertk.svg?style=svg)](https://circleci.com/gh/willowtreeapps/assertk)\n[![Maven Central](https://img.shields.io/maven-central/v/com.willowtreeapps.assertk/assertk.svg)](https://search.maven.org/search?q=g:com.willowtreeapps.assertk)\n[![Sonatype Snapshot](https://img.shields.io/nexus/s/https/oss.sonatype.org/com.willowtreeapps.assertk/assertk.svg)](https://oss.sonatype.org/content/repositories/snapshots/com/willowtreeapps/assertk/)\n\nassertk is a fluent assertion library for Kotlin inspired by [AssertJ](https://github.com/assertj/assertj-core).\n\n- [Documentation](https://willowtreeapps.github.io/assertk/assertk/assertk.assertions/index.html)\n\n## Why another assertion library?\n\nYou might be asking, \"If AssertJ already exists, why create another library?\". It's true, assertk is very similar to\nAssertJ. But assertk is written in Kotlin so it has one major advantage: extension methods. This makes adding your own\nassertion methods far simpler.\n\nSee [Custom Assertions](#custom-assertions) below to find out how to do this.\n\n## Setup\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    testImplementation(\"com.willowtreeapps.assertk:assertk:0.28.1\")\n}\n```\n\nassertk has full multiplatform support and it can be used in jvm, js, or native projects. For example to set it up using\nthe multiplatform plugin:\n\n```kotlin\nplugins {\n    kotlin(\"multiplatform\")\n}\n\nkotlin {\n    sourceSets {\n        val commonTest by getting {\n            dependencies {\n                implementation(\"com.willowtreeapps.assertk:assertk:0.28.1\")\n            }\n        }\n    }\n}\n```\n\n## Usage\n\nSimple usage is to wrap the value or property you are testing in `assertThat()` and call assertion methods on the\nresult.\n\n```kotlin\nimport assertk.assertThat\nimport assertk.assertions.*\n\nclass PersonTest {\n    val person = Person(name = \"Bob\", age = 18)\n\n    @Test\n    fun testName() {\n        assertThat(person.name).isEqualTo(\"Alice\")\n        // -\u003e expected:\u003c[\"Alice\"]\u003e but was:\u003c[\"Bob\"]\u003e\n    }\n\n    @Test\n    fun testAge() {\n        assertThat(person.age, \"age\").isGreaterThan(20)\n        // -\u003e expected [age] to be greater than:\u003c20\u003e but was:\u003c18\u003e\n    }\n\n    @Test\n    fun testNameProperty() {\n        assertThat(person::name).isEqualTo(\"Alice\")\n        // -\u003e expected [name]:\u003c[\"Alice\"]\u003e but was:\u003c[\"Bob\"]\u003e\n    }\n}\n```\n\nYou can see all built-in assertions in\nthe [docs](https://willowtreeapps.github.io/assertk/assertk/assertk.assertions/index.html).\n\n### Nullability\n\nSince null is a first-class concept in kotlin's type system, you need to be explicit in your assertions.\n\n```kotlin\nval nullString: String? = null\nassertThat(nullString).hasLength(4)\n```\n\nwill not compile, since `hasLength()` only makes sense on non-null values. You can chain `isNotNull()` to handle this.\n\n```kotlin\nval nullString: String? = null\nassertThat(nullString).isNotNull().hasLength(4)\n// -\u003e expected to not be null\n```\n\nThis will first ensure the string is not null before running any other checks.\n\n### Multiple assertions\n\nYou can assert multiple things on a single value by providing a lambda as the second argument. All assertions will be\nrun even if the first one fails.\n\n```kotlin\nval string = \"Test\"\nassertThat(string).all {\n    startsWith(\"L\")\n    hasLength(3)\n}\n// -\u003e The following 2 assertions failed:\n//    - expected to start with:\u003c\"L\"\u003e but was:\u003c\"Test\"\u003e\n//    - expected to have length:\u003c3\u003e but was:\u003c\"Test\"\u003e (4)\n```\n\nYou can wrap multiple assertions in an `assertAll` to ensure all of them get run, not just the first one.\n\n```kotlin\nassertAll {\n    assertThat(false).isTrue()\n    assertThat(true).isFalse()\n}\n// -\u003e The following 2 assertions failed:\n//    - expected to be true\n//    - expected to be false\n```\n\n### Iterable/List Assertions\n\nYou can assert on the contents of an `Iterable/List` with the various `contains*` functions. They have different\nsemantics as follows:\n\n| Assertion                 | Description                                                                                                                                                              |\n|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| containsAtLeast           | Asserts the iterable contains at least the expected elements, in **any order**. The collection may also contain **additional elements**.                                 |\n| containsSubList           | Asserts that a collection contains a **subset** of items the **same order**, but may have **additional elements** in the list.                                           |\n| containsOnly              | Asserts the iterable contains **only the expected elements**, in **any order**. **Duplicate values** in the expected and actual are ignored.                             |\n| containsExactlyInAnyOrder | Asserts the iterable contains **exactly the expected elements**, in **any order**. Each value in expected must correspond to a matching value in actual, and visa-versa. |\n| containsExactly           | Asserts the list contains **exactly the expected elements**. They must be in the **same order** and there must not be any extra elements.                                |\n| containsNone              | Asserts the iterable **does not contain any** of the expected elements                                                                                                   |\n\n### Extracting data\n\nThere's a few ways you extract the data you want to assert on. While you can do this yourself before calling the\nassertion, these methods will add the extra context to the failure message which can be helpful.\n\nThe simplest way is with `prop()`. It will take a property (or function, or a name and a lambda) and return an\nassertion on that property.\n\n```kotlin\nval person = Person(age = 22)\nassertThat(person).prop(Person::age).isEqualTo(20)\n\n// -\u003e expected [age]:\u003c2[0]\u003e but was:\u003c2[2]\u003e (Person(age=22))\n```\n\nFor collections, you can use `index()` to pull a specific index from a list, and `key()` to pull a specific value from\na map.\n\n```kotlin\nassertThat(listOf(1, 2, 3)).index(1).isEqualTo(1)\n\n// -\u003e expected: [[1]]:\u003c1\u003e but was:\u003c2\u003e ([1, 2, 3])\n\nassertThat(mapOf(\"one\" to 1, \"two\" to 2, \"three\" to 3)).key(\"two\").isEqualTo(1)\n\n// -\u003e expected: [[\"two\"]]:\u003c1\u003e but was:\u003c2\u003e ({\"one\"=1, \"two\"=2, \"three\"=3})\n```\n\nYou can also extract a property from a collection using `extracting()`.\n\n```kotlin\nval people = listOf(Person(name = \"Sue\"), Person(name = \"Bob\"))\nassertThat(people)\n    .extracting(Person::name)\n    .containsExactly(\"Sue\", \"Bob\")\n```\n\n### Exceptions\n\nIf you expect an exception to be thrown, you can use `assertFailure` which takes a lambda.\n\n```kotlin\nassertFailure {\n    throw Exception(\"error\")\n}.hasMessage(\"wrong\")\n// -\u003e expected [message] to be:\u003c[\"wrong\"]\u003e but was:\u003c[\"error\"]\u003e\n```\n\n### Table Assertions\n\nIf you have multiple sets of values you want to test with, you can create a table assertion.\n\n```kotlin\ntableOf(\"a\", \"b\", \"result\")\n    .row(0, 0, 1)\n    .row(1, 2, 4)\n    .forAll { a, b, result -\u003e\n        assertThat(a + b).isEqualTo(result)\n    }\n// -\u003e the following 2 assertions failed:\n//    on row:(a=\u003c0\u003e,b=\u003c0\u003e,result=\u003c1\u003e)\n//    - expected:\u003c[1]\u003e but was:\u003c[0]\u003e\n//    on row:(a=\u003c1\u003e,b=\u003c2\u003e,result=\u003c4\u003e)\n//    - expected:\u003c[4]\u003e but was:\u003c[3]\u003e\n```\n\nUp to 4 columns are supported.\n\n## Custom Assertions\n\nOne of the goals of this library is to make custom assertions easy to make. All assertions are just extension methods.\n\n```kotlin\nfun Assert\u003cPerson\u003e.hasAge(expected: Int) {\n    prop(Person::age).isEqualTo(expected)\n}\n\nassertThat(person).hasAge(20)\n// -\u003e expected [age]:\u003c2[0]\u003e but was:\u003c2[2]\u003e (Person(age=22))\n```\n\nFor completely custom assertions, you have a few building blocks. `given` will give you the actual value to assert on,\nand `expected()` and `show()` will help you format your failure message.\n\n```kotlin\nfun Assert\u003cPerson\u003e.hasAge(expected: Int) = given { actual -\u003e\n    if (actual.age == expected) return\n    expected(\"age:${show(expected)} but was age:${show(actual.age)}\")\n}\n\nassertThat(person).hasAge(20)\n// -\u003e expected age:\u003c20\u003e but was age:\u003c22\u003e\n```\n\nYou can also build assertions that chain by using `transform`. This allows you to both assert on the actual value, and\nreturn something more specific that additional assertions can be chained on.\n\n```kotlin\nfun Assert\u003cPerson\u003e.hasMiddleName(): Assert\u003cString\u003e = transform(appendName(\"middleName\", separator = \".\")) { actual -\u003e\n    if (actual.middleName != null) {\n        actual.middleName\n    } else {\n        expected(\"to not be null\")\n    }\n}\n\nassertThat(person).hasMiddleName().isEqualTo(\"Lorie\")\n\n// -\u003e expected [middleName]:to not be null\n```\n\nNote: this is a bit of a contrived example as you'd probably want to build this out of existing assertions instead.\n\n```kotlin\nfun Assert\u003cPerson\u003e.hasMiddleName(): Assert\u003cString\u003e = prop(Person::middleName).isNotNull()\n```\n\nThe general rule of thumb is to prefer building out of the existing assertions unless you can give a more meaningful\nerror message.\n\n## Additional Tools\n\n* [Assertk Lint](https://github.com/jzbrooks/assertk-lint) - A set of lint rules to encourage proper use of assertk.\n\n## Contributing to assertk\n\nContributions are more than welcome! Please see\nthe [Contributing Guidelines](https://github.com/willowtreeapps/assertk/blob/main/Contributing.md) and be mindful of\nour [Code of Conduct](https://github.com/willowtreeapps/assertk/blob/main/code-of-conduct.md).\n","funding_links":[],"categories":["Libraries","Testing Tools"],"sub_categories":["Test","🩺 Test"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillowtreeapps%2Fassertk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillowtreeapps%2Fassertk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillowtreeapps%2Fassertk/lists"}