# 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

```bash
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.