Cache TerraformTest methods (#57)

* add test_pickle.py

* add skip duner method cond and __*state__ methods

* add linting changes

* linting changes attempt 2

* lint changes tftest.py

* add .terragrunt-cache to gitignore

* add tftest_fixt to setup

* add tftest_fixt.py

* add terra fixt tests

* add terragrunt.hcl to plan_no_resource_changes fixt

* rm skip teardown flag and param attr

* add base_tester fixt to import tftest fixtures

* add tftest_fixt to setup py_modules

* rm tftest_fixt from py mod & fix test fixt import

* any heredocs and type hints

* fix cache hash being difference on every test

* autopep8 changes

* add .tftest-cache to gitignore

* add _cache()

* Delete test_terra_fixtures.py

* Create test_cache.py

* add use_cache arg to other methods

* Delete tftest_fixt.py

* rm pytest fixture from setup

* add cache args to TerragruntTest

* add caching section to readme

* fix using cache condition

* pass use_cache to init() within setup()

Co-authored-by: Ludovico Magnocavallo <ludomagno@google.com>

Author: marshall7m

.gitignore

@@ -125,6 +125,12 @@ dmypy.json
 # Local .terraform directories
 **/.terraform/*
 
+# Local .terragrunt directories
+**/.terragrunt-cache/*
+
+# Local .tftest-cache directories
+**/.tftest-cache/*
+
 # .tfstate files
 *.tfstate
 *.tfstate.*

README.md

@@ -78,6 +78,42 @@ def test_run_all_apply(run_all_apply_out):
     assert len(run_all_apply_out) == 3
 ```
 
+## Caching
+
+The `TerraformTest` `setup`, `init`, `plan`, `apply`, `output` and `destroy` methods have the ability to cache it's associate output to a local `.tftest-cache` directory. For subsequent calls of the method, the cached value can be returned instead of calling the actual underlying `terraform` command. Using the cache value can be significantly faster than running the Terraform command again especially if the command is time-intensive.
+
+To determine if the cache should be used, first a hash value is generated using the current `TerraformTest` instance `__init__` and calling method arguments. The hash value is compared to the hash value of the cached instance's associated arguments. If the hash is the same then the cache is used, otherwise the method is executed.
+
+The benefits of the caching feature include:
+- Faster setup time for testing terraform modules that don't change between testing sessions
+- Writing tests without worrying about errors within their test code resulting in the Terraform setup logic to run again
+
+Please see the following example for how to use it:
+
+```python
+import pytest
+import tftest
+
+
+@pytest.fixture
+def output(fixtures_dir):
+  tf = tftest.TerraformTest('apply', fixtures_dir, enable_cache=True)
+  tf.setup(use_cache=True)
+  tf.apply(use_cache=True)
+  yield tf.output(use_cache=True)
+  tf.destroy(use_cache=True, **{"auto_approve": True})
+
+
+def test_apply(output):
+  value = output['triggers']
+  assert len(value) == 2
+  assert list(value[0].keys()) == ['name', 'template']
+  assert value[0]['name'] == 'one'
+
+```
+
+
+
 ## Compatibility
 
 Starting from version `1.0.0` Terraform `0.12` is required, and tests written with previous versions of this module are incompatible. Check the [`CHANGELOG.md`](https://github.com/GoogleCloudPlatform/terraform-python-testing-helper/blob/master/CHANGELOG.md) file for details on what's changed.

setup.py

@@ -37,5 +37,5 @@
         "Operating System :: OS Independent",
     ],
     setup_requires=['nose>=1.3'],
-    test_suite='nose.collector'
+    test_suite='nose.collector',
 )

test/fixtures/plan_no_resource_changes/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+    source = get_terragrunt_dir()
+}

test/test_cache.py

@@ -0,0 +1,80 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import os
+import shutil
+import pytest
+import tftest
+from unittest.mock import patch, DEFAULT, Mock
+
+pytest_plugins = [
+    str("_pytest.pytester"),
+]
+
+_LOGGER = logging.getLogger('tftest')
+
+cache_methods = ["setup", "init", "plan", "apply", "output", "destroy"]
+
+
+@pytest.fixture
+def tf(request, fixtures_dir):
+  terra = tftest.TerraformTest(
+      tfdir='plan_no_resource_changes',
+      basedir=fixtures_dir,
+      enable_cache=request.param,
+  )
+  yield terra
+
+  _LOGGER.debug("Removing cache dir")
+  try:
+    shutil.rmtree(terra.cache_dir)
+  except FileNotFoundError:
+    _LOGGER.debug("%s does not exists", terra.cache_dir)
+
+
+@pytest.mark.parametrize("tf", [True], indirect=True)
+def test_use_cache(tf):
+  """
+  Ensures cache is used and runs the execute_command() for first call of the 
+  method only
+  """
+  for method in cache_methods:
+    with patch.object(tf, 'execute_command', wraps=tf.execute_command) as mock_execute_command:
+      for _ in range(2):
+        getattr(tf, method)(use_cache=True)
+      assert mock_execute_command.call_count == 1
+
+
+@pytest.mark.parametrize("tf", [
+    pytest.param(
+        True,
+        id="enable_cache"
+    ),
+    pytest.param(
+        False,
+        id="disable_cache"
+    ),
+], indirect=True)
+def test_no_use_cache(tf):
+  """
+  Ensures cache is not used and runs the execute_command() for every call of
+  the method
+  """
+  expected_call_count = 2
+  for method in cache_methods:
+    with patch.object(tf, 'execute_command', wraps=tf.execute_command) as mock_execute_command:
+      for _ in range(expected_call_count):
+        getattr(tf, method)(use_cache=False)
+      assert mock_execute_command.call_count == expected_call_count

tftest.py

@@ -39,6 +39,9 @@
 from functools import partial
 from pathlib import Path
 from typing import List
+import pickle
+from hashlib import sha1
+import inspect
 
 __version__ = '1.7.3'
 
@@ -307,9 +310,12 @@ class TerraformTest(object):
       directory above the one this module lives in.
     binary: path to the Terraform command.
     env: a dict with custom environment variables to pass to terraform.
+    enable_cache: Determines if the caching enabled for specific methods
+    cache_dir: optional base directory to use for caching, defaults to
+      the directory of the python file that instantiates this class
   """
 
-  def __init__(self, tfdir, basedir=None, binary='terraform', env=None):
+  def __init__(self, tfdir, basedir=None, binary='terraform', env=None, enable_cache=False, cache_dir=None):
     """Set Terraform folder to operate on, and optional base directory."""
     self._basedir = basedir or os.getcwd()
     self.binary = binary
@@ -318,6 +324,12 @@ def __init__(self, tfdir, basedir=None, binary='terraform', env=None):
     self.tg_run_all = False
     self._plan_formatter = lambda out: TerraformPlanOutput(json.loads(out))
     self._output_formatter = lambda out: TerraformValueDict(json.loads(out))
+    self.enable_cache = enable_cache
+    if not cache_dir:
+      self.cache_dir = Path(os.path.dirname(
+          inspect.stack()[1].filename)) / ".tftest-cache"
+    else:
+      self.cache_dir = Path(cache_dir)
     if env is not None:
       self.env.update(env)
 
@@ -363,9 +375,74 @@ def _abspath(self, path):
     """Make relative path absolute from base dir."""
     return path if os.path.isabs(path) else os.path.join(self._basedir, path)
 
+  def _cache(func):
+    def cache(self, **kwargs):
+      """
+      Runs the tftest instance method or retreives the cache value if it exists
+
+      Args:
+          kwargs: Keyword argument that are passed to the decorated method
+      Returns:
+          Output of the tftest instance method
+      """
+      _LOGGER.info("Cache decorated method: %s", func.__name__)
+
+      if not self.enable_cache:
+        return func(self, **kwargs)
+      elif not kwargs.get("use_cache", False):
+        return func(self, **kwargs)
+
+      cache_dir = self.cache_dir / \
+          Path(self.tfdir.strip("/")) / Path(func.__name__)
+      # creates cache dir if not exists
+      cache_dir.mkdir(parents=True, exist_ok=True)
+
+      params = {
+          **{
+              k: v
+              for k, v in self.__dict__.items()
+              # only uses instance attributes that are involved in the results of
+              # the decorated method
+              if k in ["binary", "_basedir", "tfdir", "env"]
+          },
+          **kwargs,
+      }
+
+      hash_filename = sha1(
+          json.dumps(params, sort_keys=True, default=str).encode("cp037")
+      ).hexdigest() + ".pickle"
+
+      cache_key = cache_dir / hash_filename
+      _LOGGER.debug("Cache key: %s", cache_key)
+
+      try:
+        f = cache_key.open("rb")
+      except OSError:
+        _LOGGER.debug("Could not read cache path")
+      else:
+        _LOGGER.info("Getting output from cache")
+        return pickle.load(f)
+
+      _LOGGER.info("Running command")
+      out = func(self, **kwargs)
+
+      if out:
+        _LOGGER.info("Writing command to cache")
+        try:
+          f = cache_key.open("wb")
+        except OSError as e:
+          _LOGGER.error("Cache could not write path")
+        else:
+          with f:
+            pickle.dump(out, f, pickle.HIGHEST_PROTOCOL)
+
+      return out
+    return cache
+
+  @_cache
   def setup(self, extra_files=None, plugin_dir=None, init_vars=None,
             backend=True, cleanup_on_exit=True, disable_prevent_destroy=False,
-            workspace_name=None, **kw):
+            workspace_name=None, use_cache=False, **kw):
     """Setup method to use in test fixtures.
 
     This method prepares a new Terraform environment for testing the module
@@ -437,13 +514,14 @@ def setup(self, extra_files=None, plugin_dir=None, init_vars=None,
                                        filenames, deep=cleanup_on_exit,
                                        restore_files=disable_prevent_destroy)
     setup_output = self.init(plugin_dir=plugin_dir, init_vars=init_vars,
-                             backend=backend, **kw)
+                             backend=backend, use_cache=use_cache, **kw)
     if workspace_name:
       setup_output += self.workspace(name=workspace_name)
     return setup_output
 
+  @_cache
   def init(self, input=False, color=False, force_copy=False, plugin_dir=None,
-           init_vars=None, backend=True, **kw):
+           init_vars=None, backend=True, use_cache=False, **kw):
     """Run Terraform init command."""
     cmd_args = parse_args(input=input, color=color, backend=backend,
                           force_copy=force_copy, plugin_dir=plugin_dir,
@@ -462,8 +540,9 @@ def workspace(self, name=None):
       cmd_args = ['new', name]
     return self.execute_command('workspace', *cmd_args).out
 
+  @_cache
   def plan(self, input=False, color=False, refresh=True, tf_vars=None,
-           targets=None, output=False, tf_var_file=None, **kw):
+           targets=None, output=False, tf_var_file=None, use_cache=False, **kw):
     """
     Run Terraform plan command, optionally returning parsed plan output.
 
@@ -496,8 +575,9 @@ def plan(self, input=False, color=False, refresh=True, tf_vars=None,
     except json.JSONDecodeError as e:
       raise TerraformTestError('Error decoding plan output: {}'.format(e))
 
+  @_cache
   def apply(self, input=False, color=False, auto_approve=True, tf_vars=None,
-            targets=None, tf_var_file=None, **kw):
+            targets=None, tf_var_file=None, use_cache=False, **kw):
     """
     Run Terraform apply command.
 
@@ -515,7 +595,8 @@ def apply(self, input=False, color=False, auto_approve=True, tf_vars=None,
                           tf_var_file=tf_var_file, **kw)
     return self.execute_command('apply', *cmd_args).out
 
-  def output(self, name=None, color=False, json_format=True, **kw):
+  @_cache
+  def output(self, name=None, color=False, json_format=True, use_cache=False, **kw):
     """Run Terraform output command."""
     cmd_args = []
     if name:
@@ -530,8 +611,9 @@ def output(self, name=None, color=False, json_format=True, **kw):
         _LOGGER.warning('error decoding output: {}'.format(e))
     return output
 
+  @_cache
   def destroy(self, color=False, auto_approve=True, tf_vars=None, targets=None,
-              tf_var_file=None, **kw):
+              tf_var_file=None, use_cache=False, **kw):
     """Run Terraform destroy command."""
     cmd_args = parse_args(color=color, auto_approve=auto_approve,
                           tf_vars=tf_vars, targets=targets,
@@ -612,7 +694,7 @@ def _parse_run_all_out(output: str, formatter: TerraformJSONBase) -> str:
 class TerragruntTest(TerraformTest):
 
   def __init__(self, tfdir, basedir=None, binary='terragrunt', env=None,
-               tg_run_all=False):
+               tg_run_all=False, enable_cache=False, cache_dir=None):
     """A helper class that could be used for testing terragrunt
 
     Most operations that apply to :func:`~TerraformTest` also apply to this class.
@@ -629,8 +711,12 @@ def __init__(self, tfdir, basedir=None, binary='terragrunt', env=None,
       binary: (Optional) path to terragrunt command.
       env: a dict with custom environment variables to pass to terraform.
       tg_run_all: whether the test is for terragrunt run-all, default to False
+      enable_cache: Determines if the caching enabled for specific methods
+      cache_dir: optional base directory to use for caching, defaults to
+        the directory of the python file that instantiates this class
     """
-    TerraformTest.__init__(self, tfdir, basedir, binary, env)
+    TerraformTest.__init__(self, tfdir, basedir, binary,
+                           env, enable_cache, cache_dir)
     self.tg_run_all = tg_run_all
     if self.tg_run_all:
       self._plan_formatter = partial(_parse_run_all_out,