molecule-testing

Authoring and debugging gitea_runner molecule scenarios. For running tests use the testing-and-debugging make targets — this covers writing scenarios and fixing DIND/platform issues.

When to Invoke

Adding a molecule scenario for the gitea_runner role
A scenario fails on platform setup, DIND, or registration mocking
Reviewing scenario coverage for a role change

Prerequisites

Docker running locally
.venv exists (make setup)

Scenario Layout

ansible/roles/gitea_runner/molecule/<scenario>/:

Current scenarios: default, template-content, deregister, multi-instance, update, remove, lifecycle.

File	Purpose
`molecule.yml`	driver/platforms/provisioner config
`converge.yml`	applies the role
`verify.yml`	assertions scoped to the scenario
`prepare.yml`	optional host prep

Scenario registration lives in pyproject.toml (scenario map used by devx.molecule distribution in CI) — a new scenario MUST be registered there or CI never runs it.

molecule.yml Conventions

Platform name/image/command are env-overridable via ${MOLECULE_PLATFORM_*} so all-platforms runs work.
remote_tmp: /tmp in provisioner config_options — default temp dir breaks in containers.
ANSIBLE_ROLES_PATH must include the repo roles root.
Use inventory.group_vars to isolate the scenario: disable unrelated features rather than editing tasks.
Runner registration in tests is mocked/faked — scenarios must not require a live Gitea instance; check how existing scenarios stub the registration/token flow before adding API calls.

Debugging

cd ansible/roles/gitea_runner
molecule test -s <scenario>
molecule converge -s <scenario>
molecule login -s <scenario>

"Failed to create temporary directory" → remote_tmp: /tmp missing.
Idempotence failures → find the changed task on second converge.
Registration/API timeouts → the scenario hit a real endpoint — stub it like the existing scenarios do.

Common Mistakes

Adding a scenario without registering it in pyproject.toml — silently untested.
Hardcoding the platform image — keep ${MOLECULE_PLATFORM_*} overrides.
Calling the real Gitea API in converge — scenarios must be self-contained; mock the registration path.

2.3 KiB Raw Blame History