cluster: allow opt-out from global hooks

This patch lets tests create clusters that are not managed by the
preloaded hooks, so you can keep multiple clusters alive between tests or
reuse a single long-lived cluster across the whole test suite.

Closes #414

Author: mandesero

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+- Added an option to create `Cluster` objects without global hook management,
+  allowing tests to keep clusters alive between test runs (gh-414).
+
 ## 1.2.1
 
 - Fixed a bug when `Server:grep_log()` didn't consider the `reset` option.

README.rst

@@ -471,6 +471,39 @@ to server process.
 
 ``luatest.Process:start(path, args, env)`` provides low-level interface to run any other application.
 
+``luatest.cluster`` runs a declarative configuration as a set of Tarantool instances.
+By default clusters are registered inside the current test group and cleaned up with
+preloaded hooks (``auto_cleanup = true``). When you need to reuse the same cluster across
+multiple tests or keep several clusters running at once, pass ``auto_cleanup = false`` and
+manage the lifecycle manually:
+
+.. code-block:: Lua
+
+    local t = require('luatest')
+    local cluster = require('luatest.cluster')
+    local cbuilder = require('luatest.cbuilder')
+
+    local g = t.group('shared')
+
+    g.before_all(function()
+        local config = cbuilder:new()
+            :use_group('g-1')
+            :use_replicaset('rs-1')
+            :add_instance('instance-1', {})
+            :config()
+
+        g.cluster = cluster:new(config, {}, {auto_cleanup = false})
+        g.cluster:start()
+    end)
+
+    g.after_all(function()
+        g.cluster:drop()
+    end)
+
+    g.test_reuses_cluster_between_cases = function()
+        t.assert_not_equals(g.cluster['instance-1'].process, nil)
+    end
+
 There are several small helpers for common actions:
 
 .. code-block:: Lua

luatest/cluster.lua

@@ -47,11 +47,12 @@ local Cluster = require('luatest.class').new()
 -- Cluster uses custom __index implementation to support
 -- getting instances from it using `cluster['i-001']`.
 --
--- Thus, we need to change the metatable of the class
--- with a custom __index method.
-local mt = getmetatable(Cluster)
+-- The metamethod is set on the instance metatable so that multiple
+-- cluster objects can co-exist without clobbering shared state on the
+-- class table.
+local mt = Cluster.mt
 mt.__index = function(self, k)
-    local method = rawget(mt, k)
+    local method = Cluster[k]
     if method ~= nil then
         return method
     end
@@ -310,17 +311,31 @@ end
 -- @tab[opt] server_opts Extra options passed to server:new().
 -- @tab[opt] opts Cluster options.
 -- @string[opt] opts.dir Specific directory for the cluster.
+-- @bool[opt] opts.auto_cleanup Register the cluster in a test group and
+--   automatically drop it using hooks (default: true).
 -- @return table
 function Cluster:new(config, server_opts, opts)
-    local g = cluster._group
-
     assert(type(config) == 'table')
     assert(config._config == nil, "Please provide cbuilder:new():config()")
-    assert(g._cluster == nil)
+
+    opts = opts or {}
+    local auto_cleanup = opts.auto_cleanup
+
+    if auto_cleanup == nil then
+        auto_cleanup = true
+    end
+
+    assert(type(auto_cleanup) == 'boolean')
+
+    local g
+    if auto_cleanup then
+        g = cluster._group
+        assert(g._cluster == nil)
+    end
 
     -- Prepare a temporary directory and write a configuration
     -- file.
-    local dir = opts and opts.dir or treegen.prepare_directory({}, {})
+    local dir = opts.dir or treegen.prepare_directory({}, {})
     local config_file_rel = 'config.yaml'
     local config_file = treegen.write_file(dir, config_file_rel,
                                            yaml.encode(config))
@@ -352,17 +367,20 @@ function Cluster:new(config, server_opts, opts)
         server_map[name] = iserver
     end
 
-    -- Store a cluster object in 'g'.
-    self._servers = servers
-    self._server_map = server_map
-    self._expelled_servers = {}
-    self._dir = dir
-    self._config_file_rel = config_file_rel
-    self._server_opts = server_opts
-
-    g._cluster = self
+    local object = self:from({
+        _servers = servers,
+        _server_map = server_map,
+        _expelled_servers = {},
+        _dir = dir,
+        _config_file_rel = config_file_rel,
+        _server_opts = server_opts,
+    })
+
+    if auto_cleanup then
+        g._cluster = object
+    end
 
-    return self
+    return object
 end
 
 -- }}} Replicaset management

test/cluster_test.lua

@@ -122,6 +122,34 @@ g.test_start_instance = function()
     assert_instance_stopped(c, 'i-002')
 end
 
+g.test_manual_lifecycle = function()
+    t.run_only_if(utils.version_current_ge_than(3, 0, 0),
+                  [[Declarative configuration works on Tarantool 3.0.0+.
+                    See tarantool/tarantool@13149d65bc9d for details]])
+
+    local config = cbuilder:new()
+        :use_group('cluster')
+        :use_replicaset('cluster-rs')
+        :add_instance('cluster-1', {})
+        :config()
+
+    local c1 = cluster:new(config, server_opts, {auto_cleanup = false})
+
+    t.assert_equals(g._cluster, nil)
+
+    c1:start()
+    assert_instance_running(c1, 'cluster-1')
+    c1:drop()
+
+    local c2 = cluster:new(config, server_opts, {auto_cleanup = false})
+
+    t.assert_equals(g._cluster, nil)
+
+    c2:start()
+    assert_instance_running(c2, 'cluster-1')
+    c2:drop()
+end
+
 g.test_sync = function()
     t.run_only_if(utils.version_current_ge_than(3, 0, 0),
                   [[Declarative configuration works on Tarantool 3.0.0+.
@@ -318,3 +346,53 @@ g.test_startup_error = function()
 
     cluster:startup_error(config, 'No such file')
 end
+
+local g_persistent_clusters = t.group('persistent_clusters')
+
+g_persistent_clusters.before_all(function()
+    t.run_only_if(utils.version_current_ge_than(3, 0, 0),
+                  [[Declarative configuration works on Tarantool 3.0.0+.
+                    See tarantool/tarantool@13149d65bc9d for details]])
+
+    g_persistent_clusters.instances = {}
+    g_persistent_clusters.pids = {}
+
+    for i = 1, 3 do
+        local index = tostring(i)
+        local instance = 'persistent-' .. index .. '-1'
+        local config = cbuilder:new()
+            :use_group('persistent-group-' .. index)
+            :use_replicaset('persistent-rs-' .. index)
+            :add_instance(instance, {})
+            :config()
+
+        local c = cluster:new(config, server_opts, {auto_cleanup = false})
+        c:start()
+        assert_instance_running(c, instance)
+
+        g_persistent_clusters.instances[i] = {cluster = c, instance = instance}
+        g_persistent_clusters.pids[i] = c[instance].process.pid
+    end
+end)
+
+g_persistent_clusters.after_all(function()
+    for _, cdata in ipairs(g_persistent_clusters.instances or {}) do
+        cdata.cluster:drop()
+    end
+end)
+
+g_persistent_clusters.test_clusters_survive_between_tests = function()
+    for _, cdata in ipairs(g_persistent_clusters.instances) do
+        assert_instance_running(cdata.cluster, cdata.instance)
+    end
+end
+
+g_persistent_clusters.test_clusters_keep_same_process = function()
+    for i, cdata in ipairs(g_persistent_clusters.instances) do
+        local server = cdata.cluster[cdata.instance]
+
+        t.assert_is_not(server.process, nil)
+        t.assert_equals(server.process.pid, g_persistent_clusters.pids[i])
+        assert_instance_running(cdata.cluster, cdata.instance)
+    end
+end