is-module-reset 0.8.0 → 0.8.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c285525e3c4f98d207ff16fe510941254976d5985445b93a9442bb5edc7af372
-  data.tar.gz: 795a153090769391780c48225be7c84faccad4df1ffa374c71f3317f38557121
+  metadata.gz: 4c3492581888c7c5515f550a39afb1b9760551aa0ab212e60a263f36cc1d88d7
+  data.tar.gz: 3003eee4ccc3ca344e1d61d14eab567935ddfc6b2a8d91c7ec86a202f1708a0b
 SHA512:
-  metadata.gz: 9adadbc9707da9b5c56f2a5d276342f1816a40d63c7c9645d016c7532b12664f6b409b6c9922c1812edeb8f323914e2071adcd7855051a41725dea7e7808ed61
-  data.tar.gz: d6a7a5f655b0cfef7a4480056d316157d03a4cdb4a43285f4fa05a4af00dfe3f271bc4d27e99a00afe0838760cb062a8e86db77cfdda1015d821c92f3920d88a
+  metadata.gz: fb1def03555aaab2ac065cd94c9746c3d475afefa94e233d9fddb829a7455bc83aa37ec715963dac24a23477edd5d5cd1ce02fb8b8f207d25841e6a5db8e8b1a
+  data.tar.gz: 96d73839eb00418981af55744d585b1bb5c7693ccc47fb323848d6182262d32fc0e99d765a3636fd0793ec728af1138b71c5911602fad0ad754b1e0f9fe5ca7b

data/README.md

@@ -1 +1,194 @@
-# is-module-reset
+# is-module-reset
+
+[![GitHub License](https://img.shields.io/github/license/jekyll-is/is-module-reset)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/is-module-reset.svg)](https://badge.fury.io/rb/is-module-reset)
+![Coverage](coverage-badge.svg)
+
+Save and restore the state of Ruby modules and classes **in tests**: class
+variables (`@@var`) and instance variables of the modules and classes
+themselves (`@var`). It keeps tests that touch global state (singletons,
+registries, caches, settings stored in modules) from affecting each other.
+
+> **Not intended for production use.** The gem does not create a truly
+> isolated environment: it only puts values back into the same objects.
+
+Русская версия: [README-ru.md](README-ru.md)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'is-module-reset', group: :test
+```
+
+Or install directly:
+
+```bash
+gem install is-module-reset
+```
+
+## Quick start
+
+```ruby
+require 'is-module-reset'
+
+module App
+  @@requests = 0
+  @settings = { debug: false }
+
+  def self.requests
+    @@requests
+  end
+
+  def self.hit!
+    @@requests += 1
+  end
+
+  def self.settings
+    @settings
+  end
+end
+```
+
+Run a block and roll everything back afterwards:
+
+```ruby
+IS::ModuleReset.isolate(App) do
+  App.hit!
+  App.settings[:debug] = true
+  App.requests   # => 1
+end
+
+App.requests     # => 0
+App.settings     # => { debug: false }
+```
+
+Or take a snapshot and restore it manually:
+
+```ruby
+state = IS::ModuleReset.dump(App)
+
+App.hit!
+App.settings[:debug] = true
+
+IS::ModuleReset.undump(state)
+
+App.requests     # => 0
+App.settings     # => { debug: false }
+```
+
+## What is saved
+
+For every module or class you pass in, and for every module or class
+reachable from it through constants (recursively, using only the module's own
+constants, i.e. `Module#constants(false)`), the gem saves:
+
+- the class variables defined by that module itself (inherited ones are not
+  included);
+- the instance variables of the module object itself (`@var` set at module or
+  class level, including those created by `attr_accessor` in `class << self`).
+
+When restoring, all such variables are removed and the saved ones are set
+again. This means that variables created after the snapshot disappear, changed
+ones return to their old values, and deleted ones come back.
+
+Values are copied with `deep_dup` from [is-deep](https://github.com/inat-get/is-deep):
+`Hash` and `Array` are copied recursively (shared and circular references are
+preserved), modules and classes are kept as they are, and other objects are
+copied with `dup` (if an object cannot be duplicated, the same object is kept).
+Restoring also works on a copy, so the same snapshot can be restored any
+number of times.
+
+## API
+
+### `IS::ModuleReset.dump(*mods) → Hash`
+
+Takes a snapshot of the given modules and everything reachable from them via
+constants. The returned hash is an internal representation; treat it as an
+opaque value and pass it to `undump`.
+
+### `IS::ModuleReset.undump(state)`
+
+Restores the state from a snapshot returned by `dump`. May be called multiple
+times with the same snapshot.
+
+### `IS::ModuleReset.isolate(*mods) { ... }`
+
+Takes a snapshot, runs the block, and restores the snapshot afterwards, even if
+the block raised an exception. Returns the value of the block. Raises
+`ArgumentError` if no block is given.
+
+## Test framework integration
+
+### RSpec
+
+Isolate every example:
+
+```ruby
+RSpec.configure do |config|
+  config.around do |example|
+    IS::ModuleReset.isolate(MyApp) { example.run }
+  end
+end
+```
+
+`around` hooks wrap `before` and `after` hooks, so changes made there are
+rolled back too.
+
+Or restore the state captured when the suite started:
+
+```ruby
+RSpec.configure do |config|
+  baseline = nil
+  config.before(:suite) { baseline = IS::ModuleReset.dump(MyApp) }
+  config.after(:each)   { IS::ModuleReset.undump(baseline) }
+end
+```
+
+### Minitest
+
+```ruby
+class Minitest::Test
+  def setup
+    super
+    @module_reset_state = IS::ModuleReset.dump(MyApp)
+  end
+
+  def teardown
+    IS::ModuleReset.undump(@module_reset_state)
+    super
+  end
+end
+```
+
+If your test classes define their own `setup` and `teardown`, call `super`.
+
+## Limitations
+
+- **Constants are not restored.** Neither reassigned, added, or removed
+  constants, nor the contents of mutable constants (`CONFIG = {}`).
+- **Only module-level state is saved.** Global variables (`$var`), `ENV`,
+  thread-local variables, instance variables of ordinary objects, and anything
+  outside the namespaces you pass in are not touched.
+- **Values are copies.** Objects other than `Hash` and `Array` are copied with
+  a shallow `dup`: their inner mutable state is shared with the original, and
+  after restoring the module holds the copy rather than the original instance.
+  If you store, say, a singleton object in `@instance`, it may become a
+  different object after restoring.
+- **Copies are not frozen.** A frozen value becomes mutable after restoring.
+- **Constants are followed blindly.** An alias to a module from another
+  namespace (`Log = ::Logger`) is included in the snapshot and rolled back too.
+  Traversal may also trigger loading of `autoload` constants.
+- **Not thread-safe.** The gem changes global state, so do not use it with
+  tests running in parallel threads of the same process. Process-based
+  parallelism is fine.
+
+## Requirements
+
+- Ruby >= 3.4
+- [is-deep](https://github.com/inat-get/is-deep)
+
+## License
+
+LGPL-3.0-or-later. See the [LICENSE](LICENSE) file.

data/lib/is-module-reset/info.rb

@@ -6,7 +6,7 @@ module IS::ModuleReset; end
 module IS::ModuleReset::Info
 
   NAME = 'is-module-reset'
-  VERSION  = '0.8.0'
+  VERSION  = '0.8.0.2'
   SUMMARY  = 'Reset singletons data for testing'
   LICENSE  = 'LGPL-3.0-or-later'
   AUTHOR   = 'Ivan Shikhalev'

data/lib/is-module-reset/main.rb

@@ -17,8 +17,8 @@ module IS::ModuleReset
     end
 
     def undump state
-      state.each do |mod, mod_state|
-        mod.class_variables.each { mod.remove_class_variable it }
+      state.deep_dup.each do |mod, mod_state|
+        mod.class_variables(false).each { mod.remove_class_variable it }
         mod_state[:class_vars].each do |var, value|
           mod.class_variable_set var, value
         end
@@ -32,16 +32,18 @@ module IS::ModuleReset
     def isolate *mods
       raise ArgumentError, 'Block is required!' unless block_given?
       state = dump(*mods)
-      yield
-    ensure
-      undump state
+      begin
+        yield
+      ensure
+        undump state
+      end
     end
 
     private
 
     def dump_module state, mod
       mod_state = { instance_vars: {}, class_vars: {} }
-      mod.class_variables.each do |var|
+      mod.class_variables(false).each do |var|
         mod_state[:class_vars][var] = mod.class_variable_get(var)
       end
       mod.instance_variables.each do |var|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: is-module-reset
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.0.2
 platform: ruby
 authors:
 - Ivan Shikhalev
@@ -16,6 +16,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.0.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.0.4
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement