<!-- markdownlint-disable MD013 -->
# Testing

[← Documentation index](README.md)

> **Status:** This repo contains **no** automated test suite
> and **no** CI pipeline. It is the inventory/configuration
> layer — the testable logic (roles) lives in
> [`digitalboard.core`](https://git.digitalboard.ch/Digitalboard/digitalboard.core).
> Role tests (Molecule or similar) therefore belong in the core repo, not
> here.

What is sensibly testable here are **inventory and playbook errors
before the actual deploy**. There are three levels for that — from fast and
risk-free to fully against the hosts.

## 1. Static checks (no host access needed)

No `VAULT_TOKEN`, no network access required:

```bash
# YAML syntax of all inventory files
yamllint inventories/

# Ansible best-practice lint over the playbook
ansible-lint playbooks/site.yml

# Playbook syntax + inventory parsing (does not yet resolve Bao lookups)
ansible-playbook playbooks/site.yml \
  -i inventories/demo-gymburgdorf/hosts.yml --syntax-check
```

`yamllint` and `ansible-lint` are not preconfigured in the repo —
they run with their defaults. If project-wide rules are desired,
a `.yamllint`/`.ansible-lint` in the repo root would be the place for it
(see [Open items](#open-items)).

## 2. Inspect inventory resolution

Shows the effectively merged variables per host — useful for seeing
precedence surprises (group_vars vs. host_vars) before the deploy.
Bao lookups are evaluated here, so `VAULT_TOKEN` is needed (see
[secrets.md](secrets.md#openbao-login)):

```bash
# group/host structure as a tree
ansible-inventory -i inventories/demo-gymburgdorf/hosts.yml --graph

# all vars of a host (merged)
ansible-inventory -i inventories/demo-gymburgdorf/hosts.yml --host application
```

## 3. Smoke test & dry run (against the hosts)

Requires SSH access and `VAULT_TOKEN` — for prerequisites see
[getting_started.md](getting_started.md#prerequisites):

```bash
# reachability of all demo hosts (ping module)
make ping_demo

# dry run: shows what WOULD change, without writing
ansible-playbook playbooks/site.yml \
  -i inventories/demo-gymburgdorf/hosts.yml --check --diff
```

> `--check` is only of limited value with the Docker-Compose-based roles:
> some tasks report "changed" because they only know the real
> container state at runtime. As a plausibility check
> (does the playbook run through, are the vars correct?) it is still
> useful. More on the invocation variants:
> [ansible.md § Running Ansible](ansible.md#running-ansible).

## Recommended pre-deploy workflow

```bash
yamllint inventories/ && ansible-lint playbooks/site.yml      # 1. static
ansible-playbook playbooks/site.yml -i <inv>/hosts.yml --syntax-check
make ping_demo                                                 # 2. reachability
ansible-playbook playbooks/site.yml -i <inv>/hosts.yml --check --diff   # 3. dry run
# only then: real deploy
```

## Open items

- **No CI** — lint/syntax checks run only manually. A Gitea/
  CI workflow that runs the static checks from level 1 on every push
  would be the next step.
- **No lint configuration** — `yamllint`/`ansible-lint` run with
  defaults; project-wide rules (`.yamllint`, `.ansible-lint`) are missing.
- **Role tests** — belong in
  [`digitalboard.core`](https://git.digitalboard.ch/Digitalboard/digitalboard.core),
  not in this repo.