[](https://stand-with-ukraine.pp.ua)
> [!IMPORTANT]
> **Are you considering supporting the project by donating to me? Please DO NOT!!!**
>
> **Please visit the above banner link and make a small donation to help the people in Ukraine. A small donation goes a long way.** đđ
> **Generate realistically-looking fake data for Kotlin, Android, Java and JVM**
> Use kotlin-faker during development and testing to ensure your application data looks as if it was real, just like this *really* fake logo, but not quite so.
>
> 
>
> *Kotlin-faker is a kotlin port of a popular [ruby faker](https://github.com/stympy/faker) gem.*
[](https://github.com/serpro69/kotlin-faker/actions/workflows/master.yml)
[](https://central.sonatype.com/artifact/io.github.serpro69/kotlin-faker)
[](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/io/github/serpro69/kotlin-faker/)
[](https://github.com/serpro69/kotlin-faker/issues)
[](https://kotlin.link/resources?q=kotlin-faker)
[](LICENSE.md)
## ToC
- [ToC](#toc)
- [About](#about)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Install with Gradle](#install-with-gradle)
- [Install with Maven](#install-with-maven)
- [BOM](#bom)
- [Additional Fakers](#additional-fakers)
- [Third-Party Extensions](#third-party-extensions)
- [Usage](#usage)
- [Generating data](#generating-data)
- [CLI](#cli)
- [Test](#test)
- [Build and Deploy](#build-and-deploy)
- [Bumping versions](#bumping-versions)
- [Pre-releases](#pre-releases)
- [Releases](#releases)
- [Make targets](#make-targets)
- [Contributing](#contributing)
- [Thanks](#thanks)
- [License](#license)
## About
**kotlin-faker: the ultimate fake data generation library for development and testing**
Kotlin-faker is a comprehensive data-generation library for the JVM. It is most suitable for development, testing, and data anonymization purposes, and can be used with Kotlin, Java, Android, Scala, and other JVM-based projects. Kotlin-faker provides realistic-looking, fake data generation capabilities in various domains like *names* đ, *addresses* đĄ, *internet* đ, *banking* đž, *books* đ, *games* đź, and [many more](https://serpro69.github.io/kotlin-faker/wiki/data-providers/).
In fact, kotlin-faker is so good at generating fake data, it almost fooled us into thinking it was real! đ± From names that sound like they belong to secret agents đŽïž, to addresses where superheroes 𩾠might live.
---
â ïž P.S. *All names, addresses, bank accounts, and other data generated by this library - even those based on real strings - are entirely fictional.* đŠč *All produced data is fake and generated... poorly* đ© *The data is completely made up, but the problems that it tries to solve are real* đœ *We take no responsibility for any existential crises caused by the eerily convincing fake data. Use with caution!* â ïž
## Prerequisites
- java 11+
- kotlin 2.x
## Installation
**Full documentation, including [installation instructions](https://serpro69.github.io/kotlin-faker/dev/wiki/getting-started/#installing), for kotlin-faker is available at [serpro69.github.io/kotlin-faker/](https://serpro69.github.io/kotlin-faker/).**
> [!WARNING]
> **kotlin-faker 2.0** is coming, which, apart from new features, also means breaking changes.
>
> More details on currently added breaking changes and migration can be found in [#220](https://github.com/serpro69/kotlin-faker/issues/220)
Latest releases are always available on maven central.
### Install with Gradle
```groovy
dependencies {
implementation 'io.github.serpro69:kotlin-faker:$version'
}
```
### Install with Maven
```xml
io.github.serpro69
kotlin-faker
${version}
```
***Snapshots are also available using the following repository: `https://central.sonatype.com/repository/maven-snapshots/`***
**With gradle**
```groovy
repositories {
maven {
url = 'https://central.sonatype.com/repository/maven-snapshots/'
}
}
```
**With maven**
```xml
sonatype-snapshot
Sonatype Snapshot
https://central.sonatype.com/repository/maven-snapshots/
```
### BOM
Kotlin-faker provides a [Bill-of-Materials](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms) that simplifies dependency management.
See [bom/README.md](bom/README.md) for more details.
### Additional Fakers
Extra fakers covering a wide range of domains are available as separate dependencies. See [faker](faker) submodules in this repo for more details about each faker.
### Third-Party Extensions
Faker provides extensions for some third-party testing libraries. See [extension](extension) submodules in this repo for more details about each extension.
## Usage
### Generating data
```kotlin
val faker = faker { }
faker.name.firstName() // => Ana
faker.address.city() // => New York
```
## CLI
Command line application can be used for a quick lookup of faker functions. See [faker-bot README](cli-bot/README.md)
for installation and usage details.
## Test
To run unit and integration tests: `./gradlew clean test`
## Build and Deploy
To deploy to OSS Sonatype repo:
- set the following properties in `~/.gradle/gradle.properties`
- `signing.keyId=`
- `signing.password=`
- `signing.secretKeyRingFile=/home/user/.gnupg/secring.gpg`
- `sonatypeUsername=`
- `sonatypePassword=`
- `stagingProfileId=`
- running `publishFakerCorePublicationToSonatypeRepository` will publish the artifacts to either staging release repo or to snapshots repo, depending on the current version
### Bumping versions
Versions need to be bumped manually through a tag with the next release version that has to follow the
[semver](https://semver.org/) rules, and the tag has to be pushed to origin.
Creating the tag can be either done manually with `git tag` or by using `gradlew tag` task.
#### Pre-releases
To create a new pre-release version (new release candidate)
the following can be used: `./gradlew clean tag -Prelease -PnewPreRelease -PbumpComponent={comp}`, where `comp` can be
one of the following values: `major`, `minor`, or `patch`.
To bump an existing pre-release to the next version (next release candidate for the same release version)
the following can be used: `./gradlew clean tag -Prelease -PpreRelease`.
#### Releases
To promote a pre-release to a release version the following can be used:
`./gradlew clean tag -Prelease -PpromoteToRelease`,
To create a new release version the following can be used:
`./gradlew clean tag -Prelease -PbumpComponent={comp}`, where `comp` can be one of the following values: `major`
, `minor`, or `patch`.
#### Make targets
Alternatively to the above targets from [Makefile](Makefile) can be used for the same purposes.
## Contributing
The [CONTRIBUTING](CONTRIBUTING.adoc) guidelines should help in getting you started on how to contribute to this project.
## Thanks
Many thanks to these awesome tools that help us in creating open-source software:
[](http://www.jetbrains.com/idea)
[](https://www.yourkit.com/features/)
## License
This code is free to use under the terms of the MIT license. See [LICENSE](LICENSE.adoc).