Implement acceptance tests / BDD style tests

Use a flat hierarchy for the tests. No packages, only *_test.go files that map to the filenames of the feature files in the main package of module github.com/sommerfeld-io/source2adoc-acceptance-tests

Todo Set from Before ADR

[x] Setup basic BDD test with godog and run locally
[x] Write BDD style tests with Go Dog for the basic features from the root command
[x] Write BDD style tests with Go Dog for the --exclude feature
[x] Can I pass the image to run as an argument? This way I can use local/source2adoc:dev locally and use :commit-sha and :rc images from pipeline.
[x] Should I create dedicated *_test.go files (one per feature) or should I combine every test in a single acceptance_test.go file? Ask ChatGPT and Copilot.
[x] Run locally against Docker image
- [x] Mount volumes - :telescope: https://stackoverflow.com/questions/78917880/how-can-i-test-file-system-outputs-in-a-docker-container-using-go-when-bind-volu
[x] Run from pipeline.yml against Docker image (:commit-sha and :rc) using CONTAINER_IMAGE=sommerfeldio/source2adoc:<THE_TAG> go test
[x] Run from release.yml against Docker image (:latest) using CONTAINER_IMAGE=sommerfeldio/source2adoc:latest go test
[x] Document the BDD approach and how to run from pipeline using CONTAINER_IMAGE=sommerfeldio/source2adoc:rc go test and how to run locally and explain that local/source2adoc:dev is default because this allows using the IDE features against a local image
[x] Implement Scenario "Missing mandatory flags" in components/test/acceptance-tests/specs/basic.feature

Refactoring based on ADR

[x] Write ADR and decide: #131
[x] Update Todos in this issue
[x] Combine all (duplicated) go-related pipeline steps into Matrix
[x] Cleanup pipeline (no acceptance test jobs)
[x] Refactor filesystem (components/acceptance-tests and components/compliance-tests or similar)
[x] Run acceptance tests locally against a source2adoc binary from the IDE
- [x] Remove any reference to CONTAINER_IMAGE env var
- [x] Try to simplify. No complex ContainerUnderTest, just some simple command that runs the binary directly from a test case.
  - [x] Assert that the binary is present at the beginning of each test suite

+--------------------+            +--------------------+
|                    |            |                    |
|  Acceptance Tests  +------------+  Acceptance Tests  |
|                    |            |                    |
+--------------------+            |                    |
            ^                     |                    |
            |                     |     +-----------+  |        +--------------+
            +---------------------------+ script.sh |<----------+ devcontainer |
            build binary          |     +-----------+  |        | post start   |
          copy or reference       +--------------------+        +--------------+
      to use in acceptance tests

With docker compose instead of script.sh somehow?
Before the Dockerfile.app build! 
As part of app-test?

[x] Run acceptance tests as part of multistage docker build
[x] Run Inspec only once against :sha images
[x] Checksum Verification: Verify that the image content hasn’t changed after tagging by comparing checksums before and after tagging. If the checksum is the same, tagging was successful.
- [x] Test correct tagging from :sha to :rcby comparing Checksums
- [x] Test correct tagging from :rc to :latestby comparing Checksums
[x] Update Pipeline docs in docs/modules/ROOT/pages/build-and-release.adoc
[x] Document multistage build in Dockerfile.app (with Ditaa diagram) - or link to docs/modules/ROOT/pages/build-and-release.adoc (this might be better because everything will be in one place) ... Or maybe include a partial? But then information is duplicated.
[x] Link from docs/modules/ROOT/pages/build-and-release.adoc to multistage docs from Docker image
[x] Document filesystem structure in docs/modules/ROOT/pages/project-structure.adoc
[x] Decide when to run Docker Scout against which image and update pipeline accordingly (run locally to get a grip)

Follow Up Todos

[ ] #135
[ ] #136
[ ] #137
[x] #138

Chat GPT Conversation about structuring my go test code for acceptance tests

Question

i have some acceptance tests in my go app in a dedicated component. I use gherkin feature files and godog. works fine.

now I wonder how to structure my test code. I have multiple feature files. i like this because it keeps a clear focus. but they all share some steps. as of now 1 have one single acceptance_test.go file. so all step implementations are part of the same file to avoid spreading my functions too far.

would you recommend keeping 1 acceptance_test.go file or would you use a dedicates test.go file for each feature file?

give me pros and cons for both approaches.

Answer

Single `acceptance_test.go` File

Pros

Centralized Management: All step definitions are in one place, making it easier to maintain and locate step implementations.
Avoids Duplication: Sharing step definitions across multiple feature files is straightforward, reducing the likelihood of duplicate code.
Consistent Context: Managing the test state and setup/teardown logic can be more consistent and less error-prone since it's all in one file.
Easier Refactoring: When you need to refactor or update step definitions, you only need to look in one place.

Cons

File Size & Complexity: As the number of feature files and steps grows, this single file can become large and difficult to navigate.
Coupling: Tightly couples all tests together, making it harder to run or work on individual feature files in isolation.
Decreased Modularity: Makes it harder to separate concerns and organize code by feature, potentially leading to a cluttered structure.

**Dedicated `*_test.go` File for Each Feature File**

Pros

Modular Structure: Each feature has its own test file, making it easier to navigate, manage, and understand tests related to a specific feature.
Better Isolation: Easier to run and debug tests for individual features since they are separated into distinct files.
Easier Maintenance: If a feature is removed or significantly changed, you can delete or modify just the corresponding test file without affecting others.
Logical Grouping: Organizes your test code in a way that mirrors your feature files, making the test structure more intuitive.

Cons

Step Duplication Risk: Shared step definitions might need to be repeated across multiple files or managed in a separate file, increasing the risk of duplication.
Complex Shared State Management: Sharing state, setup, or teardown logic across multiple test files can become more complex and harder to maintain.
More Files to Manage: Increases the number of files in your project, which can lead to clutter if not well-organized.
Possible Inconsistencies: There could be inconsistencies in step implementation if the same step is defined differently in different files.

Conclusion

The choice between a single acceptance_test.go file and multiple dedicated test files depends on your project's size, complexity, and team preferences.

Single File: Best for small to medium-sized projects where simplicity and ease of maintenance are more critical than modularity.
Multiple Files: Better for larger projects with many features, where modularity, isolation, and clear organization are more important.

If you find that step definitions are being shared across many features, a middle ground could be to keep shared steps in a separate, common file, and have dedicated test files for feature-specific steps.

sommerfeld-io-archive / source2adoc