feat: provide a tool to generate examples from code

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
         run: go mod verify
 
       - name: modTidy
-        run: go mod tidy
+        run: make tools-tidy
 
       - name: ensure compilation
         env:
@@ -43,6 +43,10 @@ jobs:
         if: ${{ matrix.platform == 'ubuntu-latest' }}
         run: make -C e2e tools-tidy
 
+      - name: Run example generator tests
+        if: ${{ matrix.platform == 'ubuntu-latest' }}
+        run: make -C examples test-unit
+
       - name: Run e2e tests
         if: ${{ matrix.platform == 'ubuntu-latest' }}
         run: make test-e2e

.github/workflows/cockroachdb-example.yml

@@ -0,0 +1,42 @@
+name: Cockroachdb example pipeline
+
+on: [push, pull_request]
+
+jobs:
+  test-cockroachdb:
+    strategy:
+      matrix:
+        go-version: [1.18.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./examples/cockroachdb
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./examples/cockroachdb
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./examples/cockroachdb
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-cockroachdb*.xml"
+        if: always()

.github/workflows/nginx-example.yml

@@ -0,0 +1,42 @@
+name: Nginx example pipeline
+
+on: [push, pull_request]
+
+jobs:
+  test-nginx:
+    strategy:
+      matrix:
+        go-version: [1.18.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./examples/nginx
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./examples/nginx
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./examples/nginx
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-nginx*.xml"
+        if: always()

.github/workflows/pulsar-example.yml

@@ -0,0 +1,42 @@
+name: Pulsar example pipeline
+
+on: [push, pull_request]
+
+jobs:
+  test-pulsar:
+    strategy:
+      matrix:
+        go-version: [1.18.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./examples/pulsar
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./examples/pulsar
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./examples/pulsar
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-pulsar*.xml"
+        if: always()

.github/workflows/redis-example.yml

@@ -0,0 +1,42 @@
+name: Redis example pipeline
+
+on: [push, pull_request]
+
+jobs:
+  test-redis:
+    strategy:
+      matrix:
+        go-version: [1.18.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./examples/redis
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./examples/redis
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./examples/redis
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-redis*.xml"
+        if: always()

Makefile

@@ -1,21 +1,14 @@
+include ./commons-test.mk
 
 .PHONY: test-all
 test-all: tools test-unit test-e2e
 
-.PHONY: test-unit
-test-unit:
-	@echo "Running unit tests..."
-	go run gotest.tools/gotestsum \
-		--format short-verbose \
-		--rerun-fails=5 \
-		--packages="./..." \
-		--junitfile TEST-unit.xml
-
 .PHONY: test-e2e
 test-e2e:
 	@echo "Running end-to-end tests..."
 	make -C e2e test
 
-.PHONY: tools
-tools:
-	go mod download
+.PHONY: test-examples
+test-examples:
+	@echo "Running example tests..."
+	make -C examples test

commons-test.mk

@@ -0,0 +1,16 @@
+.PHONY: test-%
+test-%:
+	@echo "Running $* tests..."
+	go run gotest.tools/gotestsum \
+		--format short-verbose \
+		--rerun-fails=5 \
+		--packages="./..." \
+		--junitfile TEST-$*.xml
+
+.PHONY: tools
+tools:
+	go mod download
+
+.PHONY: tools-tidy
+tools-tidy:
+	go mod tidy

docs/examples/cockroachdb.md

@@ -1,148 +1,9 @@
 # CockroachDB
 
-```go
-package main
+<!--codeinclude-->
+[Creating a CockroachDB container](../../examples/cockroachdb/cockroachdb.go)
+<!--/codeinclude-->
 
-import (
-	"context"
-	"database/sql"
-	"fmt"
-	"testing"
-	"time"
-
-	"github.com/google/go-cmp/cmp"
-	"github.com/google/uuid"
-	_ "github.com/jackc/pgx/v4/stdlib"
-	"github.com/testcontainers/testcontainers-go"
-	"github.com/testcontainers/testcontainers-go/wait"
-)
-
-// Task represents a unit of work to complete. We're going to be using this in
-// our example as a way to organize data that is being manipulated in
-// the database.
-type task struct {
-	ID          string     `json:"id"`
-	Description string     `json:"description"`
-	DateDue     *time.Time `json:"date_due,string"`
-	DateCreated time.Time  `json:"date_created,string"`
-	DateUpdated time.Time  `json:"date_updated"`
-}
-
-type cockroachDBContainer struct {
-	testcontainers.Container
-	URI string
-}
-
-func setupCockroachDB(ctx context.Context) (*cockroachDBContainer, error) {
-	req := testcontainers.ContainerRequest{
-		Image:        "cockroachdb/cockroach:latest-v21.1",
-		ExposedPorts: []string{"26257/tcp", "8080/tcp"},
-		WaitingFor:   wait.ForHTTP("/health").WithPort("8080"),
-		Cmd:          []string{"start-single-node", "--insecure"},
-	}
-	container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
-		ContainerRequest: req,
-		Started:          true,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	mappedPort, err := container.MappedPort(ctx, "26257")
-	if err != nil {
-		return nil, err
-	}
-
-	hostIP, err := container.Host(ctx)
-	if err != nil {
-		return nil, err
-	}
-
-	uri := fmt.Sprintf("postgres://root@%s:%s", hostIP, mappedPort.Port())
-
-	return &cockroachDBContainer{Container: container, URI: uri}, nil
-}
-
-func initCockroachDB(ctx context.Context, db sql.DB) error {
-	// Actual SQL for initializing the database should probably live elsewhere
-	const query = `CREATE DATABASE projectmanagement;
-		CREATE TABLE projectmanagement.task(
-			id uuid primary key not null,
-			description varchar(255) not null,
-			date_due timestamp with time zone,
-			date_created timestamp with time zone not null,
-			date_updated timestamp with time zone not null);`
-	_, err := db.ExecContext(ctx, query)
-
-	return err
-}
-
-func truncateCockroachDB(ctx context.Context, db sql.DB) error {
-	const query = `TRUNCATE projectmanagement.task`
-	_, err := db.ExecContext(ctx, query)
-	return err
-}
-
-func TestIntegrationDBInsertSelect(t *testing.T) {
-	if testing.Short() {
-		t.Skip("Skipping integration test")
-	}
-
-	ctx := context.Background()
-
-	cdbContainer, err := setupCockroachDB(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(func() {
-		if err := cdbContainer.Terminate(ctx); err != nil {
-			t.Fatalf("failed to terminate container: %s", err)
-		}
-	})
-
-	db, err := sql.Open("pgx", cdbContainer.URI+"/projectmanagement")
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer db.Close()
-
-	err = initCockroachDB(ctx, *db)
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer truncateCockroachDB(ctx, *db)
-
-	now := time.Now()
-
-	// Insert data
-	tsk := task{ID: uuid.NewString(), Description: "Update resumé", DateCreated: now, DateUpdated: now}
-	const insertQuery = `insert into "task" (id, description, date_due, date_created, date_updated)
-		values ($1, $2, $3, $4, $5)`
-	_, err = db.ExecContext(
-		ctx,
-		insertQuery,
-		tsk.ID,
-		tsk.Description,
-		tsk.DateDue,
-		tsk.DateCreated,
-		tsk.DateUpdated)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	// Select data
-	savedTsk := task{ID: tsk.ID}
-	const findQuery = `select description, date_due, date_created, date_updated
-		from task
-		where id = $1`
-	row := db.QueryRowContext(ctx, findQuery, tsk.ID)
-	err = row.Scan(&savedTsk.Description, &savedTsk.DateDue, &savedTsk.DateCreated, &savedTsk.DateUpdated)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	if !cmp.Equal(tsk, savedTsk) {
-		t.Fatalf("Saved task is not the same:\n%s", cmp.Diff(tsk, savedTsk))
-	}
-}
-```
+<!--codeinclude-->
+[Test for a CockroachDB container](../../examples/cockroachdb/cockroachdb_test.go)
+<!--/codeinclude-->