From 09fa9e9defa0bef0509eef74b507ebfb1363f8a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Budai?= Date: Fri, 28 Jul 2023 17:33:01 +0200 Subject: [PATCH] test/data/stages: Document the changes to the tests --- test/data/stages/README.md | 148 ++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 76 deletions(-) diff --git a/test/data/stages/README.md b/test/data/stages/README.md index 6cb55003..6c43a4af 100644 --- a/test/data/stages/README.md +++ b/test/data/stages/README.md @@ -10,20 +10,20 @@ new test-bed for your new stage do the following: 2. Populate the test folder. - The test folder is expected to have a `a.mpp.json`, `b.mpp.json`, `a.json`, + The test folder is expected to have a `a.mpp.yaml`, `b.mpp.yaml`, `a.json`, `b.json` and `diff.json`. - `(a|b).mpp.json` and `dif.json`files are the ones that you will need to + `(a|b).mpp.yaml` and `dif.json`files are the ones that you will need to provide, `(a|b).json` will be generated based on the their - ManifestPreProcessor json file counterpart (`.mpp.json`). + ManifestPreProcessor json file counterpart (`.mpp.yaml`). - The `a.mpp.json` file must provide the instructions for a minimal artifact + The `a.mpp.yaml` file must provide the instructions for a minimal artifact build using the minimum amount of pipelines and stages; you must not add - your new stage to this build. The artifact described in `b.mpp.json` will - have the same build as the one described in `a.mpp.json` but you must add + your new stage to this build. The artifact described in `b.mpp.yaml` will + have the same build as the one described in `a.mpp.yaml` but you must add your new stage to the build. - Once `(a|b).mpp.json` are made, run: + Once `(a|b).mpp.yaml` are made, run: ```bash make test/data/stages/my-new-stage/a.json @@ -37,87 +37,74 @@ new test-bed for your new stage do the following: test to pass, every change in artifact b's state must have been accounted for in the `diff.json` file. -3. Add the five required test files to your commit (`a.mmp.json`, `b.mpp.json`, +3. Add the five required test files to your commit (`a.mmp.yaml`, `b.mpp.yaml`, `a.json`, `b.json` and `diff.json`) and the GitHub CI will do the rest. -## Crafting `(a|b).mpp.json` test files +## Crafting `(a|b).mpp.yaml` test files -`(a|b).mpp.json` files can be based on OSBuild manifest v1 and v2. v2 is +`(a|b).mpp.yaml` files can be based on OSBuild manifest v1 and v2. v2 is preferred and is the version used in this guide. You can read about [Manifest Version 2](https://www.osbuild.org/guides/developer-guide/osbuild.html?highlight=manifest#version-2) in the OSBuild Guide. -Example of minimal `a.mpp.json`: -``` -{ - "version": "2", - # Specify the pipelines needed by your artifact, at a minimum it should - # specify a base image. Other pipelines should install any needed - # dependencies, create files, change permissions etc. - "pipelines": [ - { - "mpp-import-pipeline": { - # check the ../manifests folder for more options - "path": "../manifests/f34-build-v2.json", - "id": "build" - }, - # check osbuild/runners for more options - "runner": "org.osbuild.fedora34" - }, - { - "name": "tree", - "build": "name:build", - "stages": [ - { - # on manifest v1 this field was known as "name", watch out - "type": "org.osbuild.rpm", - "inputs": { - "packages": { - "type": "org.osbuild.files", - "origin": "org.osbuild.source", - # Modify these according to your needs - "mpp-depsolve": { - "architecture": "x86_64", - "module-platform-id": "f34", - "baseurl": "https://rpmrepo.osbuild.org/v2/mirror/public/f34/f34-x86_64-fedora-20210512/", - "repos": [ - { - "id": "default", - "baseurl": "https://rpmrepo.osbuild.org/v2/mirror/public/f34/f34-x86_64-fedora-20210512/" - } - ], - "packages": [ - # Specify the packages needed by your new stage - "some-package", - "another-package" - ] - } - } - } - } - ] - } - ] -} +Example of minimal `a.mpp.yaml`: +```yaml +version: '2' +pipelines: + - mpp-import-pipelines: + path: ../manifests/fedora-vars.ipp.yaml + + # If the build pipeline doesn't specify all packages needed for your + # test, feel free to add them. The goal is to have one build pipeline + # for everything to utilize caching as much as possible. + - mpp-import-pipeline: + path: ../manifests/fedora-build-v2.ipp.yaml + id: build + runner: + mpp-format-string: org.osbuild.fedora{release} + - name: tree + build: name:build + stages: + - type: org.osbuild.rpm + inputs: + packages: + type: org.osbuild.files + origin: org.osbuild.source + mpp-depsolve: + architecture: $arch + module-platform-id: $module_platform_id + repos: + mpp-eval: repos + packages: + # Specify the packages needed by your new stage + - some-package + - another-package + options: + gpgkeys: + mpp-eval: gpgkeys + exclude: + docs: true ``` -A `b.mpp.json` should have the same manifest as `a.mpp.json` but you should +A `b.mpp.yaml` should have the same manifest as `a.mpp.yaml` but you should also add your new stage: -```json -...[omitted]... -{ - "type": "org.osbuild.your-new-stage", - # the following is stage-specific: - "options": { - # add the required options for your stage - } - }, - "inputs": { - # add the required inputs for your stage - } -} +```yaml + +version: '2' +pipelines: + # [pipeline imports omitted] + - name: tree + build: name:build + stages: + - type: org.osbuild.rpm + # [options of the rpm stage omitted] + - type: org.osbuild.your-new-stage + options: + # add the required options for your stage + inputs: + # add the required inputs for your stage ``` ## Crafting `diff.json` files @@ -126,6 +113,15 @@ The `diff.json` file specifies the changes that are expected to be seen in the new artifact once the results of artifact `b` are compared against the baseline, artifact `a`. +You can easily generate them using the `tools/gen-stage-test-diff` tool: + +``` +sudo tools/gen-stage-test-diff \ + --store ~/osbuild-store \ + --libdir . \ + test/data/stages/your-new-stage >test/data/stages/your-new-stage/diff.json +``` + Sample `diff.json` file: ```json