Terraform Testing - Folder Structure Question

I am exploring the terraform test functionality and have run into an issue I was hoping someone could shed some light on. My root of the module repository has three folders. First examples contain use cases where we are sourcing the local module and able to run it for that particular use case. It’s a quick way for users who are new to the module can see what all it can do and understand what to pass in to accomplish the goal. The second is the src folder. This folder contains the source code for the module. When it bring it in from the main code base we reference the git URL and this folder. The final folder is the test folder. The idea was to add tests to this folder and iterate through the examples folder with run blocks for each example. A visual representation is something like what is below.

—use case 1
—use case 2

What I am running into is when I run terraform init in the tests folder, it doesn’t pull in the module. In my run block I do have a source with a relative path to the examples folder I’m trying to run again. The only way I’ve been able to run this is combine the examples and source folder into a single folder then run it or eliminate the src folder altogether.

does anyone know how to accomplish this or is having a folder structure a no go with terraform test?

Hi @awworrell,

The test harness expects to find the .tftest.hcl files either in the same directory as the module or in a subdirectory called tests.

You would then run terraform init in the module directory, not the test directory. The init command prepares the directory with the dependencies needed for both the module itself and its tests.

A sibling directory called src is not an idiomatic Terraform directory layout. The usual structure is for the .tf files for the module to appear in the root directory, and then put other items like examples in subdirectories.

Hey Mart,

Thanks for the explanation. I have a couple of questions, though. First, when you say that the hcl files need to be in the same directory or in subdirectory called tests, is that from the perspective of the root of the repository or could tests be a subdirectory of examples?

Second, while it’s not an idiomatic terraform layout to have a src directory, we found it more accessible for new people using our modules for the first time to have a level of separation between the source code and how to implement it. Within the test itself, there is a source argument. What is the difference in functionality between that argument and sourcing a module? They do not seem to operate in the same way.

Thanks for the help.

Terraform cannot “see” where your repository root is, so from Terraform’s perspective all that matters is where the files are in relation to the module directory, which is the one containing the .tf files.

The terraform test command was intended to be run from within the directory of the module that’s being tested, rather than in the directory containing its tests.

The test harness does support specifying a different module to use for a particular “run”. That mechanism was intended to allow writing a test for how the target module behaves when it’s called from another module. For example, in your case it could be useful to write tests for your main module that exercise it indirectly through your examples, so that you can test that the module remains compatible with how the example was written, but you’d still run terraform test in the directory containing the main module.

If you want to retain that src directory then I think the most straightforward option would be to move tests to be nested within it, as src/tests. Then you’d run terraform init and terraform test from the src directory, so that Terraform can find both the module being tested and the tests for that module.