README.md in isolator-0.6.2 vs README.md in isolator-0.7.0
- old
+ new
@@ -1,8 +1,8 @@
[](http://cultofmartians.com/tasks/isolator.html)
[](https://badge.fury.io/rb/isolator)
-[](https://travis-ci.org/palkan/isolator)
+
# Isolator
Detect non-atomic interactions within DB transactions.
@@ -77,10 +77,12 @@
2) Isolator does not distinguish framework-level adapters. For example, `:active_job` spy doesn't take into account which AJ adapter you use; if you are using a safe one (e.g. `Que`) just disable the `:active_job` adapter to avoid false negatives (i.e. `Isolator.adapters.active_job.disable!`).
3) Isolator tries to detect the `test` environment and slightly change its behavior: first, it respect _transactional tests_; secondly, error raising is turned on by default (see [below](#configuration)).
+4) Experimental [multiple databases](https://guides.rubyonrails.org/active_record_multiple_databases.html) has been added in v0.7.0. Please, let us know if you encounter any issues.
+
### Configuration
```ruby
Isolator.configure do |config|
# Specify a custom logger to log offenses
@@ -93,10 +95,14 @@
config.send_notifications = false
# Customize backtrace filtering (provide a callable)
# By default, just takes the top-5 lines
config.backtrace_filter = ->(backtrace) { backtrace.take(5) }
+
+ # Define a custom ignorer class (must implement .prepare)
+ # uses a row number based list from the .isolator_todo.yml file
+ config.ignorer = Isolator::Ignorer
end
```
Isolator relys on [uniform_notifier][] to send custom notifications.
@@ -165,11 +171,11 @@
All the exceptions raised in the listed lines will be ignored.
### Using with legacy Ruby codebases
-If you are not using Rails, you'll have to load ignores from file manually, using `Isolator#load_ignore_config`, for instance `Isolator.load_ignore_config("./config/.isolator_todo.yml")`
+If you are not using Rails, you'll have to load ignores from file manually, using `Isolator::Ignorer.prepare(path:)`, for instance `Isolator::Ignorer.prepare(path: "./config/.isolator_todo.yml")`
## Custom Adapters
An adapter is just a combination of a _method wrapper_ and lifecycle hooks.
@@ -181,11 +187,11 @@
#
# The second argument is the method owner and
# the third one is a method name.
Isolator.isolate :danger, Danger, :explode, options
-# NOTE: if you want to isolate a class method, use signleton_class instead
+# NOTE: if you want to isolate a class method, use singleton_class instead
Isolator.isolate :danger, Danger.singleton_class, :explode, options
```
Possible `options` are:
- `exception_class` – an exception class to raise in case of offense
@@ -208,12 +214,24 @@
Isolator.before_isolate do
# right after we enter the transaction
end
Isolator.after_isolate do
- # right after the transaction has been committed/rollbacked
+ # right after the transaction has been committed/rolled back
end
```
+
+## Troubleshooting
+
+### Verbose output
+
+In most cases, turning on verbose output for Isolator helps to identify the issue. To do that, you can either specify `ISOLATOR_DEBUG=true` environment variable or set `Isolator.debug_enabled` manually.
+
+### Tests failing after upgrading to Rails 6.0.3 while using [Combustion](https://github.com/pat/combustion)
+
+The reason is that Rails started using a [separate connection pool for advisory locks](https://github.com/rails/rails/pull/38235) since 6.0.3. Since Combustion usually applies migrations for every test run, this pool becomse visible to [test fixtures](https://github.com/rails/rails/blob/b738f1930f3c82f51741ef7241c1fee691d7deb2/activerecord/lib/active_record/test_fixtures.rb#L123-L127), which resulted in 2 transactional commits tracked by Isolator, which only expects one. That leads to false negatives.
+
+To fix this disable migrations advisory locks by adding `advisory_locks: false` to your database configuration in `(spec|test)/internal/config/database.yml`.
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/isolator.