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
|
# Climate Control
Easily manage your environment.
## Installation
Add this line to your application's Gemfile:
gem 'climate_control'
And then execute:
$ bundle
Or install it yourself as:
$ gem install climate_control
## Usage
Climate Control can be used to temporarily assign environment variables
within a block:
```ruby
ClimateControl.modify CONFIRMATION_INSTRUCTIONS_BCC: 'confirmation_bcc@example.com' do
sign_up_as 'john@example.com'
confirm_account_for_email 'john@example.com'
expect(current_email).to bcc_to('confirmation_bcc@example.com')
end
```
To modify multiple environment variables:
```ruby
ClimateControl.modify CONFIRMATION_INSTRUCTIONS_BCC: 'confirmation_bcc@example.com',
MAIL_FROM: 'us@example.com' do
sign_up_as 'john@example.com'
confirm_account_for_email 'john@example.com'
expect(current_email).to bcc_to('confirmation_bcc@example.com')
expect(current_email).to be_from('us@example.com')
end
```
To use with RSpec, you could define this in your spec:
```ruby
def with_modified_env(options = {}, &block)
ClimateControl.modify(options, &block)
end
```
This would allow for more straightforward way to modify the environment:
```ruby
require 'spec_helper'
describe Thing, 'name' do
it 'appends ADDITIONAL_NAME' do
with_modified_env ADDITIONAL_NAME: 'bar' do
expect(Thing.new.name).to eq('John Doe Bar')
end
end
def with_modified_env(options, &block)
ClimateControl.modify(options, &block)
end
end
```
To modify the environment for an entire set of tests in RSpec, use an `around`
block:
```ruby
describe Thing, 'name' do
# ... tests
around do |example|
ClimateControl.modify FOO: 'bar' do
example.run
end
end
end
```
Environment variables assigned within the block will be preserved;
essentially, the code should behave exactly the same with and without the
block, except for the overrides. Transparency is crucial because the code
executed within the block is not for `ClimateControl` to manage or modify. See
the tests for more detail about the specific behaviors.
## Why Use Climate Control?
By following guidelines regarding environment variables outlined by the
[twelve-factor app](http://12factor.net/config), testing code in an isolated
manner becomes more difficult:
* avoiding modifications and testing values, we introduce mystery guests
* making modifications and testing values, we introduce risk as environment
variables represent global state
Climate Control modifies environment variables only within the context of the
block, ensuring values are managed properly and consistently.
## Thread-safety
When using threads, for instance when running tests concurrently in the same
process, you may need to wrap your code inside `ClimateControl.modify` blocks,
e.g.:
```ruby
first_thread = Thread.new do
ClimateControl.modify(SECRET: "1") do
p ENV["SECRET"] # => "1"
sleep 2
p ENV["SECRET"] # => "1"
end
end
second_thread = Thread.new do
ClimateControl.modify({}) do
sleep 1
p ENV["SECRET"] # => nil
sleep 1
p ENV["SECRET"] # => nil
end
end
first_thread.join
second_thread.join
```
> The modification wraps ENV in a mutex. If there's contention (the env being used - including potentially mutating values), it blocks until the value is freed (we shift out of the Ruby block).
>
> <cite><a href="https://github.com/thoughtbot/climate_control/issues/32#issuecomment-800713686">Josh Clayton</a></cite>
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
This project uses [StandardRB](https://github.com/testdouble/standard) to ensure formatting.
## License
climate_control is copyright 2012-2021 Joshua Clayton and thoughtbot, inc. It is free software and may be redistributed under the terms specified in the [LICENSE](https://github.com/thoughtbot/climate_control/blob/main/LICENSE) file.
About thoughtbot
----------------
climate_control is maintained and funded by thoughtbot, inc.
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
We love open source software!
See [our other projects][community] or
[hire us][hire] to design, develop, and grow your product.
[community]: https://thoughtbot.com/community?utm_source=github
[hire]: https://thoughtbot.com/hire-us?utm_source=github
|
