README.md in ventable-0.0.5 vs README.md in ventable-0.0.6
- old
+ new
@@ -1,7 +1,10 @@
+[](http://badge.fury.io/rb/ventable)
[](http://travis-ci.org/kigster/ventable)
+[](https://codeclimate.com/github/kigster/ventable)
+
# Ventable
Simple eventing gem that implements Observable pattern, but with more options, ability to group observers and wrap
them in arbitrary blocks of code. For example, when a certain event fires, some observers may be called within
a transaction context, while others maybe called outside of the transaction context.
@@ -127,17 +130,62 @@
their respective classes. For example, if you need to send an email to the user, have a ```Mailer```
class observe the ```UserRegisteredEvent```, and so all the mailing logic can live inside the ```Mailer```
class, instead of, say, registration controller directly calling ```Mailer.deliver_user_registration!(user)```.
The callback method will receive the event, that wraps the User instance, or any other useful data necessary.
+## Integration with tests
+
+There are times when it may be desirable to disable all eventing. For instance, when writing unit tests,
+testing that events are fired may be useful, but integrating with all observers adds complexity and confusion.
+In these cases, Ventable may be globally disabled.
+
+```ruby
+## in spec_helper
+
+around :each, eventing: false do |example|
+ Ventable.disable
+ example.run
+ Ventable.enable
+end
+```
+
+Now in a spec file:
+
+```ruby
+describe "Stuff", eventing: false do
+ it 'does stuff' do
+ ... my code that fires events, in isolation from event observers
+ end
+
+ it 'tests that events are fired, using stubs' do
+ event = double(fire!: true)
+ allow(MyEvent).to receive(:new).and_return(event)
+ ... my code that should fire event
+ expect(event).to have_received(:fire!)
+ end
+end
+
+describe 'Other stuff' do
+ it 'actually calls through to all observers, so valid data is required' do
+ end
+end
+```
+
+Note that in the version of RSpec that Ventable has been tested with, tags on a `describe` block
+override tags on an `it` block.
+
## Further Discussion
It is worth mentioning that in the current form this gem is simply a software design pattern. It helps
decouple code that performs tasks related to the same event (such as user registration, or comment posting),
but unrelated to each other (such as sending email to the user).
Future versions of this gem may offer a way to further decouple observers, by allowing them to be notified
via a background queue, such as Sidekiq or Resque. If you are interested in helping, please email the author.
+
+For more information, check out the following blog post:
+
+[Detangling Business Logic in Rails Apps with Pure Ruby Observers](http://building.wanelo.com/post/57442907639/detangling-business-logic-in-rails-apps-with-poro).
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)