{"id":16617997,"url":"https://github.com/cc-jhr/nagare","last_synced_at":"2025-04-05T00:18:06.579Z","repository":{"id":38186260,"uuid":"484712081","full_name":"cc-jhr/nagare","owner":"cc-jhr","description":"This is an assertion/matcher library for kotlin using infix functions.","archived":false,"fork":false,"pushed_at":"2024-07-05T17:28:18.000Z","size":1074,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-10T08:32:52.129Z","etag":null,"topics":["assertion-library","assertions","kotlin","testing"],"latest_commit_sha":null,"homepage":"https://cc-jhr.github.io/nagare/","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/cc-jhr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2022-04-23T10:11:09.000Z","updated_at":"2022-05-20T09:13:44.000Z","dependencies_parsed_at":"2023-01-31T11:46:01.628Z","dependency_job_id":"4cf7f195-408d-43f2-b910-5c04d243fb67","html_url":"https://github.com/cc-jhr/nagare","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-jhr%2Fnagare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-jhr%2Fnagare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-jhr%2Fnagare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-jhr%2Fnagare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cc-jhr","download_url":"https://codeload.github.com/cc-jhr/nagare/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266568,"owners_count":20910837,"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":["assertion-library","assertions","kotlin","testing"],"created_at":"2024-10-12T02:18:42.412Z","updated_at":"2025-04-05T00:18:06.553Z","avatar_url":"https://github.com/cc-jhr.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build](https://github.com/cc-jhr/nagare/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/cc-jhr/nagare/actions/workflows/build.yml) [![Coverage Status](https://coveralls.io/repos/github/cc-jhr/nagare/badge.svg?branch=main)](https://coveralls.io/github/cc-jhr/nagare?branch=main)\n\n# nagare\n\nNagare (流れ) is japanese and means \"flow\" / \"stream\". This is an assertion/matcher library for kotlin using infix functions.\nIt is easily extendable using extension functions. You can use it with both junit or testng.\n\n## Setup\n\nIn order to use this library you need a github account and a repository read token.\nWhen logged-in open the [personal access tokens page](https://github.com/settings/tokens). Create a new token having\n`read:packages` as the only permission.\n\n### Gradle - kotlin-dsl\n\nAdd the repository to your existing list of repositories:\n\n```gradle\nrepositories {\n    maven {\n        name = \"nagare\"\n        url = uri(\"https://maven.pkg.github.com/cc-jhr/nagare\")\n        credentials {\n            username = \"your-github-username-here\"            // you should probably use environment variables\n            password = \"your-github-packages-read-token-here\" // or gradle properties here to inject the values\n        }\n    }\n}\n```\n\nAdd the dependency to your `dependencies` block:\n\n```gradle\ndependencies {\n    testImplementation(\"io.github.ccjhr:nagare:VERSION\")\n}\n```\n\n## Usage\n\nOrigin of a test is the object itsef. The object must satisfy criteria\n```kotlin\n    @Test\n    fun `usage test`() {\n        12 mustSatisfy {\n            \n        }\n    }\n```\n\nVarious criteria can be described depending on the class type. `Int` for example provides functions like `isGreaterThan`/`isLesserThan`.\n```kotlin\n    @Test\n    fun `usage test`() {\n        12 mustSatisfy {\n            it isGreaterThan 6\n            it isBetween 10..20\n        }\n    }\n```\n\nNullability can be checked using additional adjectives:\n```kotlin\n    @Test\n    fun `usage test`() {\n        val obj: String? = null\n        \n        obj mustSatisfy {\n            it isNot Null\n        }\n    }\n```\n\nChecking a parameter of a more complex object can be achieved using a nested `mustSatisfy` block:\n```kotlin\n    @Test\n    fun `usage test`() {\n        val obj = MyObj(12, \"\", emptyList())\n\n        obj mustSatisfy {\n            it isNot Null\n            it isOfType MyObj::class\n\n            it.content.number mustSatisfy { number -\u003e\n                number isEqualTo 12\n            }\n        }\n    }\n\n    data class MyObj(\n        val number: Int,\n    )\n```\n\n## Individual extensions\n\nLets assume we have an individual object.\n\n```kotlin\ndata class MyObj(\n    val title: String = \"\",\n    val number: Int = 0,\n)\n```\n\n### Based on values\n\nThe extension function itself always has a similar structure. In the signature we place our object type as\nwell as the class type that we want to test against and give the function a name.\nCheck for nullability. It's possible to make this non-nullable, but then you would have to use `!!` operator or\na kotlin function which uses contracts like `requireNotNull` if your resulting object is nullable.\n\n```kotlin\ninline infix fun \u003creified T : MyObj?\u003e AssertionContext\u003cT\u003e.hasTitleMatching(regex: Regex) {\n    expectNotNull(this.content)\n    \n    if (!regex.matches(this.content.title)) {\n        fail(\"Expecting title \u003c${this.content.title}\u003e to match \u003c${regex.pattern}\u003e, but it doesn't.\")\n    }\n}\n```\n\nThen we can use it in a test.\n\n```kotlin\n@Test\nfun `test the newly created extension`() {\n    // given\n    // setting up the test case\n\n    // when\n    val result: MyObj = // code that returns an instance of MyObj\n\n    // then\n    result mustSatisfy {\n        it hasTitleMatching Regex(\"[a-z]+-[0-9]+\")\n    }\n}\n```\n\n### Based on adjectives\n\nWe can create extensions using adjectives by adding an `enum class` for the adjectives.\nHere we simply imply that the object is \"valid\" in a way.\n\n```kotlin\nenum class MyObjAssertionAdjective {\n    Valid\n}\n```\n\nThe only difference is that the extension function takes the enum class as parameter and we use a `when` to apply to the\ndifferent cases.\n\nJust for the demonstration we assume that the object is valid if it has a `number` greater than `0` and a `title` which\nis not blank.\n\n```kotlin\ninline infix fun \u003creified T : MyObj?\u003e AssertionContext\u003cT\u003e.hasToBe(adjective: MyObjAssertionAdjective) {\n    expectNotNull(this.content)\n    \n    when(adjective) {\n        Valid -\u003e if (content.number \u003c= 0 || content.title.isBlank()) fail(\"Object is not valid.\")\n    }\n}\n```\n\nThen we can use it in a test.\n\n```kotlin\n@Test\nfun `test the newly created extension`() {\n    // given\n    // setting up the test case\n\n    // when\n    val result: MyObj = // code that returns an instance of MyObj\n\n    // then\n    result mustSatisfy {\n        it hasToBe Valid\n    }\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc-jhr%2Fnagare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcc-jhr%2Fnagare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc-jhr%2Fnagare/lists"}