1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
# WaitForIt
[](https://travis-ci.org/zombocom/wait_for_it)
Spawns processes and waits for them so you can integration test really complicated things with determinism. For inspiration behind why you should use something like this check out my talk [Testing the Untestable](https://www.youtube.com/watch?v=QHMKIHkY1nM). You can test long running processes such as webservers, or features that require concurrency or libraries that use global configuration.
Don't add `sleep` to your tests, instead...
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'wait_for_it'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install wait_for_it
## Usage
> For actual usage examples check out the [specs](https://github.com/zombocom/wait_for_it/blob/master/spec/wait_for_it_spec.rb).
This library spawns processes (sorry, doesn't work on windows) and instead of sleeping a predetermined time to wait for that process to do something it reads in a log file until certain outputs are received. For example if you wanted to test booting up a puma webserver, manually when you start it you might get this output
```sh
$ bundle exec puma
[5322] Puma starting in cluster mode...
[5322] * Version 2.15.3 (ruby 2.3.0-p0), codename: Autumn Arbor Airbrush
[5322] * Min threads: 5, max threads: 5
[5322] * Environment: development
[5322] * Process workers: 2
[5322] * Preloading application
[5322] * Listening on tcp://0.0.0.0:3000
[5322] Use Ctrl-C to stop
[5322] - Worker 0 (pid: 5323) booted, phase: 0
[5322] - Worker 1 (pid: 5324) booted, phase: 0
```
So you can see that when `booted` makes its way to the stdout we know it has fully launched and now we can start to use this running process. To do the same thing using this library we could
```ruby
require 'wait_for_it'
WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
# ...
end
```
> NOTE: If you don't use the block syntax you must call `cleanup` on the object, otherwise you may have stray files or process around after you code exits. I recommend calling it in an `ensure` block of code.
Your main code will wait until it receives an output of "booted" from the `bundle exec puma` command. Now the process is running, you could programatically send it a request via `$ curl http://localhost:3000/repos/new` and verify the output using helper methods. Let's say you expect this to trigger a `302` response, the log would look like
```sh
[5324] 127.0.0.1 - - [02/Feb/2016:12:35:15 -0600] "GET /repos/new HTTP/1.1" 302 - 0.0183
```
You can now assert that is found in your puma output
```ruby
WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
`curl http://localhost:3000/repos/new`
assert_equal 1, spawn.count("302")
end
# ...
spawn.cleanup
```
If you have a background thread that sporatically emits information to the logs like [Puma Worker Killer](https://github.com/schneems/puma_worker_killer), if you configure it to do a rolling restart, you could either wait for that to happen.
```ruby
WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn
if spawn.wait("PumaWorkerKiller: Rolling Restart")
# ...
end
end
```
The `wait` command will return a false if it reaches a timeout before finding the output, If you prefer you can raise an exception by using `wait!` method.
You can also assert if the output contains a phrase a string or regex:
```ruby
WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
spawn.contains?("PumaWorkerKiller: Rolling Restart")
end
```
You can directly read from the log if you want
```ruby
WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
spawn.log.read
end
```
The `log` method returns a `Pathname` object.
## Config
You can send environment variables to your process using the `env` key
```ruby
WaitForIt.new("bundle exec puma", wait_for: "booted", env: { RACK_ENV: "production "}) do
end
```
By default redirection is performed using `" >> "` you can change the [IO redirection](http://www.tldp.org/LDP/abs/html/io-redirection.html) by setting the `redirection` key. For example if you wanted to capture STDERR in addition to stdout:
```ruby
spawn = WaitForIt.new("bundle exec puma", wait_for: "booted", redirection: "2>>") do
end
```
If you're using Bash 4 you can get STDERR and STDOUT using `"&>>"` [Stack Overflow](http://stackoverflow.com/questions/876239/how-can-i-redirect-and-append-both-stdout-and-stderr-to-a-file-with-bash).
You can change the default timeout using the `timeout` key (default is 10 seconds).
```ruby
spawn = WaitForIt.new("bundle exec puma", wait_for: "booted", timeout: 60) do
end
```
If you need an individual `wait` have a different timeout you can pass in a timeout value
```ruby
WaitForIt.new("bundle exec puma", wait_for: "booted", timeout: 60) do |spawn|
spawn.wait("GET /repos/new", 2) # timeout after 2 seconds
end
```
## Global config
If you're doing a lot of "waiting for it" you can supply default arguments globally
```
WaitForIt.config do |config|
config.timeout = 60
config.redirection = "2>>"
config.env = { RACK_ENV: "production"}
end
```
## Concurrency Issues
You should be aware of cases where your tests might be run concurrently. For example if you're testing something that uses a lock in postgres, when you run your tests on a CI server it may spin up multiple tests at the same time that all try to grab the same lock. Most CI servers provide unique build IDs that you could use in this case to generate unique keys. Another thing to watch out for is files, if you're tesing a process that writes a `pidfile` you probably want to do something like make a temporary directory and copy files into that directory so that multiple tests could run at the same time and not try to write to the same file.
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/zombocom/wait_for_it. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
|
