{"id":19705184,"url":"https://github.com/linux-system-roles/tox-lsr","last_synced_at":"2026-03-11T01:04:31.551Z","repository":{"id":38216201,"uuid":"303690505","full_name":"linux-system-roles/tox-lsr","owner":"linux-system-roles","description":"tox plugin for testing linux system roles locally via tox","archived":false,"fork":false,"pushed_at":"2026-03-09T21:39:14.000Z","size":521,"stargazers_count":4,"open_issues_count":1,"forks_count":14,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-03-10T03:25:11.213Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linux-system-roles.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-10-13T12:09:03.000Z","updated_at":"2026-03-09T21:39:18.000Z","dependencies_parsed_at":"2023-11-14T20:23:28.759Z","dependency_job_id":"5fdec7ce-fe46-4c1c-acd1-467d482a1810","html_url":"https://github.com/linux-system-roles/tox-lsr","commit_stats":null,"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/linux-system-roles/tox-lsr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-system-roles%2Ftox-lsr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-system-roles%2Ftox-lsr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-system-roles%2Ftox-lsr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-system-roles%2Ftox-lsr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linux-system-roles","download_url":"https://codeload.github.com/linux-system-roles/tox-lsr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-system-roles%2Ftox-lsr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30364737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"ssl_error","status_checked_at":"2026-03-10T21:40:59.357Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T21:26:43.035Z","updated_at":"2026-03-11T01:04:31.530Z","avatar_url":"https://github.com/linux-system-roles.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![CI Status](https://github.com/linux-system-roles/auto-maintenance/workflows/tox/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/linux-system-roles/tox-lsr/badge.svg?branch=main)](https://coveralls.io/github/linux-system-roles/tox-lsr?branch=main)\n\n# Linux System Roles Plugin for `tox`\n\nThis plugin for `tox` provides default settings used for testing Linux system\nroles via `tox`. The default settings can be overridden by role developer in\n`tox.ini`.\n\n## How to Get It\n\nFor local development, if you have already installed `tox` and `pip`:\n\n```\npip install --user git+https://github.com/linux-system-roles/tox-lsr@main\n```\n\nThis will install `tox-lsr` in your `~/.local` directory where tox should find\nit.  If you want to use a release tagged version:\n\n```\npip install --user git+https://github.com/linux-system-roles/tox-lsr@0.0.4\n```\n\nLook at https://github.com/linux-system-roles/tox-lsr/releases for the list of\nreleases and tags.\n\nTo confirm that you have it and that `tox` can use it:\n\n```\n# tox --help | grep lsr-enable\nusage: tox [--lsr-enable] [--version] [-h] [--help-ini] [-v] [-q]\n  --lsr-enable          Enable the use of the tox-lsr plugin (env: LSR_ENABLE)\n```\n\nThis shows that the `--lsr-enable` flag is available.\n\n### Additional requirements\n\n- `shellcheck` test requires `shellcheck` package.\n\nOn Fedora, you can install it with `dnf install shellcheck`, then you can test shell scripts with `tox -e shellcheck`.\n\nSeveral tests use `podman` - so `dnf install podman`\n\nQEMU tests have more requirements - see below `QEMU Testing`\n\n### Molecule and Ansible Version Support\n\ntox-lsr 2.0 and later use molecule v3, which support Ansible 2.8 and later.  If\nfor some reason you need to support Ansible 2.7 or earlier, use tox-lsr 1.x.\n\n## Troubleshooting\n\n* Remove the `.tox` directory: `rm -rf .tox`\n* Remove all versions of `tox-lsr`: `pip uninstall tox-lsr` - repeat until all\n  versions are removed\n* Remove anything left over -\n  `rm -rf ~/.local/lib/python*/site-packages/tox_lsr*` and\n  `rm -rf ~/.local/lib/python*/site-packages/tox-lsr*`\n* Remove any cached files `rm -rf ~/.local/bin/__pycache__/*`\n* Reinstall `tox-lsr` - see above\n\n## Example tox.ini\n\nThe following is an example of a `tox.ini` from the kernel_settings role:\n\n```ini\n[lsr_config]\nlsr_enable = true\ncommands_pre = bash -c '{toxinidir}/tests/install_tuned_for_testing.sh || {toxinidir}/tests/kernel_settings/install_tuned_for_testing.sh'\n\n[lsr_yamllint]\nconfigfile = {toxinidir}/.yamllint.yml\nconfigbasename = .yamllint.yml\n\n[testenv]\nsetenv =\n    TEST_SRC_DIR = {toxinidir}/tests\n```\n\nThe `[lsr_config]` section is the configuration for the `tox-lsr` plugin.  You\nmust set `lsr_enable = true` in order to use the plugin.  You can confirm that\nthe plugin is being used:\n\n```\n# tox -l\nblack\npylint\nflake8\n...\n```\n\nIf the plugin is not enabled, you would only see testenv definitions in your\n`tox.ini` file.\n\n## Configuration\n\nThere are several ways to append to and override the default configuration.\n\n### Tox command line arguments\n\nAll of the usual tox command line arguments work as you would expect.  The\ninformation returned is a result of merging your local tox.ini with the default,\nso flags like `-l` will return the default environments, `-e` can use the\ndefault environments, `--showconfig` will show the full merged config, etc.\nHowever, the `--skip-missing-interpreters` argument is ignored.  If you want to\nexplicitly set this, you must add it to your local tox.ini:\n\n```\n[tox]\nskip_missing_interpreters = false\n```\n\n### Standard tox.ini configuration\n\nYou can use the standard `tox` configuration in your local `tox.ini`, and the\nplugin will attempt to merge those settings with its default settings.  If the\nsetting is set in the local `tox.ini`, it will be applied, replacing any default\nsetting, if any.  However, there are a few settings which will be merged -\n`setenv`, `passenv`, `deps`, `allowlist_external`.  For `setenv`, you can\noverride a default setting.  For example, if the default was:\n\n```ini\n[testenv:pylint]\nsetenv =\n    A = a\n    B = b\ndeps =\n    a\n    b\npassenv =\n    A\nallowlist_externals =\n    bash\ncommands = pylint ...\n```\n\nand you specified this in your local `tox.ini`:\n\n```ini\n[testenv:pylint]\nsetenv =\n    A = c\n    D = d\ndeps =\n    c\n    d\npassenv =\n    B\nallowlist_externals =\n    sed\n    grep\ncommands = mypylint\n```\n\nThe final result would be:\n\n```ini\n[testenv:pylint]\nsetenv =\n    A = c\n    B = b\n    D = d\ndeps =\n    a\n    b\n    c\n    d\npassenv =\n    A\n    B\nallowlist_externals =\n    bash\n    sed\n    grep\ncommands = mypylint\n```\n\nThe local `tox.ini` settings were merged with the defaults, and in the case of\n`setenv`, the local `tox.ini` settings replaced the defaults where there was a\nconflict.  All of the other parameters you set in the local `tox.ini` will be\nset, replacing any existing default parameters.\n\nYou can also define your own tests and config sections - you do not have to use\n`custom`.  However, if you add your own tests, you must also add them to the\n`[tox]` section `envlist`.  For example:\n\n```ini\n[tox]\nenvlist = mytest\n\n[lsr_config]\nlsr_enable = true\n\n[mytests_common]\ndeps = mydeps\n\n[testenv:mytest]\ndeps = {[mytests_common]mydeps} mytestdep\ncommands = mytest\n```\n\nThen `tox -l` will show `mytest` in addition to the default tests.\n\n#### How to completely disable a test\n\nDefine its testenv but use `true` for `commands`.  For example, to disable\n`flake8`:\n\n```ini\n[testenv:flake8]\ncommands = true\n```\n\n### Using the [lsr_config] section\n\nThere are a few settings that can be set in the `[lsr_config]` section:\n* `lsr_enable` - `false` or `true` - default `false` - you must explicitly set\n  this `lsr_enable = true` in your local `tox.ini` in order to use the `tox-lsr`\n  plugin.\n* `commands_pre` - a list of commands - default empty - this is a list of\n  commands to run before the test, for every test.  If you want to run commands\n  only before certain tests, you must make your tests aware of the\n  `$LSR_TOX_ENV_NAME` environment variable, or use `{envname}` in your\n  `commands_pre` definition.\n* `commands_post` - a list of commands - default empty - this is a list of\n  commands to run after the test, for every test.  If you want to run commands\n  only after certain tests, you must make your tests aware of the\n  `$LSR_TOX_ENV_NAME` environment variable, or use `{envname}` in your\n  `commands_pre` definition.\n\nHere is an example from the kernel_settings role that uses `commands_pre` to run\na script before every test, and the script will only execute for certain tests:\n\n```ini\n[lsr_config]\nlsr_enable = true\ncommands_pre = bash -c '{toxinidir}/tests/install_tuned_for_testing.sh || {toxinidir}/tests/kernel_settings/install_tuned_for_testing.sh'\n```\nand this is what the script does:\n```bash\nKS_LSR_NEED_TUNED=0\ncase \"${LSR_TOX_ENV_NAME:-}\" in\n  pylint) KS_LSR_NEED_TUNED=1 ;;\n  py*) KS_LSR_NEED_TUNED=1 ;;\n  coveralls) KS_LSR_NEED_TUNED=1 ;;\n  flake8) KS_LSR_NEED_TUNED=1 ;;\nesac\nif [ \"$KS_LSR_NEED_TUNED\" = 1 ] ; then\n  ks_lsr_install_tuned \"$KS_LSR_PYVER\" \"$(ks_lsr_get_site_packages_dir)\"\nfi\n```\n\nSo the script is only executed for `pylint`, `coveralls`, `flake8`, and any test\nbeginning with `py` e.g. `py38`.\n\n### Using [lsr_TESTNAME] sections\n\nEach test has a corresponding `[lsr_TESTNAME]` section.  For example, there is a\n`[lsr_flake8]` section.  This is primarily used when you want to completely\nreplace the default config file.  If the default looks like this:\n\n```ini\n[lsr_flake8]\nconfigfile = {lsr_configdir}/flake8.ini\n\n[testenv:flake8]\ncommands =\n    bash {lsr_scriptdir}/setup_module_utils.sh\n    {[lsr_config]commands_pre}\n    python -m flake8 --config {[lsr_flake8]configfile} \\\n        {env:RUN_FLAKE8_EXTRA_ARGS:} {posargs} .\n    {[lsr_config]commands_post}\n```\n\nand you want to use your custom `flake8.conf` to completely override and replace\nthe default config, use this in your local `tox.ini`:\n\n```ini\n[lsr_flake8]\nconfigfile = {toxinidir}/flake8.conf\n```\n\nThen doing `tox -e flake8` would use your flake8.conf.\n\n### Using setenv and environment variables\n\nThese environment variables can be set in your local tox.ini `testenv` section.\nSome of the environment variables we used in the old scripts are carried over:\n* `RUN_PYTEST_SETUP_MODULE_UTILS` - if set to an arbitrary non-empty value, the\n  environment will be configured so that tests of the `module_utils/` code will be\n  run correctly\n* `RUN_PYLINT_SETUP_MODULE_UTILS` - if set to an arbitrary non-empty value, the\n  environment will be configured so that linting of the `module_utils/` code will\n  be run correctly\n* `RUN_FLAKE8_EXTRA_ARGS` - any extra command line arguments to provide e.g.\n  `--ignore=some,errs`\n* `RUN_SHELLCHECK_EXTRA_ARGS` - any extra command line arguments to provide e.g.\n  `--ignore=some,errs`\n* `RUN_BLACK_EXTRA_ARGS` - any extra command line arguments to provide e.g.\n  `--ignore=some,errs`\n* `LSR_PUBLISH_COVERAGE` - If the variable is unset or empty (the default), no\n  coverage is published.  Other valid values for the variable are:\n    * `strict` - the reporting is performed in strict mode, so situations like\n      missing data to be reported are treated as errors\n    * `debug` - coveralls is run in debug mode (see coveralls debug --help)\n    * `normal` - coverage results will be reported normally\n* `LSR_TESTSDIR` - a path to directory where tests and tests artifacts are\n  located; if unset or empty, this variable is set to `${TOPDIR}/tests` - this\n  path should already exist and be populated with tests artifacts before the\n  script starts performing actions on it\n\nThere are some new variables which can be set via `setenv` in `tox.ini` or via\nenvironment variables:\n* `RUN_PYTEST_EXTRA_ARGS` - extra command line arguments to provide to pytest\n* `RUN_PYLINT_EXTRA_ARGS` - extra command line arguments to provide to pylint\n* `RUN_YAMLLINT_EXTRA_ARGS` - extra command line arguments to provide to\n  yamllint\n* `RUN_ANSIBLE_LINT_EXTRA_ARGS` - extra command line arguments to provide to\n  ansible-lint and ansible-lint-collection\n* `LSR_ROLE2COLL_VERSION` - a tag/commit of the lsr_role2collection script to\n  use for the collection tox test.  The default is the latest stable version.\n* `LSR_ROLE2COLL_NAMESPACE` - namespace to use for the lsr_role2collection\n  script.  The default is `fedora`.\n* `LSR_ROLE2COLL_NAME` - collection name to use for the lsr_role2collection\n  script.  The default is `linux_system_roles`.\n* `LSR_ANSIBLE_TEST_DEBUG` - if set to `true`, `ansible-test` will produce\n  additional output for debugging purposes.  The default is `false`.\n* `LSR_ANSIBLE_TEST_TESTS` - a space delimited list of `ansible-test` tests to\n  run.  See `ansible-test sanity --list-tests` for the tests you can run. See\n  also `LSR_ANSIBLE_DOC_DEBUG`.\n* `LSR_ANSIBLE_DOC_DEBUG` - if set to `true`, `ansible-test` will produce\n  additional output when running the `ansible-doc` test.  The default is\n  `false`. This is very useful when working on the docs for a plugin or module\n  and you want to see how it renders, and you don't want any other tests to run.\n  See also `Working on collections docs` below.\n* `RUN_BLACK_CONFIG_FILE` - path to config file to use instead of the default\n* `RUN_FLAKE8_CONFIG_FILE` - path to config file to use instead of the default\n* `RUN_YAMLLINT_CONFIG_FILE` - path to config file to use instead of the default\n* `LSR_ANSIBLE_TEST_DOCKER` - if set to `true`, `ansible-test` will be run with\n  `--docker`\n* `LSR_ANSIBLE_TEST_DEP` - this is the dep to pass when doing the pip install of\n  ansible for ansible-test.  The default is `ansible-core==2.12.*`.\n* `LSR_PYLINT_ANSIBLE_DEP` - this is the dep to pass when doing the pip install of\n  ansible for pylint.  The default is `ansible-core==2.12.*`.\n* `LSR_RUN_TEST_DIR` - this is the directory to use to override `changedir`, for\n  those tests that need it, primarily the tests run \"recursively\" via `-e collection`\n* `LSR_CONTAINER_RUNTIME` - default `podman` - set to `docker` if you must\n\nThese environment variables are deprecated and will be removed soon:\n* `LSR_EXTRA_PACKAGES` - set in `.github/workflows/tox.yml` - list of extra\n  packages to install in the CI environment (typically an Ubuntu variant)\n* `LSR_ANSIBLES` - set in `.github/workflows/tox.yml` - ansible versions to test\n  molecule against in the form that is used with pip e.g. use\n  `LSR_ANSIBLES='ansible==2.8.* ansible==2.9.*'` to use ansible 2.8 and ansible\n  2.9.  Only ansible 2.8 and higher are supported. tox-lsr 2.0 uses molecule v3,\n  which does not work with ansible 2.7 or earlier.\n* `LSR_MSCENARIOS` - set in `.github/workflows/tox.yml` - molecule scenarios to\n  test\n* `LSR_MOLECULE_DRIVER` - default `docker` - The molecule driver to use.  If you\n  want to use `podman`, use `LSR_MOLECULE_DRIVER=podman`\n* `LSR_MOLECULE_DRIVER_VERSION` - default empty - use this if you want to\n  override the version of the molecule driver pypi package - otherwise, the\n  correct version will be auto-detected.  E.g.\n  `LSR_MOLECULE_DRIVER=podman LSR_MOLECULE_DRIVER_VERSION='\u003c4.4'` will evaluate\n  to something like `pip install podman\u003c4.4`\n\nThese environment variables have been removed:\n* `RUN_PYLINT_INCLUDE` - use `RUN_PYLINT_EXTRA_ARGS`\n* `RUN_PYLINT_EXCLUDE` - use `RUN_PYLINT_EXTRA_ARGS`\n* `RUN_PYLINT_DISABLED` - see `How to completely disable a test`\n* `RUN_FLAKE8_DISABLED` - see `How to completely disable a test`\n* `RUN_SHELLCHECK_DISABLED` - see `How to completely disable a test`\n* `RUN_BLACK_INCLUDE` - use `RUN_BLACK_EXTRA_ARGS`\n* `RUN_BLACK_EXCLUDE` - use `RUN_BLACK_EXTRA_ARGS`\n* `RUN_BLACK_DISABLED` - see `How to completely disable a test`\n\n### Environment variables available for test scripts\n\nThese environment variables are set by the plugin or the default tox\nconfiguration and are available for use by test scripts:\n\n* `TOXINIDIR` - the full path to the local `tox.ini`\n* `LSR_SCRIPTDIR` - the full path to where the `tox-lsr` scripts are installed.\n  This is primarily useful for including `utils.sh` in your scripts:\n\n```bash\n. \"$LSR_SCRIPTDIR/utils.sh\"\nlsr_some_shell_func ....\n```\n\n* `LSR_CONFIGDIR` - the full path to where the `tox-lsr` config files are\n  installed.\n* `LSR_TOX_ENV_NAME` - the name of the test environment e.g. `py38`, `flake8`,\n  etc.\n* `LSR_TOX_ENV_DIR` - the full path to the directory for the test environment\n  e.g. `/path/to/ROLENAME/.tox/env-3.8`\n* `LSR_TOX_ENV_TMP_DIR` - the full path to the temporary directory for the test\n  environment - equivalent to tox `{envtmpdir}`\n\n### Working on collections docs\n\nIt can be tricky to get the plugin and module docs to render correctly.  Use a\nworkflow like this:\n\n```\n\u003e LSR_ANSIBLE_TEST_DEBUG=true LSR_ANSIBLE_TEST_TESTS=ansible-doc \\\n  tox -e collection,ansible-test\n```\n\nThis will convert your role to a collection, run `ansible-test` with only the\n`ansible-doc` test, and dump what the converted doc looks like, or dump errors\nif your doc could not be rendered correctly.\n\nTo run `ansible-lint-collection` you must first convert to collection.\n\n```\n\u003e tox -e collection,ansible-lint-collection\n```\n\n### Integration test setup\n\nInstall the test dependencies:\n\n```sh\nsudo dnf install -y tox qemu-system-x86-core buildah podman\n```\n\nDownload and install the [default image configuration](https://github.com/linux-system-roles/linux-system-roles.github.io/blob/main/download/linux-system-roles.json):\n\n```sh\ncurl -s -L -o ~/.config/linux-system-roles.json \\\nhttps://raw.githubusercontent.com/linux-system-roles/linux-system-roles.github.io/main/download/linux-system-roles.json\n```\n\nIf you have any additional images defined in a separate file, download that file\nto `~/.config/extra-images.json`.  This is the default file location used by the\n`extra_images_file` setting in `~/.config/linux-system-roles.json`.\n\nFinally make sure you installed tox-lsr as described above:\n\n```sh\npip install --user git+https://github.com/linux-system-roles/tox-lsr@main\n```\n\n### QEMU testing\n\nIntegration tests are run using qemu/kvm using the test playbooks in the\n`tests/` directory, using the `standard-inventory-qcow2` script to create a VM\nand an Ansible inventory. There are several test envs that can be used to run\nthese tests:\n* `qemu-ansible-2-9` - tests against ansible-2.9\n* `qemu-ansible-core-2-N` - tests against ansible-core 2.N\n\nThese tests run in one of two modes, depending on which of the following\narguments you provide.  Note that you must use `--` on the command line after\nthe `-e qemu-ansible-core-2-N` so that `tox` will not attempt to interpret these\nas `tox` arguments:\n\n```\ntox -e qemu-ansible-core-2-17 -- --image-name centos-10 ...\n```\n\nYou must provide one of `--image-file` or `--image-name`.\n\nThe values for `--image-name` come from the config file passed to the `--config`\nargument below, or if not given, the default config installed above.\n\nNOTE: By default, `qemu-ansible-2-9` will run Ansible from an EL7 container\nusing podman, because it is not possible to recreate the EL7 Ansible 2.9\nenvironment with modern Fedora and EL9+ tox venvs.  See below\n`--ansible-container`.  The container is built from `containers/Dockerfile` in\nthe tox-lsr repo.\n\n* `--image-file` - this is the full path to a local qcow2 image file.  This\n  assumes you have already downloaded the image to a local directory.  The\n  corresponding environment variable is `LSR_QEMU_IMAGE_FILE`.\n* `--image-name` - assuming you have a config file (`--config`) that maps the\n  given image name to an image url and optional setup, you can just specify an\n  image name like `--image-name centos-10` and the script will download the\n  latest qcow2 compose image for CentOS 10 to a local cache (`--cache`).  The\n  script will check to see if the downloaded image in the cache is the latest,\n  and will not download if not needed.  In the config file you can specify\n  additional setup steps to be run e.g. setting up additional dnf/yum repos.\n  The corresponding environment variable is `LSR_QEMU_IMAGE_NAME`.\n* `--image-alias` - no default - Use this if you cannot use the full path to the\n  image for the hostname in the inventory.  If you use the special value\n  `BASENAME` the basename of the image path/file will be used.  The\n  corresponding environment variable is `LSR_QEMU_IMAGE_ALIAS`.\n* `--config` - default `$HOME/.config/linux-system-roles.json` - this is the\n  full path to a config file that lists the image names, the source or compose,\n  and additional setup steps.  The corresponding environment variable is\n  `LSR_QEMU_CONFIG`.\n* `--cache` - default `$HOME/.cache/linux-system-roles` - this is the directory\n  where the downloaded qcow2 images will be cached - be sure this partition has\n  a lot of space if you plan on downloading multiple images.  The corresponding\n  environment variable is `LSR_QEMU_CACHE`.\n* `--inventory` - default is the one included with tox-lsr - this is useful to\n  set if you are working on the inventory script and want to use your local\n  clone.  The corresponding environment variable is `LSR_QEMU_INVENTORY`.\n* `--collection` - This tells the script that the given playbook should be run\n  in the context of a collection.  You must have already created the collection\n  by first using `tox -e collection`.  The corresponding environment\n  variable is `LSR_QEMU_COLLECTION`.  The test playbook should be the converted\n  test - so use something like\n  `.tox/ansible_collections/fedora/linux_system_roles/tests/ROLE/tests_my_test.yml`\n  Otherwise, you won't be testing the collection.\n* `--debug` - This uses the `TEST_DEBUG=true` for `standard-inventory-qcow2` so\n  that you can debug the VM.  The corresponding environment variable is\n  `LSR_QEMU_DEBUG`.\n* `--pretty` - pretty print the output e.g. use `ANSIBLE_STDOUT_CALLBACK=debug`\n  - the default value is `true`.  The corresponding environment variable is\n  `LSR_QEMU_PRETTY`.\n* `--profile` - show the profile_tasks information.  The default value is `true`.\n  The corresponding environment variable is `LSR_QEMU_PROFILE`.\n* `--profile-task-limit` - if using `--profile`, this specifies how many tasks\n  to show in the output.  The default is `30`.  The corresponding environment\n  variable is `LSR_QEMU_PROFILE_TASK_LIMIT`.\n* `--use-yum-cache` - Create 1 GB files in your `cache` directory for the purpose\n  of storing package cache and metadata information for the VM.  The files will\n  be named `$PLATFORM_yum_cache` and `$PLATFORM_yum_varlib`.  These are mounted\n  into the VM at `/var/cache/dnf` and `/var/lib/dnf` (or `yum` for YUM platforms).\n  If you plan to run multiple tests on the same platform, this can speed up\n  subsequent runs by installing packages from the cache rather than the network.\n  The default is `false`.  The corresponding environment variable is\n  `LSR_QEMU_USE_YUM_CACHE`.\n* `--use-snapshot` - Create a snapshot of the image using the original image as\n  the backing file.  This is useful when you want to pre-load a image for testing\n  multiple test runs, but do not want to alter the original downloaded image e.g.\n  pre-configuring package repos, pre-installing packages, etc.  This will create\n  a file called `$IMAGE_PATH.snap` e.g. `~/.cache/linux-system-roles/centos-10.qcow2.snap`.\n  The default is `false`.  The corresponding environment variable is\n  `LSR_QEMU_USE_SNAPSHOT`.\n* `--wait-on-qemu` - This tells the script to wait for qemu to fully exit after\n  each call to `ansible-playbook`.  This can solve race conditions if you are using\n  `runqemu` to run multiple tests sequentially.  The default value is `false`.  Do\n  not use this if you are using `runqemu` interactively, especially with `--debug`.\n  This is intended only for use by automated test applications.  The corresponding\n  environment variable is `LSR_QEMU_WAIT_ON_QEMU`.  NOTE: Don't use this unless\n  you know what you are doing.\n* `--setup-yml` - You can specify one or more of your own setup.yml playbooks to\n  use in addition to the setup steps in the `config` file.  The corresponding\n  environment variable is `LSR_QEMU_SETUP_YML`, which is a comma-delimited list\n  of playbook files.  These setup playbooks should be playbooks which would be\n  applied to the snapshot if using `--use-snapshot`.  If you have playbooks\n  which do other types of per-test setup, do not use `--setup-yml`.  Just specify\n  them in order on the command line after all of the arguments.\n* `--cleanup-yml` - You can specify one or more of your own cleanup playbooks to\n  use.  The cleanup playbooks are run no matter if the main playbooks succeeded\n  or failed.  This is really useful if you want to ensure some resources are\n  restored after the playbooks run, or if you want to gather some information\n  from the VM when the playbooks fail e.g. a handler fails and you want to get\n  the systemd journal from the VM.  The variable `last_rc` (string) can be used\n  to tell if the main playbooks succeeded (`\"0\"`) or failed (non-zero).  Cast to\n  an integer (`last_rc | int`) if you need an integer value for mathematical\n  operations.  The corresponding environment variable is `LSR_QEMU_CLEANUP_YML`,\n  which is a comma-delimited list of playbook files.\n* `--write-inventory` - Specify a file to write the generated inventory to.  The\n  filename must be simply `inventory`, or must end in `.yml`.  Examples:\n  `/path/to/inventory` or `/tmp/inventory.xxx.yml`.  The user is responsible for\n  removing when no longer in use.  This is useful if you use `--debug` or\n  `LOCK_ON_FILE` which leave the VM running, and you want to run Ansible against\n  the VM again.\n* `--erase-old-snapshot` - If `true`, erase the current snapshot.  The default\n  is `false`.  Use this with `--use-snapshot` to ensure a brand new snapshot is\n  created.  The corresponding environment variable is `LSR_QEMU_ERASE_OLD_SNAPSHOT`.\n* `--post-snap-sleep-time` - Amount in seconds to sleep after creating the\n  snapshot. There is some sort of race condition that is highly platform\n  dependent - if you try to use the snapshot too soon after creation, you will\n  get hangs, kernel crashes, etc. in the new guest.  The only remedy so far is\n  to figure out how long to sleep after creating the snapshot. The default value\n  is `1` second.  The corresponding environment variable is\n  `LSR_QEMU_POST_SNAP_SLEEP_TIME`.\n* `--batch-file`, `--batch-report`, `--batch-id` - see below\n* `--log-file` - by default, output from ansible and other commands go to\n  stdout/stderr - if you pass in a path to a file, the logs will be written to\n  this file - the file is opened with `\"a\"` so if you want a new file you should\n  remove it first.  The corresponding environment variable is\n  `LSR_QEMU_LOG_FILE`.\n* `--log-level` - default is `warning`.  The corresponding environment variable\n  is `LSR_QEMU_LOG_LEVEL`.  It is recommended to use `info` if you are using\n  `--batch-file` so you can see what it is doing.\n* `--tests-dir` - this is used to specify the directory where the main test\n  playbook is located, usually the directory containing the `provision.fmf` used\n  for the test.  `runqemu` allows specifying multiple playbooks to run.  By default\n  the tests directory is the directory of the first playbook.  However, in some cases\n  you may need to specify setup playbooks to run before the test.  e.g.\n  `runqemu ... save-state.yml /path/to/tests/tests_1.yml ...`\n  In that case, you need to tell `runqemu` where is the main `tests` directory:\n  `runqemu --tests-dir  /path/to/tests ... save-state.yml /path/to/tests/tests_1.yml ...`\n  The corresponding environment variable is `LSR_QEMU_TESTS_DIR`.\n* `--artifacts` - The path of the directory containing the VM provisioner log files.\n  By default this is `artifacts/` and `artifacts.snap/` in the current directory.\n  The corresponding environment variable is `LSR_QEMU_ARTIFACTS`.\n* `--ssh-el6` - default is `false`.  If `true`, the system is an EL6 system\n  which requires some additional SSH configuration.  The corresponding\n  environment variable is `LSR_QEMU_SSH_EL6`.\n* `--make-batch` - This tells runqemu to create a batch file from all of the\n  files matching `tests/tests_*.yml` and run using this batch file.\n* `--ansible-container` - default is None. Run ansible from a container rather\n  than installing it and running it from a local tox venv.  The corresponding\n  environment variable is `LSR_QEMU_ANSIBLE_CONTAINER`.\n* `--lsr-report-errors-url` - default is None.  Specifying this will activate\n  the error reporting functionality in the output.  Use `DEFAULT` if you want to\n  use the default url, which is defined in the code as the variable\n  `DEFAULT_LSR_QEMU_REPORT_ERRORS_URL`, which has the default value of\n  [https://raw.githubusercontent.com/linux-system-roles/auto-maintenance/main/callback_plugins/lsr_report_errors.py](https://raw.githubusercontent.com/linux-system-roles/auto-maintenance/main/callback_plugins/lsr_report_errors.py)\n  otherwise, specify another url or local file to use.  The corresponding\n  environment variable is `LSR_QEMU_REPORT_ERRORS_URL`.\n\nEach additional command line argument is passed through to ansible-playbook, so\nit must either be an argument or a playbook.  If you want to pass both arguments\nand playbooks, separate them with a `--` on the command line:\n\n```\ntox -e qemu-ansible-core-2-20 -- --image-name centos-10 --become --become-user root -- tests/tests_default.yml\n```\n\nThis is because `runqemu` cannot tell the difference between an Ansible argument\nand a playbook.  If you do not have any ansible-playbook arguments, only\nplaybooks, you can omit the `--`:\n\n```\ntox -e qemu-ansible-core-2-20 -- --image-name centos-10 tests/tests_default.yml\n```\n\nIf using `--collection`, it is assumed you used `tox -e collection` first.  Then\nspecify the path to the test playbook inside this collection:\n\n```\ntox -e collection\ntox -e qemu-ansible-core-2-20 -- --image-name centos-10 --collection .tox/ansible_collections/fedora/linux-system-roles/tests/ROLE/tests_default.yml\n```\n\nThe config file looks like this:\n\n```json\n{\n    \"images\": [\n    {\n      \"name\": \"centos-10\",\n      \"source\": \"https://cloud.centos.org/centos/10-stream/x86_64/images/CentOS-Stream-GenericCloud-10-latest.x86_64.qcow2\",\n      \"compose\": \"https://composes.stream.centos.org/stream-10/production/latest-CentOS-Stream/compose/\",\n      \"variant\": \"BaseOS\",\n      \"subvariant\": \"generic\",\n      \"container\": \"quay.io/centos/centos:stream10-development\",\n      \"openstack_image\": \"CentOS-10-x86_64-GenericCloud-released-latest\",\n      \"upload_results\": true,\n      \"setup\": [\n        {\n          \"name\": \"Setup repos\",\n          \"hosts\": \"all\",\n          \"gather_facts\": false,\n          \"vars\": {\n            \"repourls\": {\n              \"centos-HighAvailability\": \"https://composes.stream.centos.org/stream-10/production/latest-CentOS-Stream/compose/HighAvailability/x86_64/os/\"\n            }\n          },\n          \"tasks\": [\n            {\n              \"name\": \"set up internal repositories\",\n              \"yum_repository\": {\n                \"name\": \"{{ item.key }}\",\n                \"description\": \"{{ item.key }}\",\n                \"baseurl\": \"{{ item.value }}\",\n                \"gpgcheck\": false,\n                \"file\": \"/etc/yum.repos.d/rhel.repo\"\n              },\n              \"no_log\": true,\n              \"loop\": \"{{ repourls | dict2items }}\"\n            }\n          ]\n        }\n      ]\n    },\n    ...\n}\n```\n\nExample:\n\n```\ntox -e qemu-ansible-core-2-20 -- --image-name centos-10 tests/tests_default.yml\n```\n\nThis will lookup `centos-10` in your `~/.config/linux-system-roles.json`, will\ncheck if it needs to download a new image to `~/.cache/linux-system-roles`, will\ncreate a setup playbook based on the `\"setup\"` section in the config, and will\nrun `ansible-playbook` with `standard-inventory-qcow2` as the inventory script\nwith `tests/tests_default.yml`.\n\nThe environment variables are useful for customizing in your local tox.ini.  For\nexample, if I want to use a custom location for my config and cache, and I do not\nwant to use the profile_tasks plugin, I can do this:\n\n```ini\n[qemu_common]\nsetenv =\n    LSR_QEMU_CONFIG = /home/username/myconfig.json\n    LSR_QEMU_CACHE = /my/big/partition\n    LSR_QEMU_PROFILE = false\n```\n\n#### batch-file, batch-report, batch-id\n\nThere are cases where you want to run several playbooks in the same running VM,\nbut in multiple invocations of `ansible-playbook`.  You can use `--batch-file`\nto run in this mode.  The argument to `--batch-file` is a plain text file.  Each\nline is an invocation of `ansible-playbook`.  The contents of the line are the\nsame as the command line arguments to `runqemu`.  You can use almost all of the\nsame command-line parameters.  For example:\n\n```\n--log-file /path/to/test1.log --artifacts /path/to/test1-artifacts --setup-yml /path/to/setup-snapshot.yml --tests-dir /path/to/tests -e some_ansible_var=\"some ansible value\" --batch-id tests_test1.yml --cleanup-yml restore.yml --cleanup-yml cleanup.yml -- _setup.yml save.yml /path/to/tests/tests_test1.yml\n--log-file /path/to/test2.log --artifacts /path/to/test2-artifacts --setup-yml /path/to/setup-snapshot.yml --tests-dir /path/to/tests -e some_ansible_var=\"some ansible value\" --batch-id tests_test2.yml --cleanup-yml restore.yml --cleanup-yml cleanup.yml -- _setup.yml save.yml /path/to/tests/tests_test2.yml\n...\n```\n\nif you pass this as `runqemu.py --batch-file this-file.txt` it will start a VM\nand create an inventory, then run\n\n```\nansible-playbook --inventory inventory -e some_ansible_var=\"some ansible value\" -- _setup.yml save.yml /path/to/tests/tests_test1.yml --cleanup-yml restore.yml --cleanup-yml cleanup.yml \u003e\u003e /path/to/test1.log 2\u003e\u00261\n# artifacts such as default_provisioner.log and the vm logs will go to /path/to/test1-artifacts\nansible-playbook --inventory inventory -e some_ansible_var=\"some ansible value\" -- _setup.yml save.yml /path/to/tests/tests_test2.yml --cleanup-yml restore.yml --cleanup-yml cleanup.yml \u003e\u003e /path/to/test2.log 2\u003e\u00261\n# artifacts such as default_provisioner.log and the vm logs will go to /path/to/test2-artifacts\n```\n\nthen it will shutdown the VM.  If you want to leave the VM running for\ndebugging, use `--debug` on the command line *and* in every entry in the batch file e.g.\n`--debug --log-file /path/to/testN.log ...`\n\nUse `--make-batch` to create a batch file using all of the files matching\n`tests/tests_*.yml`, and run the tests.  This will create the files `batch.txt`\nand `batch.report` in the current directory.\n`tox -e qemu-ansible-core-2-20 -- --image-name centos-10 --log-level debug --make-batch --`\nYou must specify the trailing `--` on the command line to tell runqemu that\nthere are no more arguments.  You can then edit the `batch.txt` file to remove\nfiles, change arguments, etc. and re-run using `--batch-file batch.txt`.\n\nBy default, `--make-batch` will sort the list of test files in `imagehash`\norder. If you want to use a different order, use `--make-batch-file-order ORDER`.\nSupported `ORDER` values are:\n\n - `ascending`: US ASCII sort order (using Python's `sorted()` function)\n - `descending`: reverse  US ASCII sort order\n - `imagehash`: `ascending` or `descending` depending on an 1-bit hash of the\n   image name; this is a good compromise between avoiding test dependencies and\n   still keeping a reproducible order\n - `natural`: default filesystem order (whatever is the order returned by\n   `glob(\"tests/tests_*.yml\")`)\n\nNote that when you specify `--make-batch-file-order`, that implies `--make-batch`.\n\nOnly the following `runqemu` arguments are supported in batch files:\n`--log-file`, `--artifacts`, `--setup-yml`, `--tests-dir`, `--cleanup-yml`, and\n`--debug` (only on last line). In addition, there is an argument used only in\nbatch files - `--batch-id` - which you can use as an identifier to correlate\nlines in your batch file with the corresponding line in your batch report file.\nYou can use many/most `ansible-playbook` arguments.  Arguments passed in on the\n`runqemu` command line will be the default values.  Specifying arguments in the\nbatch file will override the `runqemu` command line arguments. NOTE: With batch\nfile, you can use `runqemu` without providing any playbooks on the command line.\nHowever, if you want to provide Ansible arguments on the `runqemu` command line,\nyou will need to add `--` to the end of the `runqemu` command line, because\n`runqemu` cannot tell the difference between an Ansible argument and a playbook.\nAlso, it is recommended to put any Ansible arguments *after* any `runqemu`\narguments.\nExample:\n\n```\nrunqemu.py --log-level info --batch-file batch.txt --batch-report report.txt \\\n  --skip-tags tests::nvme --\n```\n\nSince `--skip-tags` is an Ansible argument, it should come last, and it must be\nfollowed by `--`.\n\n`runqemu` will run *ALL* lines specified in the file, and will exit with an\nerror code at the end if *ANY* of the invocations had an error.  If you want to\nknow exactly which tests succeeded and failed, and the exit code from each test,\nspecify `--batch-report /path/to/file.txt`.  Each line of this file will contain\nthe following in this order:\n* the exit code from the run\n* the timestamp when the run started in sec.usec format\n* the timestamp when the run finished in sec.usec format\n* the batch-id, if any\n* the list of playbooks for that run\n\n```\n0 1654718873.937814 1654718878.705445 tests_default.yml /path/to/tests/tests_default.yml\n0 1654718879.937814 1654718881.705445 tests_ssh.yml /path/to/tests/tests_ssh.yml\n2 1654718879.937814 1654718881.705445 bogus.yml /path/to/bogus.yml\n```\n\nLine `N` in the report should correspond to line `N` in the batch file, and you\ncan also use the batch-id for correlation.\n\n#### Ansible Vault support\n\nIf you want to test using variables encrypted with\n[Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html) do the\nfollowing:\n* put the password in the file `tests/vault_pwd` e.g. `echo -n password \u003e tests/vault_pwd`\n* `mkdir tests/vars`\n* encrypt the variables\n\n```\nansible-vault encrypt_string --vault-password-file tests/vault_pwd my_secret_value \\\n  --name my_secret_var_name \u003e\u003e tests/vars/vault-variables.yml\nansible-vault encrypt_string --vault-password-file tests/vault_pwd another_value \\\n  --name another_var \u003e\u003e tests/vars/vault-variables.yml\n```\n\nTo prevent sensitive content like your sudo password from being written into\nyour `~/.bash_history`, you can also type the password on standard input:\n\n```\nansible-vault encrypt_string --vault-password-file tests/vault_pwd \\\n  --stdin-name sudo_password \u003e\u003e tests/vars/vault-variables.yml\n```\n\nType the password and press Control-D.\n\nDo this to run bootc end-to-end tests which call\n[bootc-buildah-qcow.sh](./src/tox_lsr/test_scripts/bootc-buildah-qcow.sh),\nunless your system has passwordless sudo.\n\nThen if you run\n\n```\ntox -e qemu-... -- --image-name name tests/tests_that_uses_my_secret_value.yml\n```\n\nthe variable `my_secret_var_name` will be automatically decrypted.  It is a good\nidea to test roles that use passwords, keys, tokens, etc. with vault to ensure\nthat encryption works according to our documentation.\n\nThere may be some tests that you want to run without the variable being defined.\nFor example, there are some roles that always require a password to be provided\nby the user, and some tests want to check the failure mode if there is no\npassword.  That is, you want to provide an encrypted password for all tests\nexcept certain ones.  In that case, create the file\n`tests/no-vault-variables.txt` containing the *basename* of the tests you want\nto skip, one per line.  For example, if you want to run all tests except\ntests_a.yml and tests_b.yml with the encrypted passwords, create the file\n`tests/no-vault-variables.txt` like this:\n\n```\ntests_a.yml\ntests_b.yml\n```\n\nThen you can run `tox -e qemu-... -- tests/tests_a.yml` and the vault encrypted\nvariables will not be defined.\n\n#### RHEL/CentOS-6 managed host support\n\nThe native version of Python on RHEL 6 is 2.6.\nThe last ansible supporting Python2.6 is 2.12.\nSo, to execute `runqemu` against RHEL/CentOS-6 managed host,\nplease specify `qemu-ansible-core-2-12` as follows.  You will\nalso need to add `--ssh-el6` if you are using a newer EL9 or\nFedora control node, or some other system which uses \"modern\"\ncrypto and needs to use old, deprecated crypto to talk to EL6.\n\n```\ntox -e \"$ansible_core\" -- --image-name rhel-6 --ssh-el6 -- test_playbook.yml\n```\n\nAlternatively, following is the command line to run `runqemu.py` directly.\nThis command line allows you to use python2, which is useful if `ansible 2.9`\nis installed on the control host.\nPlease note that the standard-inventory-qcow2 is supposed to be a python2\nversion.\n\n```\npython runqemu.py --config=NONE --cache=/path/to/cache_dir \\\n  --inventory=/path/to/my/standard-inventory-qcow2 \\\n  --image-file=/path/to/cache_dir/RHEL_6_10_GA.qcow2 \\\n  --setup-yml=/path/to/cache_dir/_setup.yml --ssh-el6 \\\n  --artifacts=/path/to/artifacts --wait-on-qemu --log-level info \\\n  -- /path/to/cache_dir/_setup.yml test_playbook.yml\n```\n\nOlder versions of `runqemu.py` would examine the `--image-name` or\n`--image-file` value to determine if the image is an EL6 image, but this is now\ndeprecated. You must specify `--ssh-el6` if you need it.\n\n### Building ostree images\n\nRequirements: You will need to install the following packages to build and run:\nosbuild-ostree osbuild-tools edk2-ovmf\n\ntox-lsr can build images for [ostree](https://coreos.github.io/rpm-ostree/). The\n`/usr` file system is read-only, which means the RPM packages and any other\nfiles in `/usr` must be provided when the image is built. This means that the\nsystem roles cannot actually manage (install, remove) packages on the system,\nthey can only verify that the required packages are available. You can use\n`-e build_ostree_image -- $image_name` to build an ostree image for testing.\nIf you want to build for an image that is not supported by tox-lsr, download the\nappropriate `$image_name.ipp.yml` into your `~/.config` directory.  The image\nwill be available as `~/.cache/linux-system-roles/$image_name-ostree.qcow2` You\ncan test with the image like this:\n\n```bash\nTEST_USE_OVMF=true tox -e qemu-ansible-core-2-20 -- \\\n  --image-file ~/.cache/linux-system-roles/centos-10-ostree.qcow2 \\\n  --log-level debug tests/tests_default.yml\n```\n\n#### Using a VM to build ostree images\n\nOne of the issues with building ostree images is that you cannot (generally)\nbuild an image for a later release on an earlier OS.  For example, you cannot\nbuild a centos-9 image on a centos-8 machine, or if you can, it might not work\nproperly.  tox-lsr provides the ability to use an intermediate VM to build the\nlater VM.  You can use one of these environment variables:\n\n* `LSR_BUILD_IMAGE_USE_VM` - default is `false` - if true, build and run a VM\n  based on the default osbuildvm/osbuildvm.mpp.yml, and run the osbuild for your\n  target in this VM\n* `LSR_BUILD_IMAGE_VM_DISTRO_FILE` - this is the absolute path and file name of\n  an alternate osbuildvm.mpp.yml file that you want to use instead of the\n  default.\n\nExamples:\n\n```\nLSR_BUILD_IMAGE_USE_VM=true tox -e build_ostree_image -- centos-10\n```\n\nWill create a VM based on the default osbuildvm.mpp.yml, and use that to build\nthe centos-10 image.\n\n```\nLSR_BUILD_IMAGE_VM_DISTRO_FILE=/path/to/my/osbuildvm.mpp.yml tox -e build_ostree_image -- centos-10\n```\n\nWill create a VM based on the given osbuildvm.mpp.yml, and use that to build the\ncentos-10 image.\n\n#### .ostree directory\n\n`build_ostree_image` uses the role `.ostree` directory to determine which\npackages to build into the image.\n\n### Container testing\n\nIntegration tests can be run using containers. Some roles support it officially\nand run container tests in CI; these are tagged with `container` in\nmeta/main.yml. If you are working on a role and notice that container tests\nwork, or you are fixing them, please add that tag -- that will automatically\nenable the corresponding tests.\n\n`tox` will start one or more containers for the managed nodes using `podman`\nand the Ansible `podman` connection plugin.  There are some test envs that can\nbe used to run these tests:\n* `container-ansible-2-9` - tests against Ansible 2.9 also uses jinja 2.7 if\n* supported by the python used `container-ansible-core-2-x` - tests against\n* ansible-core 2.x\n\nThese tests run in one of two modes, depending on which of the following\narguments you provide.  Note that you must use `--` on the command line after\nthe `-e container-ansible-2-9` or `-e container-ansible-core-2-x` so that `tox` will not attempt to\ninterpret these as `tox` arguments:\n\n```\ntox -e container-ansible-core-2-20 -- --image-name centos-10 ...\n```\n\nYou must provide `--image-name`.\n\n* `--image-name` - assuming you have a config file (`--config`) that maps the\n  given image name to a container registry image and optional setup, you can just specify an\n  image name like `--image-name centos-10` and the script will pull the\n  latest image for CentOS 10.  In the config file you can specify\n  additional setup steps to be run e.g. setting up additional dnf/yum repos.\n  The corresponding environment variable is `CONTAINER_IMAGE_NAME`.\n* `--config` - default `$HOME/.config/linux-system-roles.json` - this is the\n  full path to a config file that lists the image names, the source or compose,\n  and additional setup steps.  The corresponding environment variable is\n  `CONTAINER_CONFIG`.\n* `--erase-old-snapshot` - If given, erase the current snapshot.  If not specified\n  `tox` will use the current snapshot if it is less than\n  `CONTAINER_AGE` hours old (default: 24)\n* `--parallel N` - N is an integer which is the number of containers to run in\n  parallel.  See below.  The default is `0` which means playbooks will be run\n  sequentially.\n* `--log-dir PATH` - When using `--parallel` - for each test playbook named `TESTNAME.yml`\n  the log will be written to a file named `TESTNAME.log` in the `PATH` directory.\n  The default is the directory where `TESTNAME.yml` is found.\n* `--extra-rpm` - specifies an additional rpm package to install in the\n    container. Default to none. E.g., `--extra-rpm diffutils --extra-rpm sudo`\n* `--extra-skip-tag` - specifies a tag to skip. Default to none. E.g.,\n    `--extra-skip-tag \"tests::some_tag\"`\nEach additional command line argument is passed through to ansible-playbook, so\nit must either be an argument or a playbook.  If you want to pass both arguments\nand playbooks, separate them with a `--` on the command line:\n\n```\ntox -e container-ansible-core-2-20 -- --image-name centos-10 --become --become-user root -- tests/tests_default.yml\n```\n\nThis is because `tox` cannot tell the difference between an Ansible argument\nand a playbook.  If you do not have any ansible-playbook arguments, only\nplaybooks, you can omit the `--`:\n\n```\ntox -e container-ansible-core-2-20 -- --image-name centos-10 tests/tests_default.yml\n```\n\nIf you want to test a collection, you must use `tox -e collection` first.  Then\nspecify the path to the test playbook inside this collection:\n\n```\ntox -e collection\ntox -e container-ansible-core-2-20 -- --image-name centos-10 .tox/ansible_collections/fedora/linux-system-roles/tests/ROLE/tests_default.yml\n```\n\nExample:\n\n```\ntox -e container-ansible-core-2-20 -- --image-name centos-10 tests/tests_default.yml\n```\n\nThis will lookup `centos-10` in your `~/.config/linux-system-roles.json`, check\nif the local snapshot is more than `CONTAINER_AGE` hours old, if so will\n`podman pull` the `\"container\"` value, will create a local snapshot container of\nthis, will create a setup playbook based on the `\"setup\"` section in the config,\nwill save the snapshot and will run `ansible-playbook` with `-c podman` using\nthe local snapshot with `tests/tests_default.yml`.\n\nThe environment variables are useful for customizing in your local tox.ini.  For\nexample, if I want to use a custom location for my config, and I do not\nwant to use the profile_tasks plugin, I can do this:\n\n```ini\n[container_common]\nsetenv =\n    LSR_QEMU_CONFIG = /home/username/myconfig.json\n    LSR_QEMU_PROFILE = false\n```\n\n#### Parallel containers\n\nBy default, if you specify multiple playbooks, each one will be run sequentially\nin the same container by the same `ansible-playbook` command e.g.\n`ansible-playbook -c podman test1.yml ... testN.yml`. If you use `--parallel M`\nwith `M \u003e 1` then `tox` will run each playbook separately in separate containers\ne.g.\n\n```\n{ podman run -d ...; ansible-playbook -c podman test1.yml; } \u0026\n{ podman run -d ...; ansible-playbook -c podman test2.yml; } \u0026\n...\n{ podman run -d ...; ansible-playbook -c podman testN.yml; } \u0026\n\n```\n\nThe number `M` controls how many `podman` containers are running at a time.\nThere seems to be a limitation on the number of containers that can be run at\nthe same time.  For example, if there are 10 test playbooks, and you use\n`--parallel 3`, then `tox` will run `3` containers at the same time.  As soon as\none completes, it will start another one, until there are `3` running, or there\nare no more playbooks to run.\n\nNOTE: There seems to be a limitation on the number of containers that can be run\nin parallel.  In testing on my Fedora 36 laptop with 8 processors and lots of\nRAM, I can only run `3` at a time - using `4` will cause the containers to fail\nwith `dbus` errors - not sure what the issue is.\n\n### Image mode testing\n\nMany roles [are being updated](https://issues.redhat.com/browse/RHEL-78157) to\nwork during a bootc container image build to support\n[image mode](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux-10/image-mode).\nThese are tagged with `containerbuild` in meta/main.yml. If you are working on\na role and notice that container tests work, or you are fixing them, please add\nthat tag -- that will automatically enable the corresponding tests.\n\nThe image build phase tests work exactly like the general [container\ntests](#container-testing) above, except that it uses image names with a\n`-bootc` suffix, e.g. `--image-name centos-10-bootc`. Internally it will use\n[buildah](https://buildah.io/) instead of `podman` for a more realistic\ncontainer build environment.\n\nSome of these tests do a complete end-to-end testing: During the container test\nrun they call [`bootc-buildah-qcow.sh`](./src/tox_lsr/test_scripts/bootc-buildah-qcow.sh)\nto generate a QEMU qcow2 image from the container build. That uses\n[bootc-image-builder](https://github.com/osbuild/bootc-image-builder) which\nrequires real root privileges; to run these locally, you need to put your sudo\npassword into the [Ansible vault](#ansible-vault-support).\n\nThe end-to-end tests produce a qcow image in `tests/tmp/`*testname*`/qcow2/disk.qcow2`.\nThe validation phase ensures that running the role during container build\nactually has the desired effect in an image mode deployment. Run it through a\nQEMU environment, e.g.:\n\n```\ntox -e qemu-ansible-core-2-20 -- --image-file tests/tmp/tests_default/qcow2/disk.qcow2 \\\n    -e __bootc_validation=true -- tests/tests_default.yml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-system-roles%2Ftox-lsr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinux-system-roles%2Ftox-lsr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-system-roles%2Ftox-lsr/lists"}