RB-037 - Run collection role smoke tests with `hyops test role`¶

Use hyops test role when developing or validating a hybridops.* collection role.

This command replaces the old pattern of wiring a bespoke local ANSIBLE_COLLECTIONS_PATH overlay and running ansible-playbook directly from an external platform repository.

When to use it¶

run a role-local smoke check from a workspace checkout
syntax-check a role playbook before pushing a release branch
run a state-backed integration smoke against hosts already provisioned by HyOps
capture role smoke logs and results under the selected runtime instead of scattering local scratch files

Basic local role smoke¶

hyops test role hybridops.common.postgresql_service \
  --env dev \
  --workspace-root /path/to/hybridops-collections-src/collections/dev/workspace \
  --local-inventory

hyops test role will:

resolve the role from the workspace checkout
locate roles/<role>/tests/smoke.yml
auto-detect a local inventory under the role tests/ tree
materialize temporary overlays and dependency caches into the HyOps runtime
write run records under:
~/.hybridops/envs/<env>/logs/test/role/<collection>/<role>/<run_id>/

Syntax-check before a real smoke run¶

hyops test role hybridops.app.jenkins_controller \
  --env dev \
  --workspace-root /path/to/hybridops-collections-src/collections/dev/workspace \
  --local-inventory \
  --syntax-check

--syntax-check does not enforce required_env declarations from a role smoke manifest unless you explicitly ask for runtime vault material with --vault-env.

State-backed integration smoke¶

Use a state ref when the role needs real provisioned hosts instead of a static local inventory file.

hyops test role hybridops.app.jenkins_controller \
  --env dev \
  --workspace-root /path/to/hybridops-collections-src/collections/dev/workspace \
  --inventory-state-ref platform/onprem/platform-vm#jenkins_smoke_vm \
  --inventory-vm-group cicd_test=jenkins-01

HyOps resolves the inventory groups from current runtime state and writes a generated inventory into the run workdir.

When the upstream state was produced by a HyOps VM module, the generated inventory also inherits the effective SSH user from the published state or rerun inputs. This avoids defaulting disposable Linux smoke targets back to root when the VM contract was created with a different user such as opsadmin.

For platform/gcp/platform-vm sources, the generated inventory also infers ssh_access_mode=gcp-iap from the published VM state. That keeps private GCP smoke targets on the same IAP path used by the upstream HyOps module instead of silently falling back to direct SSH.

Prefer a disposable VM or VM set for state-backed role smoke tests. Do not point mutating roles such as jenkins_controller at long-lived shared control hosts.

Optional role manifest¶

Roles may provide:

roles/<role>/tests/hyops.role-test.yml

Use this when the role needs declared execution metadata such as:

alternate playbook path
default state ref
inventory group mapping
required environment variables
stable extra vars

Minimal example:

kind: role-smoke
role_fqcn: hybridops.app.jenkins_controller
playbook: smoke.yml
inventory:
  state_ref: platform/onprem/platform-vm#jenkins_smoke_vm
  vm_groups:
    cicd_test:
      - jenkins-01
required_env:
  - JENKINS_ADMIN_PASSWORD
extra_vars:
  jenkins_http_port: 8080

Notes¶

hyops test role is a runtime-writing command. It requires --env or --root.
Use --local-inventory for self-contained role checks.
If the role only ships inventory.sample.* or inventory.example.*, replace the placeholder values before running a real smoke test.
Use --inventory-state-ref when the role needs real hosts from module state.
Use --vault-env when required env vars or SSH key material should be resolved from the selected runtime vault.
The command is designed to replace ad-hoc harness logic, not duplicate it.

RB-037 - Run collection role smoke tests with hyops test role¶