https://github.com/lucasteles/fluentbuilder
A fluent way to create builders for tests in TypeScript/JavaScript
https://github.com/lucasteles/fluentbuilder
Last synced: 4 months ago
JSON representation
A fluent way to create builders for tests in TypeScript/JavaScript
- Host: GitHub
- URL: https://github.com/lucasteles/fluentbuilder
- Owner: lucasteles
- License: mit
- Created: 2018-10-22T22:31:29.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-03-02T10:59:13.000Z (over 2 years ago)
- Last Synced: 2025-06-20T16:11:35.645Z (4 months ago)
- Language: TypeScript
- Size: 2.69 MB
- Stars: 34
- Watchers: 2
- Forks: 6
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FluentBuilder
[](https://badge.fury.io/js/fluentbuilder)
[](https://travis-ci.org/lucasteles/fluentbuilder)
[](https://coveralls.io/github/lucasteles/fluentbuilder?branch=master)
FluentBuilder provides a simple way for creating data builders for your tests, with all the beauty of a good intellisense.
It's use [Faker.Js](https://github.com/marak/Faker.js/) for fake data.
## Installation
Nothing new here, just npm install
```sh
npm i --save-dev fluentbuilder
```
## Get Started
Let's define an interface (can be a class or anything like that)
```ts
interface Foo {
id: number,
name: string
}
```
Then define a shape for your builder and use the `addShape` method, which receives a factory function. It will use your shape to generate your test data
```ts
import Builder from 'fluentbuilder'
const builder = new Builder()
builder.addShape(() => ({ id: 1, name: 'bar' }))
builder.generate() // { id: 1, name: 'bar' }
```
You can use the `createBuilder` function
```ts
import { createBuilder } from 'fluentbuilder'
const builder = createBuilder(() => ({ id: 1, name: 'bar' }))
```
This example is not very exciting, but if we put some [Faker.Js](https://github.com/marak/Faker.js/) we can do better!
The delegate used can receive a parameter, which is an instance of FajerJs
```ts
import { createBuilder } from 'fluentbuilder'
const builder = createBuilder(faker => ({
id: faker.random.number(),
name: faker.name.firstName()
}))
builder.generate() // { id: 37566, name: 'Marquis' }
builder.generate() // { id: 7487, name: 'Joy' }
builder.generate(2) // [ { id: 35751, name: 'Opal' }, { id: 94291, name: 'Savion' } ]
```
Like that, every time we call `generate()` we will have new data. Note the fact that if we pass a number as an argument to the `generate(n)` method, it will return an array of your type of the specified size.
### Random data
You can generate a random size collection of data using the method `generateRandom` or using the exported function with the same name.
```ts
import { createBuilder } from 'fluentbuilder'
const builder = createBuilder(faker => ({
id: faker.random.number(),
name: faker.name.firstName()
}))
builder.generateRandom(2) // generate from 1 to 2 items
builder.generateRandom(10,20) // generate from 10 to 20 items
```
it can be useful for nested array on types
```ts
interface Bar {
baz: number,
qux: string,
foos: Foo[],
}
import { createBuilder, generateRandom } from 'fluentbuilder'
const builder = createBuilder(faker => ({
baz: faker.random.number(),
qux: faker.name.firstName(),
foos: generateRandom(() => ({
id: faker.random.number(),
name: faker.name.firstName()
}), 4)
}))
builder.generate() // { baz: 1,qux: 'some',foos: [ { id: 12, name: 'Steve' }, { id: 5, name: 'Jack' } ] }
```
## Fluent Style
You can define `rules` for each of the properties in your type suing the method `ruleFor()`, which receives the property which will be populated, and a value function or a raw value
```ts
builder.ruleFor("id", faker => faker.random.number())
```
We have great intellisense/autocomplete help
With these methods it's easy to derive a class from Builder and make a domain specific builder
```ts
import Builder from 'fluentbuilder'
class FooBuilder extends Builder {
constructor(){
super()
// define basic props
this.from(faker => ({
id: faker.random.number(),
name: faker.name.firstName()
}))
}
withName(name: string): this {
this.ruleFor("name", name);
return this
}
}
const fooBuilder = new FooBuilder()
fooBuilder.generate() // { id: 58431, name: 'Lesley' }
fooBuilder.withName("Fluffy").generate() // { id: 25927, name: 'Fluffy' }
```
The methods can be chained, so this is a valid approach
```ts
const fooFactory = () =>
new Builder()
.ruleFor("id", f => f.random.number())
.ruleFor("name", f => f.name.firstName())
.generate()
```
## Localization
You can change de locale with a function `setLocale`
suported locales can be checked [here](https://github.com/marak/Faker.js/#localization)
```ts
import { setLocale } from 'fluentbuilder'
setLocale("pt_BR")
```