Skip to content
This repository
Browse code

Working my way through documenting everything.

  • Loading branch information...
commit ba722419bfe16cbd35a6077a625906fa32220738 1 parent 8c085e2
Pete Yandell authored

Showing 1 changed file with 96 additions and 76 deletions. Show diff stats Hide diff stats

  1. +96 76 README.md
172 README.md
Source Rendered
@@ -2,120 +2,140 @@
2 2
3 3 *Fixtures aren't fun. Machinist is.*
4 4
5   -## What's New?
  5 +And now, Machinist 2 gives you the convenience of Machinist, with the
  6 +performance of fixtures.
6 7
7   -Now you get all the convenience of Machinist, with the performance of fixtures.
  8 +See the wiki for [upgrade instructions and info on what's
  9 +new](http://wiki.github.com/notahat/machinist/machinist-2) in Machinist 2.
8 10
9   -When you create an object, Machinist 2 keeps the object around in the database.
10   -If, in a later test, you request an identical object, Machinist will give you
11   -the cached copy.
12 11
13   -## Introduction
  12 +# Introduction
14 13
15   -Nobody loves fixtures. How do you avoid them?
  14 +Machinist makes it easy to create test data within your tests. It generates
  15 +data for the fields you don't care about, and constructs any necessary
  16 +associated objects, leaving you to specify only the fields you *do* care about
  17 +in your tests. For example:
16 18
17   -It would be nice to just make model objects as you need them, but your models
18   -probably have lots of required attributes, which means you end up writing
19   -something like:
  19 + describe Comment do
  20 + it "should not include spam in the without_spam scope" do
  21 + # This will make a Comment, a Post, and a User (the author of
  22 + # the Post), and generate values for all their attributes:
  23 + spam = Comment.make!(:spam => true)
20 24
21   - user = User.create!(:username => "fred", :email => "fred@example.com", :password => "secret", :password_confirmation => "secret")
22   -
23   -when your test only cares about one or two attributes.
24   -
25   -With Machinist, you just write:
26   -
27   - user = User.make!(:password => "secret")
28   -
29   -Machinist knows how to generate values for the attributes you don't specify in
30   -your test. How? You define a blueprint for User class in `spec/blueprints.rb`:
31   -
32   - User.bluerint do
33   - username { "user#{serial_number}" } # Each user gets a unique serial number.
34   - email { "#{attributes.username}@example.com" }
35   - password { "secret" }
36   - password_confirmation { attributes.password }
  25 + Comment.without_spam.should_not include(spam)
  26 + end
37 27 end
38 28
  29 +You tell Machinist how to do this with blueprints:
39 30
40   -## Docs
41   -
42   -### Caching
  31 + require 'machinist/active_record'
43 32
44   -Whenever you generate an object using `make!`, Machinist keeps it in the
45   -database. If you request an identicaly object in another test, you'll get the
46   -cached object back.
  33 + User.blueprint do
  34 + username { "user#{sn}" } # Each user gets a unique serial number.
  35 + end
  36 +
  37 + Post.blueprint do
  38 + author
  39 + title { "Post #{sn}" }
  40 + body { "Lorem ipsum..." }
  41 + end
47 42
48   -- Serial Numbers
49   -- Accessing Other Attributes
50   -- Associations
51   -- make vs make!
  43 + Comment.blueprint do
  44 + post
  45 + email { "commenter-#{sn}@example.com" }
  46 + body { "Lorem ipsum..." }
  47 + end
52 48
53 49
54   -## Example
  50 +# Installation
55 51
56   -In `app/models/user.rb` you define your model:
  52 +So far the generators only work with Rails 3 and RSpec. This will be fixed soon.
57 53
58   - class User < ActiveRecord::Base
59   - validates_presence_of :username, :email, :password
60   - validates_uniqueness_of :username
61   - validates_confirmation_of :password
62   - end
  54 +## Rails 3
63 55
64   -In `spec/blueprints.rb` you define a blueprint for the user:
  56 +Edit your app's `Gemfile` and, inside the `group :test` section, add:
65 57
66   - User.bluerint do
67   - username { "user#{sn}" }
68   - email { "#{attr.username}@example.com" }
69   - password { "secret" }
70   - password_confirmation { attr.password }
71   - end
  58 + gem 'machinist', '2.0.0.head', :git => 'git://github.com/notahat/machinist.git', :branch => 'machinist2'
72 59
73   -In `spec/models/user_spec.rb` you use Machinist to make a user for you.
74   -Machinist uses the blueprint to generate any attributes you don't explicitly
75   -provide.
  60 +Then run:
76 61
77   - describe User do
78   - it "should match the user's password" do
79   - user = User.make!(:password => "special-password")
80   - user.password_matches?("special-password").should be_true
81   - user.password_matches?("wrong-password").should be_false
82   - end
83   - end
  62 + bundle install
  63 + rake machinist:install
84 64
  65 +If you want Machinist to automatically add a blueprint to your blueprints file
  66 +whenever you generate a model, add the following to your
  67 +`config/application.rb` in the `config.generators` section:
85 68
86   -## What's New
  69 + g.fixture_replacement :machinist
87 70
88   -- Caching, FTW!!!!
89   -- Collections -- make lots of objects in one hit (experimental)
90 71
  72 +# Documentation
91 73
92   -## What's Different
  74 +Still to come!
93 75
94   -Machnist 2 is not a drop-in replacement for Machinist 1. Implementing
95   -caching has required substantial changes to the API.
  76 +- Caching
  77 +- Serial Numbers
  78 +- Accessing Other Attributes
  79 +- Associations
  80 +- make vs make!
96 81
97   -- No more Sham
98   -- Use `make!` if you want a saved object, or `make` if you don't
99   -- Use `object` in the blueprint to access attributes that have already been
100   - assigned on the object being constructed
101 82
  83 +# In The Works
102 84
103   -## What's Not There Yet
  85 +## Not Done Yet
104 86
105   -- No easy upgrade path from Machinist 1
106 87 - No `make` method on associations
107 88 - No support for ORMs other than ActiveRecord
108 89 - Blueprints don't follow class inheritance
109 90 - No `plan` method
110 91
111   -
112   -## What's Broken
  92 +## Currently Broken
113 93
114 94 - The master blueprint for a class has to be defined before any named
115 95 blueprints, or inheritance won't work
116 96
  97 +## In The Planning Stage
117 98
118   -## Stuff I'm Still Thinking About
119   -
  99 +- Support for constructing (and caching) complete graphs of objects in one hit
120 100 - Easy support for different construction strategies, e.g. generating all the
121 101 attributes and passing them to new as a hash
  102 +
  103 +
  104 +# Community
  105 +
  106 +You can always find the [latest version on GitHub](http://github.com/notahat/machinist/tree/machinist2).
  107 +
  108 +If you have questions, check out the [Google Group](http://groups.google.com/group/machinist-users).
  109 +
  110 +File bug reports and feature requests in the [issue tracker](http://github.com/notahat/machinist/issues).
  111 +
  112 +## Contributors
  113 +
  114 +Machinist is maintained by Pete Yandell ([pete@notahat.com](mailto:pete@notahat.com), [@notahat](http://twitter.com/notahat))
  115 +
  116 +Other contributors include:
  117 +
  118 +[Marcos Arias](http://github.com/yizzreel),
  119 +[Jack Dempsey](http://github.com/jackdempsey),
  120 +[Clinton Forbes](http://github.com/clinton),
  121 +[Perryn Fowler](http://github.com/perryn),
  122 +[Niels Ganser](http://github.com/Nielsomat),
  123 +[Jeremy Grant](http://github.com/jeremygrant),
  124 +[Jon Guymon](http://github.com/gnarg),
  125 +[James Healy](http://github.com/yob),
  126 +[Evan David Light](http://github.com/elight),
  127 +[Chris Lloyd](http://github.com/chrislloyd),
  128 +[Adam Meehan](http://github.com/adzap),
  129 +[Kyle Neath](http://github.com/kneath),
  130 +[Lawrence Pit](http://github.com/lawrencepit),
  131 +[T.J. Sheehy](http://github.com/tjsheehy),
  132 +[Roland Swingler](http://github.com/knaveofdiamonds),
  133 +[Gareth Townsend](http://github.com/quamen),
  134 +[Matt Wastrodowski](http://github.com/towski),
  135 +[Ian White](http://github.com/ianwhite)
  136 +
  137 +Thanks to Thoughtbot's [Factory
  138 +Girl](http://github.com/thoughtbot/factory_girl/tree/master). Machinist was
  139 +written because I loved the idea behind Factory Girl, but I thought the
  140 +philosophy wasn't quite right, and I hated the syntax.
  141 +

0 comments on commit ba72241

Please sign in to comment.
Something went wrong with that request. Please try again.