From 2b4f485d72efbc85e580e8a8810f84657c2097dd Mon Sep 17 00:00:00 2001
From: Muhammad Atif Ali <me@matifali.dev>
Date: Fri, 8 Aug 2025 17:44:59 +0500
Subject: [PATCH] docs: update docs and samples to use terraform test; route
 npm test to terraform runner; no direct pushes to main

---
 CONTRIBUTING.md                         | 27 +++++++++++++++----------
 MAINTAINER.md                           |  4 ++--
 examples/modules/MODULE_NAME.tftest.hcl | 21 +++++++++++++++++++
 package.json                            |  2 +-
 4 files changed, 40 insertions(+), 14 deletions(-)
 create mode 100644 examples/modules/MODULE_NAME.tftest.hcl

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3b2b4d1e..44ac9ab0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ The Coder Registry is a collection of Terraform modules and templates for Coder
 
 ### Install Dependencies
 
-Install Bun:
+Install Bun (for formatting and scripts):
 
 ```bash
 curl -fsSL https://bun.sh/install | bash
@@ -124,19 +124,23 @@ This script generates:
    - Accurate description and usage examples
    - Correct icon path (usually `../../../../.icons/your-icon.svg`)
    - Proper tags that describe your module
-3. **Create `main.test.ts`** to test your module
+3. **Create at least one `.tftest.hcl`** to test your module with `terraform test`
 4. **Add any scripts** or additional files your module needs
 
 ### 4. Test and Submit
 
 ```bash
-# Test your module
-bun test -t 'module-name'
+# Test your module (from the module directory)
+terraform init -upgrade
+terraform test -verbose
+
+# Or run all tests in the repo
+./scripts/terraform_test_all.sh
 
 # Format code
-bun fmt
+bun run fmt
 
-# Commit and create PR
+# Commit and create PR (do not push to main directly)
 git add .
 git commit -m "Add [module-name] module"
 git push origin your-branch
@@ -335,11 +339,12 @@ coder templates push test-[template-name] -d .
 ### 2. Test Your Changes
 
 ```bash
-# Test a specific module
-bun test -t 'module-name'
+# Test a specific module (from the module directory)
+terraform init -upgrade
+terraform test -verbose
 
 # Test all modules
-bun test
+./scripts/terraform_test_all.sh
 ```
 
 ### 3. Maintain Backward Compatibility
@@ -388,7 +393,7 @@ Example: `https://github.com/coder/registry/compare/main...your-branch?template=
 ### Every Module Must Have
 
 - `main.tf` - Terraform code
-- `main.test.ts` - Working tests
+- One or more `.tftest.hcl` files - Working tests with `terraform test`
 - `README.md` - Documentation with frontmatter
 
 ### Every Template Must Have
@@ -488,6 +493,6 @@ When reporting bugs, include:
 2. **No tests** or broken tests
 3. **Hardcoded values** instead of variables
 4. **Breaking changes** without defaults
-5. **Not running** `bun fmt` before submitting
+5. **Not running** formatting (`bun run fmt`) and tests (`terraform test`) before submitting
 
 Happy contributing! 🚀
diff --git a/MAINTAINER.md b/MAINTAINER.md
index 22326574..9959e59c 100644
--- a/MAINTAINER.md
+++ b/MAINTAINER.md
@@ -18,9 +18,9 @@ sudo apt install golang-go
 
 Check that PRs have:
 
-- [ ] All required files (`main.tf`, `main.test.ts`, `README.md`)
+- [ ] All required files (`main.tf`, `README.md`, at least one `.tftest.hcl`)
 - [ ] Proper frontmatter in README
-- [ ] Working tests (`bun test`)
+- [ ] Working tests (`terraform test`)
 - [ ] Formatted code (`bun run fmt`)
 - [ ] Avatar image for new namespaces (`avatar.png` or `avatar.svg` in `.images/`)
 
diff --git a/examples/modules/MODULE_NAME.tftest.hcl b/examples/modules/MODULE_NAME.tftest.hcl
new file mode 100644
index 00000000..6f11666b
--- /dev/null
+++ b/examples/modules/MODULE_NAME.tftest.hcl
@@ -0,0 +1,21 @@
+run "plan_with_required_vars" {
+  command = plan
+
+  variables {
+    agent_id = "example-agent-id"
+  }
+}
+
+run "app_url_uses_port" {
+  command = plan
+
+  variables {
+    agent_id = "example-agent-id"
+    port     = 19999
+  }
+
+  assert {
+    condition     = resource.coder_app.MODULE_NAME.url == "http://localhost:19999"
+    error_message = "Expected MODULE_NAME app URL to include configured port"
+  }
+}
diff --git a/package.json b/package.json
index 7ca9f2ec..c2f9ff69 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
     "fmt": "bun x prettier --write **/*.sh **/*.ts **/*.md *.md && terraform fmt -recursive -diff",
     "fmt:ci": "bun x prettier --check **/*.sh **/*.ts **/*.md *.md && terraform fmt -check -recursive -diff",
     "terraform-validate": "./scripts/terraform_validate.sh",
-    "test": "bun test",
+    "test": "./scripts/terraform_test_all.sh",
     "update-version": "./update-version.sh"
   },
   "devDependencies": {