`terraform test`: using `-test-directory` breaks module initialization

[edgetools]

Terraform Version

> terraform version
Terraform v1.14.0
on darwin_arm64

Terraform Configuration Files

command:

terraform init

directory structure:

tests/modules/foo/main.tf
tests/subdir/test_foo.tftest.hcl

tests/modules/foo/main.tf:

resource "time_sleep" "wait_5_seconds" {
  create_duration = "5s"
}

tests/subdir/test_foo.tftest.hcl:

run "use_foo_module" {
  module {
    source = "./tests/modules/foo"
  }
}

Debug Output

> terraform init
2025-12-03T14:49:34.525-0600 [INFO]  Terraform version: 1.14.0
2025-12-03T14:49:34.525-0600 [DEBUG] using github.com/hashicorp/go-tfe v1.94.0
2025-12-03T14:49:34.525-0600 [DEBUG] using github.com/hashicorp/hcl/v2 v2.24.0
2025-12-03T14:49:34.525-0600 [DEBUG] using github.com/hashicorp/terraform-svchost v0.1.1
2025-12-03T14:49:34.525-0600 [DEBUG] using github.com/zclconf/go-cty v1.16.3
2025-12-03T14:49:34.525-0600 [INFO]  Go runtime version: go1.25.4
2025-12-03T14:49:34.525-0600 [INFO]  CLI args: []string{"/Users/[REDACTED]/.config/tfenv/versions/1.14.0/terraform", "init"}
2025-12-03T14:49:34.525-0600 [TRACE] Stdout is a terminal of width 186
2025-12-03T14:49:34.525-0600 [TRACE] Stderr is a terminal of width 186
2025-12-03T14:49:34.525-0600 [TRACE] Stdin is a terminal
2025-12-03T14:49:34.525-0600 [DEBUG] Attempting to open CLI config file: /Users/[REDACTED]/.terraformrc
2025-12-03T14:49:34.525-0600 [DEBUG] File doesn't exist, but doesn't need to. Ignoring.
2025-12-03T14:49:34.525-0600 [DEBUG] ignoring non-existing provider search directory terraform.d/plugins
2025-12-03T14:49:34.525-0600 [DEBUG] ignoring non-existing provider search directory /Users/[REDACTED]/.terraform.d/plugins
2025-12-03T14:49:34.525-0600 [DEBUG] ignoring non-existing provider search directory /Users/[REDACTED]/Library/Application Support/io.terraform/plugins
2025-12-03T14:49:34.525-0600 [DEBUG] ignoring non-existing provider search directory /Library/Application Support/io.terraform/plugins
2025-12-03T14:49:34.525-0600 [INFO]  CLI command args: []string{"init"}
Terraform initialized in an empty directory!

The directory has no Terraform configuration files. You may begin working
with Terraform immediately by creating Terraform configuration files.

Expected Behavior

terraform initializes modules for tests in the tests/subdir directory

Actual Behavior

terraform does not see the modules and never initializes them

Steps to Reproduce

1. terraform init

Additional Context

This issue requires some context:

Currently, terraform documentation indicates that the tests directory is the defacto standard and expected directory for putting tests.

https://developer.hashicorp.com/terraform/cli/commands/test#alternate-test-directories

We do not recommend changing the default test directory. The option for customization is included for configuration authors who may have included a tests submodule in their configuration before the terraform test command was released. In general, the default test directory of tests should always be used.

It's common to need to separate test runs between unit tests and integration tests (or other classes of tests), as unit tests often have less requirements than integration tests and provide faster feedback.

Terraform currently supports the -filter and -test-directory options as ways of narrowing or filtering test runs.

The -filter option does not work with globs (*), meaning that it's not possible to specify a prefix or multi-file filter using that switch. (e.g. -filter=ut_* to match all files starting with ut_). This would allow keeping all tests in the base tests/ directory.

As a workaround to the lack of a wildcard -filter option, I tried putting my unit and integration tests into separate directories.

e.g.

tests/ut and tests/it

and then added -test-directory to be able to narrow the test runs:

terraform test -test-directory=tests/ut

terraform test -test-directory=tests/it

both of these test categories need to be able to access test modules located in tests/modules/*

Currently, if the test files are located directly under tests/, then terraform init is able to detect their references to other test modules, and perform the initialization for those modules.

However, once the tests are located inside a subdir of tests/ (such as tests/ut or tests/it), then terraform init no longer recognizes the module references and fails to initialize the modules.

This breaks from the clean/simple pattern of running terraform init on the root directory to initialize the project and its tests.

In general, the story for classifying different tests into different runs seems immature at the moment.

Compare this to something like python unittest discover which allows nesting tests at various directory levels and surface them through a single command. I would have expected terraform test -filter to work similar to that.

The only workaround I can think of right now is to keep all tests in tests/ and then wrap my terraform test command with automation that will do an ls tests/it_*.tftest.hcl and then for each result, add every file with its own -filter switch: -filter=tests/it_foo.tftest.hcl -filter=tests/it_bar.tftest.hcl, etc.

So this is sort of a bug report and feature request. If it's expected that all test files should be located at a flat level directly inside tests/, then -filter should be enhanced to allow for globbing or pattern matching.

If instead it is better to use folders to organize tests, then terraform init needs to be able to discover module references within nested tests.

edit: it should also be noted that keeping all ut_ and it_ tests in the base tests/ dir and then having every module needed get initialized at once might also not be ideal. For fast feedback, ideally the terraform init could be limited to just resources needed for the tests that will be ran with a scoped terraform test. e.g. It would be nice to do init just for unit tests, and then after that passes, do init for integration tests (or system tests, etc). Requirements between unit and integration runs is often different, but sharing modules is still useful, so I don't want to have to maintain a completely separate copy of test modules for each use case, but I'd like to be able to initialize them separately based on which tests I'm going to run.

References

No response

Generative AI / LLM assisted development?

N/A

[crw]

Thanks for this report! As I suspect this will be reclassified as a feature request, I will also add the relevant comment:

Thanks for this feature request! If you are viewing this issue and would like to indicate your interest, please use the 👍 reaction on the issue description to upvote this issue. We also welcome additional use case descriptions. Thanks again!