Skip to content

Commit 951a52d

Browse files
serpro69serpro69
committed
Update documentation for random class instance changes
1 parent 346a973 commit 951a52d

File tree

4 files changed

+282
-1
lines changed

4 files changed

+282
-1
lines changed

‎core/src/integration/kotlin/io/github/serpro69/kfaker/docs/Extras.kt

+108
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package io.github.serpro69.kfaker.docs
22

33
import io.github.serpro69.kfaker.Faker
4+
import io.github.serpro69.kfaker.fakerConfig
45
import io.github.serpro69.kfaker.provider.misc.ConstructorFilterStrategy
56
import io.github.serpro69.kfaker.provider.misc.FallbackStrategy
67
import io.kotest.core.spec.style.DescribeSpec
@@ -161,6 +162,113 @@ class Extras : DescribeSpec({
161162
// END extras_random_instance_nine
162163
}
163164
}
165+
166+
context("Configuration levels") {
167+
// START extras_random_instance_ten
168+
class Foo
169+
data class Bar(val int: Int, val uuid: UUID)
170+
data class Baz(val foo: Foo, val bar: Bar, val string: String)
171+
// END extras_random_instance_ten
172+
173+
it("should configure random class instance from fakerConfig") {
174+
// START extras_random_instance_eleven
175+
val cfg = fakerConfig {
176+
randomClassInstance {
177+
typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
178+
}
179+
}
180+
val f = Faker(cfg)
181+
val baz: Baz = f.randomProvider.randomClassInstance<Baz>()
182+
assertEquals(baz.bar, Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")))
183+
val anotherBaz = f.randomProvider.new().randomClassInstance<Baz>()
184+
assertEquals(anotherBaz.bar, Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")))
185+
// END extras_random_instance_eleven
186+
}
187+
188+
it("should configure random class instance from randomProvider") {
189+
// START extras_random_instance_twelve
190+
val cfg = fakerConfig {
191+
randomClassInstance {
192+
typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
193+
}
194+
}
195+
val f = Faker(cfg).also {
196+
it.randomProvider.configure {
197+
typeGenerator<UUID> { UUID.fromString("00000000-0000-0000-0000-000000000000") }
198+
}
199+
}
200+
201+
val bar: Bar = f.randomProvider.randomClassInstance()
202+
val baz: Baz = f.randomProvider.randomClassInstance()
203+
assertEquals(bar.uuid, UUID.fromString("00000000-0000-0000-0000-000000000000"))
204+
assertEquals(baz.bar, Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")))
205+
// END extras_random_instance_twelve
206+
}
207+
208+
it("should configure random class instance from function") {
209+
// START extras_random_instance_thirteen
210+
faker.randomProvider.configure {
211+
typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
212+
}
213+
val baz: Baz = faker.randomProvider.randomClassInstance {
214+
typeGenerator<Bar> { Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")) }
215+
}
216+
assertEquals(baz.bar, Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")))
217+
// END extras_random_instance_thirteen
218+
}
219+
}
220+
221+
context("New instances and copies") {
222+
class Foo
223+
data class Bar(val int: Int, val uuid: UUID)
224+
data class Baz(val foo: Foo, val bar: Bar, val string: String)
225+
226+
it("should create a new instance") {
227+
// START extras_random_instance_fourteen
228+
val cfg = fakerConfig {
229+
randomClassInstance { // ❶
230+
typeGenerator<Bar> { Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")) }
231+
}
232+
}
233+
val f = Faker(cfg)
234+
f.randomProvider.configure { // ❷
235+
typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
236+
}
237+
val new = f.randomProvider.new() // ❸
238+
val baz: Baz = f.randomProvider.randomClassInstance<Baz>()
239+
val newBaz: Baz = new.randomClassInstance<Baz>()
240+
assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), baz.bar)
241+
assertEquals(Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")), newBaz.bar)
242+
// END extras_random_instance_fourteen
243+
}
244+
245+
it("should make a copy") {
246+
// START extras_random_instance_fifteen
247+
val cfg = fakerConfig { // ❶
248+
randomClassInstance {
249+
typeGenerator<Bar> { Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")) }
250+
}
251+
}
252+
val f = Faker(cfg)
253+
f.randomProvider.configure { // ❷
254+
typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
255+
}
256+
val copy = f.randomProvider.copy() // ❸
257+
val baz: Baz = f.randomProvider.randomClassInstance<Baz>()
258+
val bazCopy: Baz = copy.randomClassInstance<Baz>()
259+
assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), baz.bar)
260+
assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), bazCopy.bar)
261+
262+
copy.configure { // ❹
263+
typeGenerator<Bar> { Bar(0, UUID.fromString("22222222-2222-2222-2222-222222222222")) }
264+
}
265+
val originalBaz: Baz = f.randomProvider.randomClassInstance<Baz>()
266+
val reconfiguredBazCopy = copy.randomClassInstance<Baz>()
267+
assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), originalBaz.bar)
268+
assertEquals(Bar(0, UUID.fromString("22222222-2222-2222-2222-222222222222")), reconfiguredBazCopy.bar)
269+
// END extras_random_instance_fifteen
270+
}
271+
}
164272
}
165273

166274
describe("Random Everything") {

‎core/src/integration/kotlin/io/github/serpro69/kfaker/docs/FakerConfiguration.kt

+21
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package io.github.serpro69.kfaker.docs
22

33
import io.github.serpro69.kfaker.Faker
4+
import io.github.serpro69.kfaker.faker
45
import io.github.serpro69.kfaker.fakerConfig
56
import io.kotest.core.spec.DisplayName
67
import io.kotest.core.spec.style.DescribeSpec
@@ -92,5 +93,25 @@ class FakerConfiguration : DescribeSpec({
9293
// END faker_config_five
9394
}
9495
}
96+
97+
context("RandomClassProvider") {
98+
it("should configure RandomClassProvider") {
99+
// START faker_config_six
100+
class Test(
101+
val uuid: UUID,
102+
val name: String,
103+
)
104+
val config = fakerConfig {
105+
randomClassInstance {
106+
collectionsSize = 6
107+
typeGenerator<UUID> { UUID.fromString("00000000-0000-0000-0000-000000000000") }
108+
namedParameterGenerator("name") { faker {}.name.name() }
109+
}
110+
}
111+
val test = Faker(config).randomProvider.randomClassInstance<Test>()
112+
assertEquals(test.uuid, UUID.fromString("00000000-0000-0000-0000-000000000000"))
113+
// END faker_config_six
114+
}
115+
}
95116
}
96117
})

‎docs/src/orchid/resources/wiki/extras.md

+139-1
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@
88
## ToC
99

1010
* [Random instance of any class](#random-instance-of-any-class)
11+
* [Random Class Instance Configuration](#random-class-instance-configuration)
1112
* [Pre-configuring type generation for constructor arguments](#pre-configuring-type-generation-for-constructor-arguments)
1213
* [Deterministic constructor selection](#deterministic-constructor-selection)
1314
* [Configuring the size of generated Collections](#configuring-the-size-of-generated-collections)
15+
* [Making a Copy or a New instance of RandomClassProvider](#making-a-new-instance-of-random-class-provider)
1416
* [Random Everything](#random-everything)
1517
* [Random Strings from Templates](#random-strings-from-templates)
1618

@@ -43,6 +45,80 @@ Random instance generation is available through `Faker().randomProvider`:
4345

4446
<br>
4547

48+
### Random Class Instance Configuration
49+
50+
Random Class Instance configuration can be applied on several levels. Consider the following classes:
51+
52+
{% tabs %}
53+
54+
{% kotlin "Kotlin" %}
55+
{% filter compileAs('md') %}
56+
```kotlin
57+
{% snippet 'extras_random_instance_ten' %}
58+
```
59+
{% endfilter %}
60+
{% endkotlin %}
61+
62+
{% endtabs %}
63+
64+
<br>
65+
66+
#### Configuration via `FakerConfig`
67+
68+
This takes the least precedence and applies to all instances (see [Making a copy/new instance of RandomClassProvider]({{ link(collectionType='wiki', collectionId='', itemId='Extras') }}#making-a-new-instance-of-random-class-provider)) of `RandomClassProvider` if set.
69+
70+
{% tabs %}
71+
72+
{% kotlin "Kotlin" %}
73+
{% filter compileAs('md') %}
74+
```kotlin
75+
{% snippet 'extras_random_instance_eleven' %}
76+
```
77+
{% endfilter %}
78+
{% endkotlin %}
79+
80+
{% endtabs %}
81+
82+
<br>
83+
84+
#### Configuration via `Faker#randomProvider`
85+
86+
This takes higher precedence and will also merge any configuration that was set on the previous level.
87+
88+
{% tabs %}
89+
90+
{% kotlin "Kotlin" %}
91+
{% filter compileAs('md') %}
92+
```kotlin
93+
{% snippet 'extras_random_instance_twelve' %}
94+
```
95+
{% endfilter %}
96+
{% endkotlin %}
97+
98+
{% endtabs %}
99+
100+
<br>
101+
102+
#### Configuration via `randomClassInstance` function
103+
104+
This configuration takes the most precedence and does not take into account configurations applied on other levels.
105+
106+
{% tabs %}
107+
108+
{% kotlin "Kotlin" %}
109+
{% filter compileAs('md') %}
110+
```kotlin
111+
{% snippet 'extras_random_instance_thirteen' %}
112+
```
113+
{% endfilter %}
114+
{% endkotlin %}
115+
116+
{% endtabs %}
117+
118+
{% btc %}{% endbtc %}
119+
120+
<br>
121+
46122
### Pre-Configuring type generation for constructor arguments
47123

48124
Some, or all, of the constructor params can be instantiated with values following some pre-configured logic using `typeGenerator` or `namedParameterGenerator` functions. Consider the following example:
@@ -96,7 +172,7 @@ val baz: Baz = faker.randomProvider.randomClassInstance {
96172
class Person(val id: Int, val name: String)
97173

98174
val person: Person = faker.randomProvider.randomClassInstance {
99-
typeGenerator<String> { faker.name.fullName() }
175+
typeGenerator<String> { faker.name.name() }
100176
}
101177
```
102178
{% endfilter %}
@@ -248,6 +324,68 @@ At the same time, `typeGenerator` configurator itself can be used with collectio
248324

249325
<br>
250326

327+
### Making a new instance of Random Class Provider
328+
329+
`RandomClassProvider` has two functions: `new` and `copy`, that allow you to create another instance of the class, for example, a one that has a different type generation configuration.
330+
331+
#### New Instance
332+
333+
To make a new instance of `randomProvider`:
334+
335+
{% tabs %}
336+
337+
{% kotlin "Kotlin" %}
338+
{% filter compileAs('md') %}
339+
```kotlin
340+
{% snippet 'extras_random_instance_fourteen' %}
341+
```
342+
{% endfilter %}
343+
{% endkotlin %}
344+
345+
{% endtabs %}
346+
347+
348+
<br>
349+
350+
{% info %}
351+
{% filter compileAs('md') %}
352+
Any configuration set via `fakerConfig` ( ❶ ), will be applied to the `new` instance ( ❸ ) as well.
353+
Any configuration set via `faker.randomProvider` instance ( ❷ ) is NOT applied to the `new` instance.
354+
{% endfilter %}
355+
{% endinfo %}
356+
357+
<br>
358+
359+
#### Instance Copy
360+
361+
To make a copy of an existing instance of `randomProvider`:
362+
363+
{% tabs %}
364+
365+
{% kotlin "Kotlin" %}
366+
{% filter compileAs('md') %}
367+
```kotlin
368+
{% snippet 'extras_random_instance_fifteen' %}
369+
```
370+
{% endfilter %}
371+
{% endkotlin %}
372+
373+
{% endtabs %}
374+
375+
<br>
376+
377+
{% info %}
378+
{% filter compileAs('md') %}
379+
Any configuration that was already applied to `faker.randomProvider` ( ❶ and ❷ ), will be applied to the `copy` ( ❸ ) as well.
380+
381+
The `copy`, just as `new` instance, can of course be reconfigured ( ❹ ) as needed, which does not affect the configuration of the `faker.randomProvider` or configurations of other "copies".
382+
{% endfilter %}
383+
{% endinfo %}
384+
385+
{% btc %}{% endbtc %}
386+
387+
<br>
388+
251389
## Random Everything
252390

253391
Faker provides its wrapper functions around `java.util.Random` (with some additional functionality that is not covered by `java.util.Random`) through `Faker().random` property.

‎docs/src/orchid/resources/wiki/faker-configuration.md

+14
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* [Default Configuration](#default-configuration)
99
* [Deterministic Random](#deterministic-random)
1010
* [Locale](#locale)
11+
* [Random Class Instance](#random-class-instance)
1112

1213
<br>
1314

@@ -206,3 +207,16 @@ A list of all locales, and their corresponding dictionary files, can be found on
206207
{% btc %}{% endbtc %}
207208

208209
<br>
210+
211+
## Random Class Instance
212+
213+
[RandomClassInstance]({{ link(collectionType='wiki', collectionId='', itemId='Extras') }}#random-instance-of-any-class) can also be configured both from the `FakerConfig` level.
214+
215+
{% info %}
216+
This configuration takes the least precedence and will be overridden by config set on the `faker.randomProvider` level or on the `randomClassInstance` function level.
217+
See [Random Class Instance Configuration]({{ link(collectionType='wiki', collectionId='', itemId='Extras') }}#random-class-instance-configuration) for more details.
218+
{% endinfo %}
219+
220+
{% btc %}{% endbtc %}
221+
222+
<br>

0 commit comments

Comments
 (0)