cosa-kola

# Running Tests with cosa kola This skill guides you through running kola tests against CoreOS builds using coreos-assembler. ## Out of scope Writing new native (Go) kola tests and cloud platform testing are not covered here. For writing external tests, refer to the docs listed below. ## Key documentation references Do NOT duplicate these docs. Read them at runtime for command details: | File | What it covers | |------|----------------| | `docs/kola.md` | Kola overview, `cosa kola` wrapper behavior, automatic test discovery, common flags, denylists, test output logs | | `docs/kola/external-tests.md` | How to write and structure external tests, `kola.json` metadata, reboot support | | `docs/kola/adding-tests.md` | Adding native Go tests to kola (for reference) | | `src/cmd-kola` | `cosa kola` wrapper source -- shows how args are passed through to kola | ## Prerequisites Before running tests you need a QEMU image in the cosa workdir and the `cosa()` bash alias must be set up. Load the **cosa-basics** skill for both of these -- it covers container invocation, building from source, and fetching published builds. ## Workflow All commands below assume you are in a cosa workdir (or inside the cosa container). Read `docs/kola.md` for full flag documentation. ### Step 1: Find the right test(s) List available tests to find the one the user wants: ``` cosa kola list ``` For JSON output with descriptions: ``` cosa kola list --json | jq -r '.[] | [.Name, .Description] | @tsv' ``` External tests from `src/config/tests/kola/` are discovered automatically and named `ext.config.<path>` (e.g., `ext.config.files.aleph-version`). When you need to inspect or understand a test whose name starts with `ext.config.`, find its source under `src/config/tests/kola/` in the cosa workdir. The path maps directly from the test name: replace dots with `/` after `ext.config.` and look for `test.sh` (and optionally `kola.json` or `config.bu`) in that directory. For example: | Test name | Source path | |-----------|-------------| | `ext.config.files.aleph-version` | `src/config/tests/kola/files/aleph-version/test.sh` | | `ext.config.upgrade.extended` | `src/config/tests/kola/upgrade/extended/test.sh` | The `src/config/` directory is the cloned config repo (e.g., `fedora-coreos-config`). If it does not exist in the current directory, check for it relative to the cosa workdir root. **Important:** The cosa workdir (created by `cosa init`) is NOT the same as the coreos-assembler source repository. The `src/config/` directory only exists inside a cosa workdir. Do not search the coreos-assembler source tree for `ext.config.*` test files -- they won't be there. If you need to inspect these test sources and are not currently in a cosa workdir, either navigate to one or clone the config repo (e.g., `fedora-coreos-config`) directly. ### Step 2: Run the test(s) Test names are glob patterns: ``` cosa kola run basic cosa kola run ext.config.files.aleph-version cosa kola run 'ext.config.*' ``` Running `cosa kola run` with no pattern runs all tests (can take a long time). Read `docs/kola.md` for flags like `--parallel`, `--tag`, `--rerun`, `--denylist-test`, `--ssh-on-test-failure`, `--append-butane`, and others. For running tests on platforms other than QEMU (e.g. AWS, GCP, Azure, ISO, metal), load the **cosa-platforms** skill. ### Step 3: Check results Test logs are written to `tmp/kola/<test-name>/`. Key files: `journal.txt`, `console.txt`, `ignition.json`, `journal-raw.txt.gz`. Read `docs/kola.md` ("More information on tests") for details. ## Special test types ### ISO install tests ISO install tests are regular kola tests (the `testiso` subcommand was removed in https://github.com/coreos/coreos-assembler/pull/4377). Run them with `cosa kola run` like any other test: ``` cosa kola run iso.iso-offline-install.mpath.bios cosa kola run 'iso.*' ``` ### Upgrade tests ``` cosa kola --upgrades ``` This runs the `run-upgrade` subcommand, which tests OS upgrades. It automatically finds parent images and caches them in `tmp/kola-qemu-cache/`.