{"id":20102935,"url":"https://github.com/stackrox/helmtest","last_synced_at":"2025-10-29T10:13:37.044Z","repository":{"id":41989110,"uuid":"421864370","full_name":"stackrox/helmtest","owner":"stackrox","description":"helmtest is a Go-based framework for testing helm charts in various configurations","archived":false,"fork":false,"pushed_at":"2025-04-14T15:04:14.000Z","size":1763,"stargazers_count":13,"open_issues_count":9,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-14T16:23:42.763Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackrox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-27T15:04:09.000Z","updated_at":"2025-04-14T15:04:17.000Z","dependencies_parsed_at":"2023-12-18T12:25:04.062Z","dependency_job_id":"3f2e17e3-0980-42d7-8102-91f7d669e006","html_url":"https://github.com/stackrox/helmtest","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackrox%2Fhelmtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackrox%2Fhelmtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackrox%2Fhelmtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackrox%2Fhelmtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackrox","download_url":"https://codeload.github.com/stackrox/helmtest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252648486,"owners_count":21782395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-13T17:33:43.578Z","updated_at":"2025-10-29T10:13:31.995Z","avatar_url":"https://github.com/stackrox.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Package `helmtest`\n======\n\nThe `helmtest` package allows you to declaratively specify test suites for Helm charts. It specifically\nseeks to address two inconveniences of the \"normal\" Go unit test-based approach:\n- it allows testing a multitude of different configurations via a hierarchical, YAML-based specification\n  of test cases.\n- it makes writing assertions about the generated Kubernets objects easy, by using `jq` filters as the\n  assertion language.\n  \nFormat of a test\n=========\nA `helmtest` test is generally defined in a YAML file according to the format specified in `spec.go`.\nTests are organized in a hierarchical fashion, in the sense that a test may contain one or more\nsub-tests. Tests with no sub-tests are called \"leaf tests\", and other tests are called \"non-leaf tests\".\nA Helm chart is only rendered and checked against expectations in leaf tests; in such a setting,\nthe leaf test inherits certain properties from its non-leaf ancestors.\n\nThe general schema of a test is as follows:\n```yaml\nname: \"string\" # the name of the test (optional but strongly recommended). Auto-generated if left empty.\nrelease:  # Overrides for the Helm release properties. These are applied in root-to-leaf order.\n  name: \"string\"  # override for the Helm release name\n  namespace: \"string\"  # override for the Helm release namespace\n  revision: int # override for the Helm release revision\n  isInstall: bool # override for the \"IsInstall\" property of the release options\n  isUpgrade: bool # override for the \"IsUpgrade\" property of the release options\nserver:\n  visibleSchemas: # openAPI schema which is visible to helm, i.e. to check API resource availability\n  # all valid schemas are:\n  - kubernetes-1.20.2\n  - openshift-3.11.0\n  - openshift-4.1.0\n  - openshift-4.18\n  - com.coreos\n  availableSchemas: [] # openAPI schema to validate against, i.e. to validate if rendered objects could be applied\n  objects: # objects visible to Helm's k8s client, for example via the `lookup` function\n    # example object specification:\n    - apiVersion: string\n      kind: string\n      metadata:\n        name: string\n        namespace: string # optional for cluster-scoped objects\n  noInherit: bool # indicates that server-side settings should *not* be inherited from the enclosing scope\ncapabilities: # represents the .Capabilities in Helm\n  kubeVersion: string # the kubernetes version which is discoverable via `.Capabilities.KubeVersion`\nvalues:  # values as consumed by Helm via the `-f` CLI flag.\n  key: value\nset:  # alternative format for Helm values, as consumed via the `--set` CLI flag.\n  nes.ted.key: value\ndefs: |\n  # Sequence of jq \"def\" statements. Each def statement must be terminated with a semicolon (;). Defined functions\n  # are only visible in this and descendant scopes, but not in ancestor scopes.\n  def name: .metadata.name;\n\nexpectError: bool # indicates whether we can tolerate an error. If unset, inherit from the parent test, or\n                  # default to `false` at the root level.\nexpect: |\n  # Sequence of jq filters, one per line (or spanning multiple lines, where each continuation line must begin with a\n  # space).\n  # See the below section on the world model and special functions.\n  .objects[] | select(.metadata?.name? // \"\" == \"\")\n    | assertNotExist  # continuation line\ntests: []  # a list of sub-tests. Determines whether the test is a leaf test or non-leaf test.\n```\n\nA comprehensive set of hierarchically organized tests to be run against a Helm chart is called a \"suite\". Each suite\nis defined in a set of YAML files located in a single directory on the filesystem (a directory may hold at most one\nsuite). The properties of the top-level test in the suite (such as a common set of expectations or Helm values to be\ninherited by all tests) can be specified in a `suite.yaml` file within this directory. The `suite.yaml` file may be\nabsent, in which case there are no values, definitions, expectations etc. shared among all the tests in the suite. In\naddition to the tests specified in the `tests:` stanza of the `suite.yaml` file (if any), the tests of the suite are\nadditionally read from files with the extension `.test.yaml` in the suite directory. Note that any combination of\ndefining tests in the `suite.yaml` and in individual files may be used, these tests will then be combined. In\nparticular, it is possible to define arbitrary test suites either with only `.test.yaml` files, with only a `suite.yaml`\nfile, or with combinations thereof.\n\nInheritance\n----------------\nFor most fields in the test specification, a test will inherit the value from its parent test (which might use an\ninherited value as well, etc.). If an explicit value is given, this value\n- overrides the values from the parent for the following fields: `expectError` and the individual sub-fields of\n  `release`.\n- is merged with the values from the parent for the following fields: `values`, `set` (in such a way that the values\n  from the child take precedence).\n- is added to the values from the parents for the following fields: `expect`, `defs`.\n\nWorld model\n============\n\nAs stated above, expectations are written as `jq` filters (using `gojq` as an evaluation engine). Generally, a filter\nthat evaluates to a \"falsy\" value is treated as a violation. In contrast to normal JS/`jq` semantics, an empty list,\nobject, or string will also be treated as \"falsy\". The input to those filters (i.e., the `.` value at the start of\neach `jq` pipeline) is a JSON object containing anything that is relevant to the test execution, referred to as the\n\"world\". See [the world model documentation](./docs/world-model.md) for an explanation of what it contains.\n\nSpecial functions\n===============\n\nSee the [documentation on functions](./docs/functions.md) for an overview of what functions are available in filters,\nbeyond the ones known from `jq`.\n\nDebugging\n===============\n\n**Run a single test:**\n\nTo get the name of a single test:\n1. Run the whole test suite\n2. Look up the test to execute\n3. Copy the complete name from the CLI (or logs)\n\n```\n$ go test -run \"TestWithHelmtest/testdata/helmtest/some_values.test.yaml/some_example_test\"\n```\n\n**Print rendered manifests and values:**\n\n```\n- name: \"some example test\"\n  expect: |\n    .helm[]| toyaml | print                  ## Print all Helm values\n    .secrets[\"secret-name\"] | toyaml | print ## Print a specific object\n    .objects[]| toyaml | print               ## Print the complete rendered Helm chart\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackrox%2Fhelmtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackrox%2Fhelmtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackrox%2Fhelmtest/lists"}