Merge pull request #172 from KnapsackPro/rspec-track-queue-batches

[Queue] [RSpec] Update docs: Get tests and the status of each batch of tests in RSpec

docusaurus/docs/ruby/hooks.mdx

@@ -34,7 +34,7 @@ KnapsackPro::Hooks::Queue.after_queue do |queue_id|
 end
 ```
 
- ## RSpec
+## RSpec
 
 <details>
   <summary>For legacy versions of `knapsack_pro` older than 7.0, please click here.</summary>
@@ -126,6 +126,43 @@ end
   </Tabs>
 </details>
 
+### Get tests and the status of each batch of tests in RSpec
+
+The `KnapsackPro::Hooks::Queue.before_subset_queue` and `KnapsackPro::Hooks::Queue.after_subset_queue` hooks get a 3rd variable - the `queue`.
+
+The `queue` variable stores an enumerable collection with each batch of tests fetched from the Queue API. The batch has:
+
+* a list of test file paths (`KnapsackPro::Batch#test_file_paths` returns an array like `['a_spec.rb', 'b_spec.rb']`)
+* a status of the given set of tests in the batch (`KnapsackPro::Batch#status` returns `:not_executed`, `:passed` or `:failed`)
+
+Example usage:
+
+```ruby title="spec_helper.rb"
+KnapsackPro::Hooks::Queue.before_subset_queue do |queue_id, subset_queue_id, queue|
+  print "Tests from all batches fetched from the Queue API so far:  "
+  puts queue.map(&:test_file_paths).inspect
+
+  queue.each(&:test_file_paths) # you can use each as well
+
+  print "Current batch tests: "
+  puts queue.current_batch.test_file_paths.inspect
+
+  print "Current batch status: "
+  puts queue.current_batch.status # returns :not_executed in the `before_subset_queue` hook
+end
+
+KnapsackPro::Hooks::Queue.after_subset_queue do |queue_id, subset_queue_id, queue|
+  print "Tests from all batches fetched from the Queue API so far: "
+  puts queue.map(&:test_file_paths).inspect
+
+  print "Current batch tests: "
+  puts queue.current_batch.test_file_paths.inspect
+
+  print "Current batch status: "
+  puts queue.current_batch.status # returns :passed or :failed in the `after_subset_queue` hook
+end
+```
+
 ## `percy-capybara`
 
 ### `percy-capybara` >= 4