Define sequenced actions that simulate real-world scenarios, e.g write_file then 2 seconds later rename it
APACHE-2.0 License
Define sequenced actions that simulate real-world scenarios, e.g. write_file then 2 seconds later rename it or execute a sequence of actions on a http server
Add this line to your application's Gemfile:
gem 'rspec-sequencing'
And then execute:
$ bundle
Or install it yourself as:
$ gem install rspec-sequencing
Generally one would use this when you need to have a series of actions occur in way that reflects the real world in terms of being asynchronous, serial, and spread out over time especially when the library code you are testing has difficult to mock dependencies like sockets, files, servers or apis, i.e. integration testing.
Add require "rspec_sequencing"
in your spec_helper.rb or equivalent.
Lets start with an abstract example. Imagine you want to fully test a Order Processing external api. Suppose you want to test the Product Return/Refund api call. Assumptions:
let
variables for creds, order details and client etc. are available. context "when refunding an order" do
let(:results) { Hash.new(NullObject.new) }
it "returns-processing starts and a refund is pending" do
RSpec::Sequencing
.run("login") do
results[:auth] = client.login(*creds)
end
.then("place order") do
results[:new_order] = client.place_order(order_details)
end
.then_after(2, "pay for order") do #<-- wait for place order background job
results[:pay_order] = client.pay_for_order(order_details)
end
.then_after(1, "ship order because we received payment") do
results[:shipit] = client.ship_order(order_details)
end
.then_after(2, "refund order") do
results[:refund] = client.refund_order(order_details)
end
.value # <-- we need to wait for the last action to complete
expect(results[:auth]).to eq("Welcome")
expect(results[:new_order]).to eq("Order placed. Picking started")
expect(results[:pay_order]).to eq("Payment received, thank you.")
expect(results[:shipit]).to eq("Order shipped")
expect(results[:refund]).to eq("Order returns processing started, you will receive a refund when we receive the goods back")
end
end
and the spec output will be
when refunding an order
login
place order
pay for order
ship order because we received payment
refund order
returns-processing starts and a refund is pending
You might be tempted to think, I can just do:
context "when refunding an order" do
it "returns-processing starts and a refund is pending" do
message = client.login(*creds)
expect(message).to eq("Welcome")
message = client.place_order(order_details)
expect(message).to eq("Order placed. Picking started")
sleep 2
message = client.pay_for_order(order_details)
expect(message).to eq("Payment received, thank you.")
sleep 1
message = client.ship_order(order_details)
expect(message).to eq("Order shipped")
sleep 2
message = client.refund_order(order_details)
expect(message).to eq("Order returns processing started, you will receive a refund when we receive the goods back")
end
end
and you would be correct, for this contrived example.
Here is a real example from the Logstash file input plugin tests. Here we use Sequencing to let files age and other elapsed time mechanisms.
context "when ignore_older is less than close_older and all files are not expired" do
let(:opts) { super.merge(:ignore_older => 1, :close_older => 1.1) }
let(:suffix) { "N" }
let(:actions) do
RSpec::Sequencing
.run_after(0.1, "file created") do
File.open(file_path, "wb") { |file| file.write("line1\nline2\n") }
end
.then("start watching before file age reaches ignore_older") do
tailing.watch_this(watch_dir)
end
.then("wait for lines") do
wait(1.2).for{listener1.calls}.to eq([:open, :accept, :accept, :timed_out])
end
.then("quit after allowing time to close the file") do
tailing.quit
end
end
it "reads lines normally" do
actions.activate
# subscribe is a blocking operation until tailing.quit is called on the sequence threads
# and that last step is dependent on the wait(1.2).for rspec expectation to succeed.
tailing.subscribe(observer)
actions.assert_no_errors # if the rspec `wait` call times out then this raises the RSpec failed assertion exception.
expect(listener1.lines).to eq(["line1", "line2"])
end
end
There are two class level constructional methods:
run(description = '', &block) # block runs without delay
run_after(delay, description = '', &block) # block runs after delay seconds
and some instance methods:
then(description = '', &block) # when the previous action completed the block runs without delay
then_after(delay, description = '', &block) # when the previous action completed the block runs after delay seconds
# use `activate` or `activate_quietly`, when defining a sequence in a `let` block,
# to get RSpec to instantiate the sequence.
activate # this will print 'sequence activated' to the RSpec output_stream
activate_quietly # this will print nothing to the RSpec output_stream
value # this will block until the value from the last step is available
The description is optional, however by adding a description you document the action in the code and the spec output. The description is printed after the delay and before the block is executed - use present tense, e.g. "Creating file"
This library is multithreaded and uses the concurrent-ruby
Dataflow feature.
Dataflow will absorb any exceptions and cause the dataflow to be rejected with the reason
set to the Exception.
In this case, use the assert_no_errors
method - this will re-raise the first exception it finds.
Bug reports and pull requests are welcome on GitHub at https://github.com/elastic/rspec-sequencing.