[Enhancement]: incomplete documentation for postgres example

[ChristianSch]

Proposal

Hi there,

As the postgres docs are based on the https://github.com/testcontainers/testcontainers-go/blob/7ae3f5ae950813ea3fe1b071f7a17012d222f2dd/modules/postgres/postgres_test.go, it produces code which is unusable. It is not clear what tt is from the context. You can't really know it, as it's rest related. Any change this could get fixed up?

It should really be something along the lines of:

	"github.com/testcontainers/testcontainers-go"
	testpg "github.com/testcontainers/testcontainers-go/modules/postgres"
	"github.com/testcontainers/testcontainers-go/wait"

	container, err := testpg.RunContainer(ctx,
		testcontainers.WithImage("docker.io/postgres:15.2-alpine"),
		testpg.WithDatabase("test"),
		testpg.WithUsername("test"),
		testpg.WithPassword("test"),
		testcontainers.WithWaitStrategy(
			wait.ForLog("database system is ready to accept connections").
				WithOccurrence(2).
				WithStartupTimeout(5*time.Second)),
	)

Instead of:

In theory I'm up for submitting a patch, but I really don't want to meddle with tests and doc generation processes.

[mdelapenya]

Hi @ChristianSch , thanks for the issue report.

We are using a plugin to extract the test code from test files and put it into the markdown files, which is optimal to sync code and documentation. The downside of this is that the test code, as you pointed out, could have references to testing structures (in this case a table, or even the testing library).

We have this issue open: #611, and/but I'd like to also have Go examples, that end up in the pkg.dev documentation site.

Given we want to prioritise code snippets that don't get outdated, and are executed as real tests, I think it would be hard at the moment to unlink those code snippets from the test files.

[sanan-go]

I think for documentation exports, you might consider testable Examples (https://go.dev/blog/examples)
They are also tests, but more readable and complete as snipped. Would it be possible?

At some point, I was going to give up using the postgres module and go with generic container API.
I found this issue after 30 minutes of digging - searching for proper wait strategies from random sources.

[mdelapenya]

I think for documentation exports, you might consider testable Examples (https://go.dev/blog/examples)
They are also tests, but more readable and complete as snipped. Would it be possible?

Exactly, it's in our plans: #1362 (comment)

We have this issue open: #611, and/but I'd like to also have Go examples

Regarding your frustration on finding accurate docs

I was going to give up using the postgres module

I'm really sorry about that, hopefully I can dedicate a full time-slot for fixing all code snippets from the docs, also improving the module generator code to force an module_example.go test file for the Go Examples.

[sanan-go]

@mdelapenya thanks! sorry I missed that line above.
And keeping actual tests linked with documentation is definitely a good thing to have.

[mdelapenya]

@sanan-go @ChristianSch we have added #1600, which will force new modules to include testable examples. Once merged, I'm going to do round of reviews to all modules migrating them to examples.

I'll close this issue once everything is migrated.

Thanks for your support!