From da465576e2c2dfa11c6fb1d9977992329c5f405c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Janko=20Marohni=C4=87?= Date: Sat, 1 Jun 2024 23:32:37 +0200 Subject: [PATCH] Document multithreaded transactional tests People searching for testing advice will likely look at the testing guide, so add a section on browser tests there showing the new temporarily_release_connection extension. --- doc/testing.rdoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/testing.rdoc b/doc/testing.rdoc index bc7b9bf53..234b567da 100644 --- a/doc/testing.rdoc +++ b/doc/testing.rdoc @@ -47,6 +47,20 @@ These run each test in its own transaction, the recommended way to test. end end +== Transactional testing with multiple threads + +Some tests may require executing code across multiple threads. The most common example are browser tests with Capybara, where the web server is running in a separate thread. For transactional tests to work in this case, the main thread needs to allow other threads to use its database connection while the transaction is in progress. This can be achieved with the temporarily_release_connection extension: + + DB.extension :temporarily_release_connection + DB.transaction(rollback: :always, auto_savepoint: true) do |conn| + DB.temporarily_release_connection(conn) do + # Other threads can operate on connection safely inside the transaction + yield + end + end + +This requires maximum connection pool size to be 1, so make sure to set the Database +:max_connections+ option to 1 in tests. + == Transactional testing with multiple databases You can use the Sequel.transaction method to run a transaction on multiple databases, rolling all of them back. Instead of: