{"id":13537118,"url":"https://github.com/goncalossilva/kotlinx-resources","last_synced_at":"2026-01-03T20:14:29.810Z","repository":{"id":37517464,"uuid":"435578611","full_name":"goncalossilva/kotlinx-resources","owner":"goncalossilva","description":"Kotlin Multiplatform (KMP) library for reading resources in tests","archived":false,"fork":false,"pushed_at":"2025-03-25T17:24:08.000Z","size":740,"stargazers_count":121,"open_issues_count":7,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-28T21:08:19.881Z","etag":null,"topics":["gradle-plugin","kotlin-multiplatform","resources","testing"],"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/goncalossilva.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-12-06T17:01:41.000Z","updated_at":"2025-03-27T14:28:35.000Z","dependencies_parsed_at":"2023-10-05T05:13:16.750Z","dependency_job_id":"1161a13c-fe8d-4b5d-9b5d-419f4abddce4","html_url":"https://github.com/goncalossilva/kotlinx-resources","commit_stats":{"total_commits":150,"total_committers":5,"mean_commits":30.0,"dds":"0.42000000000000004","last_synced_commit":"a048d62c50040c02bf9ebfd2822d57103b49e8c0"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goncalossilva%2Fkotlinx-resources","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goncalossilva%2Fkotlinx-resources/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goncalossilva%2Fkotlinx-resources/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goncalossilva%2Fkotlinx-resources/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goncalossilva","download_url":"https://codeload.github.com/goncalossilva/kotlinx-resources/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"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-multiplatform","resources","testing"],"created_at":"2024-08-01T09:00:55.300Z","updated_at":"2026-01-03T20:14:29.799Z","avatar_url":"https://github.com/goncalossilva.png","language":"Kotlin","funding_links":[],"categories":["Libraries"],"sub_categories":["Test","🛢 Resources"],"readme":"# kotlinx-resources\n\n[![badge-library-version]](https://search.maven.org/search?q=g:com.goncalossilva%20a:resources*)\n[![badge-plugin-version]](https://plugins.gradle.org/plugin/com.goncalossilva.resources)\n![badge-jvm][badge-jvm]\n![badge-js][badge-js]\n![badge-nodejs][badge-nodejs]\n![badge-android][badge-android]\n![badge-ios][badge-ios]\n![badge-watchos][badge-watchos]\n![badge-tvos][badge-tvos]\n![badge-macos][badge-macos]\n![badge-windows][badge-windows]\n![badge-linux][badge-linux]\n\nKotlin Multiplatform (KMP) plugin and library for reading resources in tests.\n\nIt bridges the gap between different Kotlin Multiplatform targets, allowing you to access files from your `resources` folders in a single, consistent way.\n\n## Setup\n\nApply the plugin and add the library as a dependency in your `build.gradle.kts`:\n\n```kotlin\nplugins {\n    id(\"com.goncalossilva.resources\") version \"\u003cversion\u003e\"\n}\n\n// ...\n\nkotlin {\n    sourceSets {\n        val commonTest by getting {\n            dependencies {\n                implementation(\"com.goncalossilva:resources:\u003cversion\u003e\")\n            }\n        }\n    }\n}\n```\n\nReplace `\u003cversion\u003e` with the latest version shown in the badge above.\n\n### Compatibility\n\nDifferent Kotlin versions require different versions of the plugin/library:\n\n| Kotlin        | kotlinx-resources                |\n| ------------- | -------------------------------- |\n| 2.1 and above | 0.10 and above                   |\n| 2.0           | 0.9                              |\n| 1.9 and below | 0.8 and below (plus `k1` branch) |\n\n## Usage\n\nTo access a file in your tests:\n\n1. Place it in a [`resources` folder](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.SourceSet.html#org.gradle.api.tasks.SourceSet:resources). For example, in `src/commonTest/resources/` to have it available in all targets, or `src/jsTest/resources/` to limit access to JS.\n2. Instantiate a `Resource` class with the path relative to that folder.\n\n### Examples\n\n#### Basic Multiplatform Example\n\nFor a file located at `src/commonTest/resources/data/example.json`:\n\n```kotlin\nimport com.goncalossilva.resources.Resource\n\nclass MyTest {\n    @Test\n    fun `example data exists`() {\n        val resource = Resource(\"data/example.json\")\n        assertTrue(resource.exists())\n    }\n\n    @Test\n    fun `example data ends in a newline`() {\n        val content = Resource(\"data/example.json\").readText()\n        assertTrue(content.endsWith(\"\\n\"))\n    }\n}\n```\n\n#### Android Example\n\nFor Android device tests, resources are packaged as assets. Place them under `src/androidDeviceTest/resources/` and access using the same relative paths:\n\n```kotlin\nimport com.goncalossilva.resources.Resource\nimport kotlin.test.Test\nimport kotlin.test.assertEquals\n\nclass AndroidResourceTest {\n    @Test\n    fun readsFromAssets() {\n        assertEquals(\"hello\", Resource(\"data/hello.txt\").readText().trim())\n    }\n}\n```\n\n### API Overview\n\nThe `Resource` class provides a clean and simple API:\n\n```kotlin\nclass Resource(path: String) {\n    // Checks if the resource exists at the given path.\n    fun exists(): Boolean\n\n    // Reads the entire resource content as a string decoded using the specified charset.\n    fun readText(charset: Charset = Charsets.UTF_8): String\n\n    // Reads the entire resource content as a byte array.\n    fun readBytes(): ByteArray\n}\n```\n\n## Example Project\n\nLibrary tests use the library itself, so they serve as a practical example.\n\nSee [`ResourceTest`](https://github.com/goncalossilva/kotlinx-resources/blob/main/resources-test/src/commonTest/kotlin/ResourceTest.kt) for example usage, and [`resources-test/src/commonTest/resources`](https://github.com/goncalossilva/kotlinx-resources/tree/main/resources-test/src/commonTest/resources) for the associated folder structure for resources.\n\n## Caveats\n\n### Collisions\n\nAs a rule of thumb, place test files in `src/commonTest/resources/`. This avoids collisions entirely.\n\nBut if you want to override a common file, you can have a platform-specific version of it in the platform-specific source set (e.g., `src/jvmTest/resources/`). By default, Gradle will throw a \"Entry (...) is a duplicate\" error during the build process, prompting you to set a `duplicateStrategy` in your `build.gradle.kts`.\n\nTo have platform-specific resources override common ones, set the strategy to `EXCLUDE`:\n\n```kotlin\ntasks.withType\u003cCopy\u003e().configureEach {\n    if (name.contains(\"Test(?:Copy|Process)Resources$\".toRegex())) {\n        duplicatesStrategy = DuplicatesStrategy.EXCLUDE\n    }\n}\n```\n\n[Other `DuplicatesStrategy` options are available](https://docs.gradle.org/current/javadoc/org/gradle/api/file/DuplicatesStrategy.html), but avoid `INCLUDE`, as the override behavior becomes inconsistent across platforms.\n\n### Browser limitations\n\nIn browser runtimes, `readBytes()` uses a synchronous XHR-based implementation to keep the API synchronous.\nSome browser+tooling stacks can corrupt leading UTF-16 BOM bytes (`0xFF 0xFE` / `0xFE 0xFF`), which makes\n`readText(Charsets.UTF_16)` unreliable for UTF-16 files that include a BOM. Prefer `Charsets.UTF_16LE` /\n`Charsets.UTF_16BE` (or files without a BOM) for browser tests.\n\n## Acknowledgements\n\nThis library is inspired by [this gist](https://gist.github.com/dellisd/a1df42787d42b41cd3ce16f573984674) by [@dellisd](https://gist.github.com/dellisd).\n\n## License\n\nReleased under the [MIT License](https://opensource.org/licenses/MIT).\n\n[badge-library-version]: https://img.shields.io/maven-central/v/com.goncalossilva/resources?style=flat\n[badge-plugin-version]: https://img.shields.io/gradle-plugin-portal/v/com.goncalossilva.resources?style=flat\n[badge-ios]: https://img.shields.io/badge/platform-ios-CDCDCD.svg?style=flat\n[badge-js]: https://img.shields.io/badge/platform-js-F8DB5D.svg?style=flat\n[badge-nodejs]: https://img.shields.io/badge/platform-nodejs-68a063.svg?style=flat\n[badge-android]: https://img.shields.io/badge/platform-android-6EDB8D.svg?style=flat\n[badge-jvm]: https://img.shields.io/badge/platform-jvm-DB413D.svg?style=flat\n[badge-linux]: https://img.shields.io/badge/platform-linux-2D3F6C.svg?style=flat\n[badge-windows]: https://img.shields.io/badge/platform-windows-4D76CD.svg?style=flat\n[badge-macos]: https://img.shields.io/badge/platform-macos-111111.svg?style=flat\n[badge-watchos]: https://img.shields.io/badge/platform-watchos-C0C0C0.svg?style=flat\n[badge-tvos]: https://img.shields.io/badge/platform-tvos-808080.svg?style=flat\n[badge-wasm]: https://img.shields.io/badge/platform-wasm-624FE8.svg?style=flat\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoncalossilva%2Fkotlinx-resources","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoncalossilva%2Fkotlinx-resources","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoncalossilva%2Fkotlinx-resources/lists"}