Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xgouchet/elmyr
A utility to make Kotlin/Java tests random yet reproducible
https://github.com/xgouchet/elmyr
fuzzing hacktoberfest hacktoberfest2020 hacktoberfest2021 hacktoberfest2022 hacktoberfest2023 hacktoberfest2024 java kotlin test
Last synced: about 11 hours ago
JSON representation
A utility to make Kotlin/Java tests random yet reproducible
- Host: GitHub
- URL: https://github.com/xgouchet/elmyr
- Owner: xgouchet
- License: other
- Created: 2017-05-22T08:29:35.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-17T07:25:29.000Z (2 months ago)
- Last Synced: 2024-12-18T06:06:14.939Z (8 days ago)
- Topics: fuzzing, hacktoberfest, hacktoberfest2020, hacktoberfest2021, hacktoberfest2022, hacktoberfest2023, hacktoberfest2024, java, kotlin, test
- Language: Kotlin
- Homepage:
- Size: 935 KB
- Stars: 83
- Watchers: 3
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Elmyr
> Elmyr is a Kotlin library providing tools to generate “random” values, specifically useful for tests
[](https://central.sonatype.com/namespace/fr.xgouchet.elmyr)
[](https://github.com/xgouchet/Elmyr/wiki)
[](https://circleci.com/github/xgouchet/Elmyr)
[](https://codecov.io/gh/xgouchet/Elmyr)
[](https://opensource.org/licenses/MIT)
[](https://paypal.me/xaviergouchet)
Being an adept of testing code, I write a lot of tests. One thing I noticed is that in my tests, my fake / test data always look the same. My user names are always `“Bob”` and `“Alice”`, aged `42` or `69`, with userId `4816152342` or `24601`, and eating `“spam”`, `“eggs”` and `“bacon”`.
The problem is, the more test I write, the less I'm confident in my fake values, because they're always the same.
This is where Elmyr kicks in, allowing you to create fake/fuzzy data based on a few constraints, making your test data random, and yet reproducible.
## Usage
### Gradle
```groovy
dependencies {
// Core library
testCompile("com.github.xgouchet.Elmyr:core:1.4.1")
// Testing Framework Integrations
testCompile("com.github.xgouchet.Elmyr:junit4:1.4.1")
testCompile("com.github.xgouchet.Elmyr:junit5:1.4.1")
testCompile("com.github.xgouchet.Elmyr:spek:1.4.1")
//
testCompile("com.github.xgouchet.Elmyr:jvm:1.4.1")
}
```
### Forging data: the `core` module
You can create an instance of the `Forge` class, and from that generate:
- primitives, with basic constraints
- Strings matching simple predicates or even Regexes
- Any Kotlin `data class`
- Your own custom data, by implementing the `ForgeryFactory` interface, then
calling the `Forge::addFactory` method.
### ForgeRule for `junit4`
You can instantiate a `ForgeRule` instance, which extends the `Forge` class,
add factories to it, and then annotate fields on your test class with `@Forgery`.
```kotlin
class FooTest {
@get:Rule
val forge = ForgeRule()
.withFactory(FooFactory())
.withFactory(BarFactory())
@Forgery
internal lateinit var fakeBar: Bar
@Forgery
lateinit var fakeFooList: List
//…
}
```
### ForgeExtension for `junit5`
You can add an extension and configure it. In addition to creating forgeries on
fields/properties of your test class, you can inject parameters directly on your
test methods.
```kotlin
@ExtendWith(ForgeExtension::class)
@ForgeConfiguration(KotlinAnnotationTest.Configurator::class)
internal class FooTest {
@Forgery
internal lateinit var fakeBar: Bar
@Forgery
lateinit var fakeFooList: List
@Test
fun testSomething(@IntForgery i: Int, forge:Forge){
// …
}
}
```
### `spek` forgeries
You can create a custom Forge instance with `spekForge` to be able to
add reproducibility to Spek tests.
```kotlin
class CalculatorSpek : Spek({
val forge = spekForge(
seeds = mapOf(
"CalculatorSpek/A calculator/addition/returns the sum of its arguments" to 0x1337L
)
)
describe("A calculator") {
val calculator by memoized { Calculator() }
describe("addition") {
it("returns the sum of its arguments") {
val a = forge.anInt()
val b = forge.anInt()
assertEquals(calculator.add(a, b), a + b)
}
}
}
})
```
## Documentation
The full documentation will be coming shortly.
The [Wiki](https://github.com/xgouchet/Elmyr/wiki) contains a full reference of all the packages and classes distributed.
## Contributing
Contribution is always welcome, to know more, read our [Contributing guide](.github/CONTRIBUTING.md).
## Release History
### Latest Release: `1.4.1` (2024/10/19)
#### `core`
- Add enum forgery through reflexive factory
- Make reflexive factory available through injection (with `@Forgery`)
- Make reflexive factory available via JUnit4 (with `@ForgeRule`)
- Make reflexive factory available via JUnit5 (with `@ForgeExtension`)
- Add set forgery (thanks [@ambushwork](https://github.com/ambushwork))
- Add list forgery with indexed lambda (thanks [@ambushwork](https://github.com/ambushwork))
## Donate
This library is completely free to use and modify (as per the [License](LICENSE.md)).
I try my best to make it as good as possible, but only do this on my free time.
If you want to support my work, you can click the Donate button below.
[](https://paypal.me/xaviergouchet)
## Meta
Xavier F. Gouchet – [@xgouchet](https://twitter.com/xgouchet)
Distributed under the MIT license. See [LICENSE.md](LICENSE.md) for more information.
[https://github.com/xgouchet/Elymr](https://github.com/xgouchet/Elymr)