faker_maker 1.1.4 → 1.1.9

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,9 @@
1
+ ---
2
+ layout: default
3
+ title: Contributing
4
+ nav_order: 3
5
+ ---
6
+
7
+ # Contributing
8
+
9
+ Bug reports and pull requests are welcome on GitHub at https://github.com/BillyRuffian/faker_maker.
@@ -0,0 +1,9 @@
1
+ ---
2
+ layout: default
3
+ title: Credits
4
+ nav_order: 4
5
+ ---
6
+
7
+ # Extra Credit
8
+
9
+ Unipug logo by [1smr1](https://pixabay.com/users/1smr1-4646356/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=2970825) from [Pixabay](https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=2970825).
@@ -0,0 +1,21 @@
1
+ ---
2
+ layout: default
3
+ title: Home
4
+ nav_order: 1
5
+ permalink: /
6
+ ---
7
+
8
+ # Factories over fixtures
9
+ {: .fs-9 }
10
+
11
+
12
+ FakerMaker is a simple factory builder so you can throw away your fixtures and generate test data instead.
13
+ {: .fs-6 .fw-300 }
14
+
15
+ ---
16
+
17
+ Sometimes you need generate data; something testers need to do a lot. Often, a bunch of fixtures will be built by hand, carefully maintained and curated, until the API or schema or something changes and all the fixtures need to be pruned before the tests pass again. This drives testers into building fixtures which individually cover lots of acceptance critera just so that they can drive down the number of them they have to maintain until the fixtures don't resemble anything like realistic criteria.
18
+
19
+ If you're testing a Rails application, you can use the awesome [FactoryBot](https://github.com/thoughtbot/factory_bot) to generate faked model instances but what if you're not using Rails or you don't have model classes or you're testing an API? This is what Faker Maker aims to help with.
20
+
21
+ It is designed to resemble the Factory Bot gem but without needing an existing class definition to back its object and so it goes without saying that it offers no persistence mechanism. Its purpose is to provide a simple framework for generating data to test JSON APIs and is intended to be used with the [Faker](https://github.com/stympy/faker) gem (but has no dependency upon it).
@@ -0,0 +1,21 @@
1
+ ---
2
+ layout: default
3
+ title: Installation
4
+ nav_order: 2
5
+ ---
6
+
7
+ # Installation
8
+
9
+ Add this line to your application's Gemfile:
10
+
11
+ ```ruby
12
+ gem 'faker_maker'
13
+ ```
14
+
15
+ And then execute:
16
+
17
+ $ bundle
18
+
19
+ Or install it yourself as:
20
+
21
+ $ gem install faker_maker
Binary file
@@ -0,0 +1,44 @@
1
+ ---
2
+ layout: default
3
+ title: Arrays
4
+ parent: Usage
5
+ nav_order: 2
6
+ ---
7
+
8
+ # Arrays
9
+
10
+ It is possible to declare an attribute as having multiple values.
11
+
12
+ ```ruby
13
+ FakerMaker.factory :basket do
14
+ items( has: 10 ) { Faker::Commerce.product_name }
15
+ end
16
+ ```
17
+
18
+ or to pick random number of attributes from a range:
19
+
20
+ ```ruby
21
+ FakerMaker.factory :basket do
22
+ items( has: 5..20 ) { Faker::Commerce.product_name }
23
+ end
24
+ ```
25
+
26
+ A range always generates an array, even if the range produces 1 items or the range is `0..1`.
27
+
28
+ It is possible to force an attribute to always be an array, even if only produces one item.
29
+
30
+ ```ruby
31
+ FakerMaker.factory :basket do
32
+ items( array: true ) { Faker::Commerce.product_name }
33
+ end
34
+ ```
35
+
36
+ You can always use long-form block syntax...
37
+
38
+ ```ruby
39
+ FakerMaker.factory :basket do
40
+ items has: 5..20 do
41
+ Faker::Commerce.product_name
42
+ end
43
+ end
44
+ ```
@@ -0,0 +1,64 @@
1
+ ---
2
+ layout: default
3
+ title: Building Instances
4
+ parent: Usage
5
+ nav_order: 6
6
+ ---
7
+
8
+ # Building Instances
9
+
10
+ Instances are Plain Ol' Ruby Objects and the attributes are attached with getters and setters with their values assigned to the value return from their block at build time.
11
+
12
+ To build an object:
13
+
14
+ ```ruby
15
+ result = FakerMaker[:basket].build
16
+ ```
17
+
18
+ will generate a new instance using the Basket factory. Because an actual class is defined, you can instantiate an object directly through `Basket.new` but that will not populate any of the attributes.
19
+
20
+ It's possible to override attributes at build-time, either by passing values as a hash:
21
+
22
+ ```ruby
23
+ result = FakerMaker[:item].build( name: 'Electric Blanket' )
24
+ ```
25
+
26
+ or by passing in a block:
27
+
28
+ ```ruby
29
+ result = FakerMaker[:item].build{ |i| i.name = 'Electric Sheep' }
30
+ ```
31
+
32
+ this is particularly useful for overriding nested values, since all the getters and setters of the embedded objects are already constructed:
33
+
34
+ ```ruby
35
+ result = FakerMaker[:basket].build do |b|
36
+ b.items.first.name = 'Neon Badger'
37
+ end
38
+ ```
39
+
40
+ if you're crazy enough to want to do both styles during creation, the values in the block will be preserved, e.g.
41
+
42
+ ```ruby
43
+ result = FakerMaker[:item].build( name: 'Electric Blanket' ) do |i|
44
+ i.name = 'Electric Sheep'
45
+ end
46
+ ```
47
+
48
+ then the value of `result.name` is 'Electric Sheep'.
49
+
50
+ Beware when overriding values in this way: there is no type checking. You will get an exception if you try to set a value to an attribute that doesn't exist but you won't get one if you assign, say, an array of values where you would otherwise have a string and vice versa.
51
+
52
+ Calling `result.to_json` will give a stringified JSON representation. Because ActiveSupport is used under the covers, `as_json` will give you a `Hash` rather than the stringified version.
53
+
54
+ As a convenience, you can request a JSON representation directly:
55
+
56
+ ```ruby
57
+ result = FakerMaker[:basket].to_json
58
+ ```
59
+
60
+ As another convenience, `FakerMaker` is also assigned to the variable `FM` to it is possible to write just:
61
+
62
+ ```ruby
63
+ result = FM[:basket].build
64
+ ```
@@ -0,0 +1,10 @@
1
+ ---
2
+ layout: default
3
+ title: Managing Dependencies
4
+ parent: Usage
5
+ nav_order: 3
6
+ ---
7
+
8
+ # Managing Dependencies
9
+
10
+ Factory definition files are Plain Ol' Ruby. If you depend on another factory because you either extend from it or use it just add a `require` or (depending on your load path) `require_relative` to the top of your file.
@@ -0,0 +1,54 @@
1
+ ---
2
+ layout: default
3
+ title: Destroying Factories
4
+ parent: Usage
5
+ nav_order: 9
6
+ ---
7
+
8
+ ## A Cautionary Tale
9
+
10
+ If you think you want to do this, you are probably wrong. This will not only de-register the factory from Faker Maker, but also delete the class definition from the interpreter. While it's cool that Ruby allows this, it's almost certainly going to hurt.
11
+
12
+ This functionality exists for experimenting with factories in REPLs.
13
+
14
+ Seriously, don't use this in anger.
15
+
16
+ # Destroying Factories
17
+
18
+ Faker Maker deliberately does not allow you to redefine a factory by redeclaring it. It will also be silent about your attempt to do so. This is to avoid throwing up runtime warning from the Ruby interpreter if you are embedding one factory definition in another.
19
+
20
+ For example, this might give you unexpected behavior:
21
+
22
+ ```ruby
23
+ FakerMaker.factory :user do
24
+ name {'Patsy Stone'}
25
+ end
26
+
27
+ FakerMaker.factory :user do
28
+ name {'Patsy Stone'}
29
+ email {'patsy@fabulous.co.uk'}
30
+ end
31
+
32
+ FM[:user].as_json
33
+ => {:name=>"Patsy Stone"}
34
+ ```
35
+
36
+ On the other hand, sometimes you really, really want to destroy a factory and start again (especially if you are experimenting in a REPL for example). FakerMaker allows you to shut a factory which will de-register it from the list of available factories and attempt to unload the class it has built from the Ruby interpreter.
37
+
38
+ ```ruby
39
+ FakerMaker.factory :user do
40
+ name {'Patsy Stone'}
41
+ end
42
+
43
+ FakerMaker.shut!(:user)
44
+
45
+ FakerMaker.factory :user do
46
+ name {'Patsy Stone'}
47
+ email {'patsy@fabulous.co.uk'}
48
+ end
49
+
50
+ FM[:user].as_json
51
+ => {:name=>"Patsy Stone", :email=>"patsy@fabulous.co.uk"}
52
+ ```
53
+
54
+ It also provides the `shut_all!` method to remove all factories.
@@ -0,0 +1,23 @@
1
+ ---
2
+ layout: default
3
+ title: Embedding Factories
4
+ parent: Usage
5
+ nav_order: 8
6
+ ---
7
+
8
+ # Embedding Factories
9
+
10
+ To use factories with factories, the following pattern is recommended:
11
+
12
+ ```ruby
13
+ FakerMaker.factory :item do
14
+ name { Faker::Commerce.product_name }
15
+ price { Faker::Commerce.price }
16
+ end
17
+
18
+ FakerMaker.factory :basket do
19
+ items( has: 10 ) { FakerMaker[:item].build }
20
+ end
21
+ ```
22
+
23
+ You might have to [manage your dependencies]({% link usage/dependencies.md %}) and `require` your referenced factory.
@@ -0,0 +1,52 @@
1
+ ---
2
+ layout: default
3
+ title: Usage
4
+ nav_order: 3
5
+ has_children: true
6
+ ---
7
+
8
+ # Usage
9
+
10
+ FakerMaker generates factories that build disposable objects for testing. Each factory has a name and a set of attributes.
11
+
12
+ ```ruby
13
+ FakerMaker.factory :user do
14
+ name {'Patsy Stone'}
15
+ email {'patsy@fabulous.co.uk'}
16
+ admin {false}
17
+ end
18
+ ```
19
+
20
+ This will generate a `User` class with the attributes `name`, `email` and `admin` which will always return the same value.
21
+
22
+ It is possible to explicitly set the name of class which is particularly useful if there is a risk of redefining an existing one.
23
+
24
+ ```ruby
25
+ FakerMaker.factory :user, class: 'EmailUser' do
26
+ name {'Patsy Stone'}
27
+ email {'patsy@fabulous.co.uk'}
28
+ admin {false}
29
+ end
30
+ ```
31
+
32
+ The class name will always be turned into a Ruby-style class name so `email_user` would become `EmailUser`.
33
+
34
+ Because of the block syntax in Ruby, defining attributes as `Hash`es requires two sets of curly brackets:
35
+
36
+ ```ruby
37
+ FakerMaker.factory :response do
38
+ body { { title: 'First Post', content: 'This is part of a hash' } }
39
+ end
40
+ ```
41
+
42
+ Blocks are executed in the context of their instance. This means you can refer to variables already defined:
43
+
44
+ ```ruby
45
+ FakerMaker.factory :user, class: 'EmailUser' do
46
+ title {'Ms'}
47
+ name {'Patsy Stone'}
48
+ formal_name {"#{title} #{name}"}
49
+ email {'patsy@fabulous.co.uk'}
50
+ admin {false}
51
+ end
52
+ ```
@@ -0,0 +1,37 @@
1
+ ---
2
+ layout: default
3
+ title: Inheritance
4
+ parent: Usage
5
+ nav_order: 1
6
+ ---
7
+
8
+ # Inheritance
9
+
10
+ FakerMaker can exploit the Ruby class hierarchy to provide additional specialisation or to override some behaviours:
11
+
12
+ ```ruby
13
+ FakerMaker.factory :vehicle do
14
+ wheels { 4 }
15
+ colour { Faker::Color.color_name }
16
+ engine_capacity { rand( 600..2500 ) }
17
+ end
18
+
19
+ FakerMaker.factory :motorbike, parent: :vehicle do
20
+ wheels { 2 }
21
+ sidecar { [true, false].sample }
22
+ end
23
+ ```
24
+
25
+ This is the equivalent of:
26
+
27
+ ```ruby
28
+ class Vehicle < Object
29
+ # ...
30
+ end
31
+
32
+ class Motorbike < Vehicle
33
+ # ...
34
+ end
35
+ ```
36
+
37
+ so a motorbike will still have a colour and engine capacity between 600 and 2500.
@@ -0,0 +1,29 @@
1
+ ---
2
+ layout: default
3
+ title: JSON Field Names
4
+ parent: Usage
5
+ nav_order: 4
6
+ ---
7
+
8
+ # JSON Field Names
9
+
10
+ JavaScript likes to use camelCase, Ruby's idiom is to use snake_case. This can make make manipulating factory-built objects in ruby ugly. To avoid this, you can call your fields one thing and ask the JSON outputter to rename the field when generating JSON.
11
+
12
+ ```ruby
13
+ FakerMaker.factory :vehicle do
14
+ wheels { 4 }
15
+ colour { Faker::Color.color_name }
16
+ engine_capacity(json: 'engineCapacity') { rand( 600..2500 ) }
17
+ end
18
+
19
+ v = FM[:vehicle].build
20
+ v.engine_capacity = 125
21
+ ```
22
+
23
+ and calls to `as_json` and `to_json` will report the fieldname as `engineCapacity`.
24
+
25
+ ```ruby
26
+ v.to_json
27
+
28
+ => "{\"wheels\":4,\"colour\":\"blue\",\"engineCapacity\":125}"
29
+ ```
@@ -0,0 +1,33 @@
1
+ ---
2
+ layout: default
3
+ title: Lifecycle Hooks
4
+ parent: Usage
5
+ nav_order: 8
6
+ ---
7
+
8
+ # Lifecycle Hooks
9
+
10
+ Faker Maker has a few hooks which can be added to the factory which are triggered when the factory builds an instance.
11
+
12
+ * `before_build` the instance has been created but none of the values have been set yet
13
+ * `after_build` the instance has been created and all of the values have been set
14
+
15
+ For instance:
16
+
17
+ ```ruby
18
+ FakerMaker.factory :user do
19
+ before_build do
20
+ puts 'Building an instance of User'
21
+ end
22
+
23
+ name {'Patsy Stone'}
24
+ email {'patsy@fabulous.co.uk'}
25
+ admin {false}
26
+
27
+ after_build do
28
+ puts "Built an instance of User (#{faker_maker_factory.instance.name})"
29
+ end
30
+ end
31
+ ```
32
+
33
+ Access to the factory object is through the `faker_maker_factory` method. The instance under construction is available through the `faker_maker_factory.instance` method.
@@ -0,0 +1,42 @@
1
+ ---
2
+ layout: default
3
+ title: Omitting Fields
4
+ parent: Usage
5
+ nav_order: 5
6
+ ---
7
+
8
+ # Omitting Fields
9
+
10
+ Sometimes you want a field present, other times you don't. This is often the case when you want to skip fields which have null or empty values.
11
+
12
+ ```ruby
13
+ FakerMaker.factory :user do
14
+ name {'Patsy Stone'}
15
+ email(omit: :nil) {'patsy@fabulous.co.uk'}
16
+ admin {false}
17
+ end
18
+
19
+ FM[:user].build.as_json
20
+ => {:name=>"Patsy Stone", :email=>"patsy@fabulous.co.uk", :admin=>false}
21
+
22
+ FM[:user].build(email: nil).as_json
23
+ => {:name=>"Patsy Stone", :admin=>false}
24
+ ```
25
+
26
+ The `omit` modifier can take a single value or an array. If it is passed a value and the attribute equals this value, it will not be included in the output from `as_json` (which returns a Ruby Hash) or in `to_json` methods.
27
+
28
+ There are three special modifiers:
29
+
30
+ * `:nil` (symbol) to omit output when the attribute is set to nil
31
+ * `:empty` to omit output when the value is an empty string, an empty array or an empty hash
32
+ * `:always` to never output this attribute.
33
+
34
+ These can be mixed with real values, e.g.
35
+
36
+ ```ruby
37
+ FakerMaker.factory :user do
38
+ name {'Patsy Stone'}
39
+ email(omit: [:nil, :empty, 'test@foobar.com']) {'patsy@fabulous.co.uk'}
40
+ admin {false}
41
+ end
42
+ ```