{"id":23108186,"url":"https://github.com/prompt/actions-assert","last_synced_at":"2025-08-16T17:32:24.521Z","repository":{"id":49132005,"uuid":"372913691","full_name":"prompt/actions-assert","owner":"prompt","description":":vertical_traffic_light: A GitHub Action for asserting actual is expected in GitHub Workflows — designed for GitHub Action integration tests and robust build pipelines","archived":false,"fork":false,"pushed_at":"2023-08-11T16:47:20.000Z","size":1003,"stargazers_count":5,"open_issues_count":9,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-08T12:56:40.347Z","etag":null,"topics":["assertions","github-actions","github-workflows","testing-tools","workflows"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/prompt.png","metadata":{"funding":{"github":"pr-mpt"},"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-06-01T17:37:29.000Z","updated_at":"2024-12-02T13:57:14.000Z","dependencies_parsed_at":"2023-01-05T13:23:07.669Z","dependency_job_id":null,"html_url":"https://github.com/prompt/actions-assert","commit_stats":null,"previous_names":["prompt/actions-assert","pr-mpt/actions-assert"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/prompt/actions-assert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prompt%2Factions-assert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prompt%2Factions-assert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prompt%2Factions-assert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prompt%2Factions-assert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prompt","download_url":"https://codeload.github.com/prompt/actions-assert/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prompt%2Factions-assert/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270746564,"owners_count":24638368,"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","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["assertions","github-actions","github-workflows","testing-tools","workflows"],"created_at":"2024-12-17T01:17:41.690Z","updated_at":"2025-08-16T17:32:24.252Z","avatar_url":"https://github.com/prompt.png","language":"TypeScript","funding_links":["https://github.com/sponsors/pr-mpt"],"categories":[],"sub_categories":[],"readme":"# Assert\n\nA GitHub Action for asserting **actual** is **expected** in GitHub Workflows,\ndesigned for GitHub Action integration tests and robust build pipelines.\n\n- Cast action input values from strings to `type` for type safety\n- Distribute reusable assertions via npm\n- Write local Javascript assertions to meet project-specific testing needs\n- Run tests against multiple values using `each`\n\n```yaml\njobs:\n  test-actor:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Test actor is @shrink\n        uses: prompt/actions-assert@v4\n        with:\n          assertion: npm://@assertions/is-equal:v1\n          actual: \"${{ github.actor }}\"\n          expected: shrink\n```\n\n[Jump to complete examples \u0026darr;](#examples)\n\n## Outputs\n\n| Name      | Description                                     | Example                                      |\n| :-------- | :---------------------------------------------- | :------------------------------------------- |\n| `message` | Human readable result of the assertion          | `Value is equal to expected \"Hello, World!\"` |\n| `passed`  | Boolean describing whether the assertion passed | `true`                                       |\n| `failed`  | Boolean describing whether the assertion failed | `false`                                      |\n\n## Inputs\n\n| Name                                  | Description                                                                                                   | Default                 | Examples                                                      |\n| :------------------------------------ | :------------------------------------------------------------------------------------------------------------ | :---------------------- | :------------------------------------------------------------ |\n| **`assertion`**                       | **Reference to a supported [assertion](#assertions) in `source://name` format**                               |                         | **`npm://@assertions/is-equal:v1`**\u003cbr/\u003e**`local://is-even`** |\n| `expected`                            | Value the assertion is looking for                                                                            |                         | `Hello, World!`                                               |\n| `actual`                              | Value the assertion will test against the expected value                                                      |                         | `${{steps.fields.outputs.greeting}}`                          |\n| `error-message`                       | Error message to output when assertion fails                                                                  |                         | `Commit does not include a distributable build`               |\n| `type`                                | A supported [data type](#data-types) that `actual` and `expected` will be cast to before performing assertion | `string`                | `string` `json` `number`                                      |\n| `each`                                | Parse multi-line `actual` into many values and perform assertion against each                                 | `false`                 | `true` `false`                                                |\n| `local-path`                          | Path to directory containing `local` assertion                                                                | `${{github.workspace}}` | `.github/workflows/assertions`                                |\n| `error-on-fail`                       | Report error in step when assertion fails                                                                     | `true`                  | `false`                                                       |\n| `convert-empty-to-null`\u003csup\u003e[1]\u003c/sup\u003e | Convert empty input values to null                                                                            | `true`                  | `false`                                                       |\n\n[1] `convert-empty-to-null` is a workaround for a\n[GitHub Actions Runner bug #924][runner/empty-input-bug]\n\n### Data Types\n\n| Name     | Description                                                                               |\n| :------- | :---------------------------------------------------------------------------------------- |\n| `string` | A Javascript [`String`\u003csup\u003e\u0026neArr;\u003c/sup\u003e][javascript/string]                              |\n| `number` | A Javascript [`Number`\u003csup\u003e\u0026neArr;\u003c/sup\u003e][javascript/number]                              |\n| `json`   | JavaScript value or object from [`JSON.parse()`\u003csup\u003e\u0026neArr;\u003c/sup\u003e][javascript/json/parse] |\n\n### Each\n\nWhen `each` is enabled, the Action splits `actual` by new-line into multiple\nvalues and asserts against each value. The final result is an aggregate of each\nresult: all individual assertions must pass for the aggregate to pass.\n\n### Assertions\n\nAn `assertion` is a Javascript function that accepts `expected` and `actual`\nparameters and then returns a `Result`. A `Result` has a boolean `pass`\nparameter and a `message` string.\n\n```javascript\nmodule.exports = function (expected, actual) {\n  return {\n    pass: actual === expected,\n    message: `compared ${actual} to ${expected}`\n  }\n}\n```\n\n#### Sources\n\nThe test builder resolves assertion references using `source` and `name`\naccepted in `source://name` format.\n\n| Source  | Resolved To                                                                                                                  | Example                         |\n| :------ | :--------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |\n| `npm`   | An [npm\u003csup\u003e\u0026neArr;\u003c/sup\u003e][npm] package with an assertion as the [main exported module\u003csup\u003e\u0026neArr;\u003c/sup\u003e][package.json/main] | `npm://@assertions/is-equal:v1` |\n| `local` | A Javascript file (on the runner's filesystem) that exports an assertion as default                                          | `local://is-equal`              |\n\n##### `npm`\n\n###### Version Pinning\n\n:pushpin: An npm assertion reference **should** include a valid npm package\nversion. Unlike npm itself, an npm assertion reference without a version will\ndefault to `v1` instead of `latest`.\n\n```yaml\nℹ️ assertion: npm://@assertions/is-equal\n✅ assertion: npm://@assertions/is-equal:1\n✅ assertion: npm://@assertions/is-equal:v1\n✅ assertion: npm://@assertions/is-equal:v1.0.0\n✅ assertion: npm://@assertions/is-equal:latest\n```\n\n###### @assertions\n\nA collection of first-party assertions is available on npm within the\n[`@assertions`\u003csup\u003e\u0026neArr;\u003c/sup\u003e][npm/@assertions] organisation.\n\n| Package                         | Test                                              |\n| :------------------------------ | :------------------------------------------------ |\n| [@assertions/is-equal]          | `actual` is equal in value to `expected`          |\n| [@assertions/is-strictly-equal] | `actual` is equal in value and type to `expected` |\n| [@assertions/starts-with]       | `actual` starts with `expected`                   |\n| [@assertions/directory-exists]  | path `expected` exists and is a directory         |\n\nThird-party assertions are discoverable via\n[:mag_right: `actions-assert` on npm][npm/search].\n\n###### Distributing Assertions\n\nAdd :bookmark: `actions-assert` to\n[package.json `keywords`\u003csup\u003e\u0026neArr;\u003c/sup\u003e][package.json/keywords] for an\nassertion to be discoverable via [npm search\u003csup\u003e\u0026neArr;\u003c/sup\u003e][npm/search].\n\n## Examples\n\n### SemVer Aliases Are Prefixed\n\n[prompt/actions-semver-aliases] generates aliases for a Semantic Version with an\noptional prefix, in this example, the job tests that the optional prefix is\napplied to each alias.\n\n```yaml\non: push\n\njobs:\n  test-aliases-are-prefixed:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Generate SemVer aliases with prefix\n        id: prefixed\n        uses: prompt/actions-semver-aliases@v1\n        with:\n          version: \"3.14.1\"\n          prefix: \"v\"\n          major: true\n          minor: false\n      - name: Assert alias is prefixed\n        uses: prompt/actions-assert@v4\n        with:\n          assertion: npm://@assertions/starts-with:v1\n          each: true\n          actual: \"${{ steps.prefixed.outputs.list }}\"\n          expected: \"v\"\n          error-message: \"SemVer Alias is not prefixed with v\"\n```\n\nA complete test Workflow for [prompt/actions-semver-aliases] using multiple\nassertions is available in\n[`.github/workflows/test.yml`][prompt/actions-semver-aliases/tests].\n\n### Delete Invalid Tags\n\nA repository may restrict tags to commits that include a specific file; in this\nexample, the job deletes a newly created tag if the distributable directory\n(`dist`) does not exist.\n\n```yaml\non:\n  push:\n    tags:\n      - \"**\"\n\njobs:\n  validate-tag:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n      - uses: prompt/actions-assert@v4\n        with:\n          assertion: npm://@assertions/directory-exists:v1\n          expected: dist\n          error-message: \"A commit without a dist is not allowed to be tagged\"\n      - if: failure()\n        name: Delete tag\n        uses: prompt/actions-delete-tag@v1\n```\n\n## Automatic Release Packaging\n\nA Workflow packages the Action automatically when a collaborator created a new\ntag. Any reference to this Action in a Workflow must use a [tag][tags] (mutable)\nor the commit hash of a tag (immutable).\n\n```yaml\n✅ uses: prompt/actions-assert@v2\n✅ uses: prompt/actions-assert@v2.0.0\n✅ uses: prompt/actions-assert@0d888b7601af756fff1ffc9d0d0dca8fcc214f0a\n❌ uses: prompt/actions-assert@main\n```\n\nThe blog post\n[Package GitHub Actions automatically with GitHub Actions][blog/package-automatically]\ndescribes how this achieved.\n\n[javascript/string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String\n[javascript/number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number\n[javascript/json/parse]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse\n[prompt/actions-semver-aliases]: https://github.com/prompt/actions-semver-aliases\n[npm]: https://npmjs.com\n[npm/search]: https://www.npmjs.com/search?q=keywords%3Aactions-assert\n[package.json/main]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#main\n[package.json/keywords]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#keywords\n[@assertions/is-equal]: https://npmjs.com/package/@assertions/is-equal\n[@assertions/is-strictly-equal]: https://npmjs.com/package/@assertions/is-strictly-equal\n[@assertions/starts-with]: https://npmjs.com/package/@assertions/starts-with\n[@assertions/directory-exists]: https://npmjs.com/package/@assertions/directory-exists\n[npm/@assertions]: https://www.npmjs.com/org/assertions\n[workflows/workspace]: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context\n[blog/package-automatically]: https://medium.com/prompt/package-github-actions-automatically-with-github-actions-a70b9f7bae4\n[tags]: https://github.com/prompt/actions-assert/tags\n[prompt/actions-semver-aliases/tests]: https://github.com/prompt/actions-semver-aliases/blob/main/.github/workflows/test.yml\n[runner/empty-input-bug]: https://github.com/actions/runner/issues/924\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprompt%2Factions-assert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprompt%2Factions-assert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprompt%2Factions-assert/lists"}