gotenberg/test/integration/README.md

Integration Tests

Gherkin (BDD) via Godog, with testcontainers-go for Docker orchestration.

• Feature files: test/integration/features/*.feature, one per endpoint or capability.
• Step definitions: test/integration/scenario/ (container management, HTTP helpers, PDF validation).
• Entry point: test/integration/main_test.go (build tag: integration).
• Test data: test/integration/testdata/.

Each scenario spins up a fresh Gotenberg Docker container via testcontainers. A separate gotenberg/integration-tools container provides PDF validation tools (verapdf, pdfinfo, pdftotext).

Run make build before make test-integration. Integration tests require a Docker image.

Selective runs

make test-integration TAGS=health
make test-integration TAGS=chromium-convert-html
make test-integration TAGS="merge,split"
make test-integration NO_CONCURRENCY=true  # disable parallel scenarios
make test-integration PLATFORM=linux/arm64 # force a specific platform

Available tags:

Group	Tags
Chromium	chromium, chromium-concurrent, chromium-convert-html, chromium-convert-markdown, chromium-convert-url, chromium-screenshot-html, chromium-screenshot-markdown, chromium-screenshot-url
LibreOffice	libreoffice, libreoffice-convert
PDF Engines	pdfengines, pdfengines-convert, pdfengines-merge, merge, pdfengines-split, split, pdfengines-flatten, flatten, pdfengines-rotate, rotate, pdfengines-embed, embed, pdfengines-encrypt, encrypt, pdfengines-watermark, watermark, pdfengines-stamp, stamp, pdfengines-metadata, metadata, pdfengines-bookmarks, bookmarks
Infra	health, debug, root, version, output-filename, prometheus-metrics, webhook, download-from

Writing a new test

1. Create or update a .feature file in test/integration/features/.
2. Tag it appropriately (e.g., @chromium @chromium-convert-html).
3. For new tags, add them to both the TAGS comment block in the Makefile and the table above.
4. For new step definitions, add the function to scenario/scenario.go, register it in InitializeScenario, and add the step pattern to the step reference below.
5. Test data goes in test/integration/testdata/.

Step reference

Given (setup)

• I have a default Gotenberg container
• I have a Gotenberg container with the following environment variable(s): (table: key | value)
• I have a (webhook|static) server

When (action)

• I make a "(GET|HEAD)" request to Gotenberg at the "<endpoint>" endpoint
• I make a "(GET|HEAD)" request to Gotenberg at the "<endpoint>" endpoint with the following header(s): (table: name | value)
• I make a "(POST)" request to Gotenberg at the "<endpoint>" endpoint with the following form data and header(s): (table: name | value | kind, where kind is file, field, or header)
• I make <N> concurrent "(POST)" requests to Gotenberg at the "<endpoint>" endpoint with the following form data and header(s): (same table format)
• I wait for the asynchronous request to the webhook

Then (assertions)

• the response status code should be <code>
• the (response|webhook request|file request|server request) header "<name>" should be "<value>"
• the (response|webhook request|file request|server request) cookie "<name>" should be "<value>"
• the (response|webhook request) body should match string: (docstring)
• the (response|webhook request) body should contain string: (docstring)
• the (response|webhook request) body should match JSON: (docstring, use "ignore" for dynamic values)
• the webhook event should match JSON: (docstring, use "ignore" for dynamic values; polls for up to 5s)
• there should be <N> PDF(s) in the (response|webhook request)
• there should be the following file(s) in the (response|webhook request): (table of filenames)
• the "<name>" PDF should have <N> page(s)
• the "<name>" PDF (should|should NOT) be set to landscape orientation
• the "<name>" PDF (should|should NOT) have the following content at page <N>: (docstring)
• the "<name>" PDF (should|should NOT) have content matching "<regexp>" at page <N>
• the (response|webhook request) PDF(s) should be valid "<standard>" with a tolerance of <N> failed rule(s) (standards: PDF/A-1b, PDF/A-2b, PDF/A-3b, PDF/UA-1, PDF/UA-2)
• the (response|webhook request) PDF(s) (should|should NOT) be flatten
• the (response|webhook request) PDF(s) (should|should NOT) be encrypted
• the (response|webhook request) PDF(s) (should|should NOT) allow "<action>" (actions: printing, copying, modifying, annotating)
• the (response|webhook request) PDF(s) (should|should NOT) have the "<filename>" file embedded
• the "<name>" PDF should have <N> image(s)
• the Gotenberg container (should|should NOT) log the following entries: (table of log substrings)
• all concurrent response status codes should be <code>
• all concurrent responses should have <N> PDF(s)