chore: support generating Go Examples

modulegen/_template/examples_test.go.tmpl

@@ -0,0 +1,36 @@
+{{ $entrypoint := Entrypoint }}{{ $lower := ToLower }}{{ $title := Title }}package {{ $lower }}_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/testcontainers/testcontainers-go/modules/{{ $lower }}"
+)
+
+func Example{{ $entrypoint }}() {
+	// run{{ $title }}Container {
+	ctx := context.Background()
+
+	{{ $lower }}Container, err := {{ $lower }}.{{ $entrypoint }}(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	// Clean up the container after the test is complete
+	defer func() {
+		if err := {{ $lower }}Container.Terminate(ctx); err != nil {
+			panic(err)
+		}
+	}()
+	// }
+
+	state, err := {{ $lower }}Container.State(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(state.Running)
+
+	// Output:
+	// true
+}

modulegen/_template/module.md.tmpl

@@ -17,11 +17,7 @@ go get github.com/testcontainers/testcontainers-go/{{ ParentDir }}/{{ $lower }}
 ## Usage example
 
 <!--codeinclude-->
-[Creating a {{ $title }} container](../../{{ ParentDir }}/{{ $lower }}/{{ $lower }}.go)
-<!--/codeinclude-->
-
-<!--codeinclude-->
-[Test for a {{ $title }} container](../../{{ ParentDir }}/{{ $lower }}/{{ $lower }}_test.go)
+[Creating a {{ $title }} container](../../{{ ParentDir }}/{{ $lower }}/examples_test.go) inside_block:run{{ $title }}Container
 <!--/codeinclude-->
 
 ## Module reference

modulegen/internal/module/main.go

@@ -52,7 +52,7 @@ func generateGoModFile(moduleDir string, tcModule context.TestcontainersModule)
 }
 
 func GenerateFiles(moduleDir string, moduleName string, funcMap template.FuncMap, tcModule any) error {
-	for _, tmpl := range []string{"module_test.go", "module.go"} {
+	for _, tmpl := range []string{"examples_test.go", "module_test.go", "module.go"} {
 		name := tmpl + ".tmpl"
 		t, err := template.New(name).Funcs(funcMap).ParseFiles(filepath.Join("_template", name))
 		if err != nil {

modulegen/main_test.go

@@ -292,6 +292,7 @@ func TestGenerate(t *testing.T) {
 	assertModuleGithubWorkflowContent(t, module, mainWorkflowFile)
 
 	generatedTemplatesDir := filepath.Join(examplesTmp, moduleNameLower)
+	assertExamplesTestContent(t, module, filepath.Join(generatedTemplatesDir, "examples_test.go"))
 	assertModuleTestContent(t, module, filepath.Join(generatedTemplatesDir, moduleNameLower+"_test.go"))
 	assertModuleContent(t, module, filepath.Join(generatedTemplatesDir, moduleNameLower+".go"))
 	assertGoModContent(t, module, originalConfig.Extra.LatestVersion, filepath.Join(generatedTemplatesDir, "go.mod"))
@@ -354,6 +355,7 @@ func TestGenerateModule(t *testing.T) {
 	assertModuleGithubWorkflowContent(t, module, mainWorkflowFile)
 
 	generatedTemplatesDir := filepath.Join(modulesTmp, moduleNameLower)
+	assertExamplesTestContent(t, module, filepath.Join(generatedTemplatesDir, "examples_test.go"))
 	assertModuleTestContent(t, module, filepath.Join(generatedTemplatesDir, moduleNameLower+"_test.go"))
 	assertModuleContent(t, module, filepath.Join(generatedTemplatesDir, moduleNameLower+".go"))
 	assertGoModContent(t, module, originalConfig.Extra.LatestVersion, filepath.Join(generatedTemplatesDir, "go.mod"))
@@ -410,14 +412,31 @@ func assertModuleDocContent(t *testing.T, module context.TestcontainersModule, m
 	assert.Equal(t, data[10], "Please run the following command to add the "+title+" module to your Go dependencies:")
 	assert.Equal(t, data[13], "go get github.com/testcontainers/testcontainers-go/"+module.ParentDir()+"/"+lower)
 	assert.Equal(t, data[18], "<!--codeinclude-->")
-	assert.Equal(t, data[19], "[Creating a "+title+" container](../../"+module.ParentDir()+"/"+lower+"/"+lower+".go)")
+	assert.Equal(t, data[19], "[Creating a "+title+" container](../../"+module.ParentDir()+"/"+lower+"/examples_test.go)inside_block:run"+title+"Container")
 	assert.Equal(t, data[20], "<!--/codeinclude-->")
-	assert.Equal(t, data[22], "<!--codeinclude-->")
-	assert.Equal(t, data[23], "[Test for a "+title+" container](../../"+module.ParentDir()+"/"+lower+"/"+lower+"_test.go)")
-	assert.Equal(t, data[24], "<!--/codeinclude-->")
-	assert.Equal(t, data[28], "The "+title+" module exposes one entrypoint function to create the "+title+" container, and this function receives two parameters:")
-	assert.True(t, strings.HasSuffix(data[31], "(*"+title+"Container, error)"))
-	assert.Equal(t, "for "+title+". E.g. `testcontainers.WithImage(\""+module.Image+"\")`.", data[44])
+	assert.Equal(t, data[24], "The "+title+" module exposes one entrypoint function to create the "+title+" container, and this function receives two parameters:")
+	assert.True(t, strings.HasSuffix(data[27], "(*"+title+"Container, error)"))
+	assert.Equal(t, "for "+title+". E.g. `testcontainers.WithImage(\""+module.Image+"\")`.", data[40])
+}
+
+// assert content module test
+func assertExamplesTestContent(t *testing.T, module context.TestcontainersModule, examplesTestFile string) {
+	content, err := os.ReadFile(examplesTestFile)
+	assert.Nil(t, err)
+
+	lower := module.Lower()
+	entrypoint := module.Entrypoint()
+	title := module.Title()
+
+	data := sanitiseContent(content)
+	assert.Equal(t, data[0], "package "+lower+"_test")
+	assert.Equal(t, data[6], "\t\"github.com/testcontainers/testcontainers-go/modules/"+lower+"\"")
+	assert.Equal(t, data[9], "func Example"+entrypoint+"() {")
+	assert.Equal(t, data[10], "\t// run"+title+"Container {")
+	assert.Equal(t, data[13], "\t"+lower+"Container, err := "+lower+"."+entrypoint+"(ctx)")
+	assert.Equal(t, data[31], "\tfmt.Println(state.Running)")
+	assert.Equal(t, data[33], "\t// Output:")
+	assert.Equal(t, data[34], "\t// true")
 }
 
 // assert content module test

modules/elasticsearch/examples_test.go

@@ -20,11 +20,18 @@ func ExampleRunContainer() {
 		panic(err)
 	}
 	defer func() {
-		_ = elasticsearchContainer.Terminate(ctx)
+		if err := elasticsearchContainer.Terminate(ctx); err != nil {
+			panic(err)
+		}
 	}()
 	// }
 
-	fmt.Println(strings.HasPrefix(elasticsearchContainer.Settings.Address, "https://"))
+	state, err := elasticsearchContainer.State(ctx)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(state.Running)
 
 	// Output:
 	// true