Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 136 lines (83 sloc) 4.995 kb
93f72b8 @jstorimer First version of README
authored
1 Spin
2 ====
3
88431b3 @jstorimer README tweaks
authored
4 Spin speeds up your Rails testing workflow.
93f72b8 @jstorimer First version of README
authored
5
88431b3 @jstorimer README tweaks
authored
6 By preloading your Rails environment in one process and then using fork(2) for each test run you don't load the same code over and over and over...
7 Spin works with an autotest(ish) workflow.
93f72b8 @jstorimer First version of README
authored
8
9 Installation
10 ===========
11
12 Spin is available as a rubygem.
13
14 ``` ruby
15 gem i spin
16 ```
17
88431b3 @jstorimer README tweaks
authored
18 Spin is a tool for Rails 3 apps. It is compatible with the following testing libraries:
19
20 * any version of test/unit or MiniTest
21 * RSpec 2.x
22
93f72b8 @jstorimer First version of README
authored
23 Usage
24 =====
25
26 There are two components to Spin, a server and client. The server has to be running for anything interesting to happen. You can start the Spin server from your `Rails.root` with the following command:
27
28 ``` bash
29 spin serve
30 ```
31
32 As soon as the server is running it will be ready to accept from clients. You can use the following command to specify a file for the server to load:
33
34 ``` bash
35 spin push test/unit/product_test.rb
36 ```
37
fb9f040 @jstorimer Allows multiple files to be pushed at the same time
authored
38 Or push multiple files to be loaded at once:
39
40 ``` bash
41 spin push test/unit/product_test.rb test/unit/shop_test.rb test/unit/cart_test.rb
42 ```
43
381ec3f @maprihoda Preload rspec with the server start
maprihoda authored
44 Or, when using RSpec, run the whole suite:
45
46 ``` bash
47 spin push spec
48 ```
49
043ea46 @maprihoda Update README
maprihoda authored
50 Running a single RSpec example by adding a line number is also possible, e.g:
51
52 ``` bash
53 spin push spec/models/user_spec.rb:14
54 ```
55
3bdf265 @jstorimer Adds note to README about missing test_helper
authored
56 If you experience issues with `test_helper.rb` not being available you may need to add your test directory to the load path using the `-I` option:
57
58 ``` bash
59 spin serve -Itest
60 ```
61
29a59ce Add a note about SIGQUIT to the readme
Jesse Trimble authored
62 Send a SIGQUIT to spin serve (`Ctrl+\`) if you want to re-run the last files that were ran via `spin push [files]`.
63
93f72b8 @jstorimer First version of README
authored
64 ### With Kicker
65
66 As mentioned, this tool works best with an autotest(ish) workflow. I haven't actually used with with `autotest` itself, but it works great with [kicker](http://github.com/alloy/kicker). Here's the suggested workflow for a Rails app:
67
68 1. Start up the spin server
312df15 @jstorimer Trying to fix those code blocks
authored
69
7e0f987 @jstorimer Fixes list numbering in README
authored
70 ``` bash
71 spin serve
72 ```
312df15 @jstorimer Trying to fix those code blocks
authored
73
93f72b8 @jstorimer First version of README
authored
74 2. Start up `kicker` using the custom binary option (and any other options you want)
312df15 @jstorimer Trying to fix those code blocks
authored
75
7e0f987 @jstorimer Fixes list numbering in README
authored
76 ``` bash
77 kicker -r rails -b 'spin push'
78 ```
312df15 @jstorimer Trying to fix those code blocks
authored
79
93f72b8 @jstorimer First version of README
authored
80 3. Faster testing workflow!
81
82 Motivation
83 ==========
84
85 A few months back I did an experiment. I opened up the source code to my local copy of the ActiveRecord gem. I added a line at the top of `active_record/base` that incremented a counter in Redis each time it was evaluated. After about a week that counter was well above 2000!
86
b136c78 @jstorimer README tweaks
authored
87 How did I load the ActiveRecord gem over 2000 times in one week? Autotest. I was using it all day while developing. The Rails version that the app was tracking doesn't change very often, yet I had to load the same code over and over again.
93f72b8 @jstorimer First version of README
authored
88
b136c78 @jstorimer README tweaks
authored
89 Given that there's no way to compile Ruby code into a faster representation I immediately thought of fork(2). I just need a process to load up Rails and wait around until I need it. When I want to run the tests I just fork(2) that idle process and run the test. Then I only have to load Rails once at the start of my workflow, fork(2) takes care of sharing the code with each child process.
93f72b8 @jstorimer First version of README
authored
90
381ec3f @maprihoda Preload rspec with the server start
maprihoda authored
91 I threw together the first version of this project in about 20 minutes and noticed an immediate difference in the speed of my testing workflow. Did I mention that I work on a big app? It takes about 10 seconds(!) to load Rails and all of the gem dependencies. With a bit more hacking I was able to get the idle process to load both Rails and my application dependencies, so each test run just initializes the application and loads the files needed for the test run.
93f72b8 @jstorimer First version of README
authored
92
93 (10 seconds saved per test run) x (2000 test runs per week) = (lots of time saved!)
94
95 ### How is it different from Spork?
96
f035b7a @bquorning Fixed links to Spork
bquorning authored
97 There's another project ([spork](https://github.com/sporkrb/spork)) that aims to solve the same problem, but takes a different approach.
93f72b8 @jstorimer First version of README
authored
98
99 1. It's unobtrusive.
100
101 Your application needs to know about Spork, Spin works entirely outside of your application.
102
103 You'll need to add spork to your Gemfile and introduce your `test_helper.rb` to spork. Spork needs to know details about your app's loading process.
104
b136c78 @jstorimer README tweaks
authored
105 Spin is designed so that your app never has to know about it. You can use Spin to run your tests while the rest of your team doesn't even know that Spin exists.
93f72b8 @jstorimer First version of README
authored
106
107 2. It's simple.
108
109 Spin should work out of the box with any Rails app. No custom configuration required.
110
3007fa7 @leocassarani Fix broken link in README
leocassarani authored
111 3. It doesn't do any [crazy monkey patching](https://github.com/sporkrb/spork-rails/blob/master/lib/spork/app_framework/rails.rb#L43-80).
93f72b8 @jstorimer First version of README
authored
112
88431b3 @jstorimer README tweaks
authored
113 Docs
93f72b8 @jstorimer First version of README
authored
114 ============
115
88431b3 @jstorimer README tweaks
authored
116 [Rocco](http://rtomayko.github.com/rocco/)-annotated source:
f111c48 @jstorimer Fix links to source
authored
117
88431b3 @jstorimer README tweaks
authored
118 * [spin](http://jstorimer.github.com/spin/)
119 * [spin serve](http://jstorimer.github.com/spin/#section-spin_serve)
120 * [spin push](http://jstorimer.github.com/spin/#section-spin_push)
93f72b8 @jstorimer First version of README
authored
121
122 Hacking
123 =======
124
125 I take pull requests, and it's commit bit, and there are no tests.
126
188f843 @jstorimer Adds 'Related Projects' to the README (Closes #19)
authored
127 Related Projects
128 ===============
129
130 If Spin isn't scratching your itch then one of these projects might:
131
eb3e58a @jstorimer Adds a link to guard-spin in the README. Closes #20
authored
132 * [guard-spin](https://github.com/vizjerai/guard-spin)
188f843 @jstorimer Adds 'Related Projects' to the README (Closes #19)
authored
133 * [Spork](https://github.com/sporkrb/spork)
134 * [TestR](https://github.com/sunaku/testr)
135
Something went wrong with that request. Please try again.