Skip to content

🚦 A GitHub Action for asserting actual is expected in GitHub Workflows — designed for GitHub Action integration tests and robust build pipelines

License

Notifications You must be signed in to change notification settings

prompt/actions-assert

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Assert

A GitHub Action for asserting actual is expected in GitHub Workflows, designed for GitHub Action integration tests and robust build pipelines.

  • Cast action input values from strings to type for type safety
  • Distribute reusable assertions via npm
  • Write local Javascript assertions to meet project-specific testing needs
  • Run tests against multiple values using each
jobs:
  test-actor:
    runs-on: ubuntu-latest
    steps:
      - name: Test actor is @shrink
        uses: prompt/actions-assert@v4
        with:
          assertion: npm://@assertions/is-equal:v1
          actual: "${{ github.actor }}"
          expected: shrink

Jump to complete examples ↓

Outputs

Name Description Example
message Human readable result of the assertion Value is equal to expected "Hello, World!"
passed Boolean describing whether the assertion passed true
failed Boolean describing whether the assertion failed false

Inputs

Name Description Default Examples
assertion Reference to a supported assertion in source://name format npm://@assertions/is-equal:v1
local://is-even
expected Value the assertion is looking for Hello, World!
actual Value the assertion will test against the expected value ${{steps.fields.outputs.greeting}}
error-message Error message to output when assertion fails Commit does not include a distributable build
type A supported data type that actual and expected will be cast to before performing assertion string string json number
each Parse multi-line actual into many values and perform assertion against each false true false
local-path Path to directory containing local assertion ${{github.workspace}} .github/workflows/assertions
error-on-fail Report error in step when assertion fails true false
convert-empty-to-null[1] Convert empty input values to null true false

[1] convert-empty-to-null is a workaround for a GitHub Actions Runner bug #924

Data Types

Name Description
string A Javascript String
number A Javascript Number
json JavaScript value or object from JSON.parse()

Each

When each is enabled, the Action splits actual by new-line into multiple values and asserts against each value. The final result is an aggregate of each result: all individual assertions must pass for the aggregate to pass.

Assertions

An assertion is a Javascript function that accepts expected and actual parameters and then returns a Result. A Result has a boolean pass parameter and a message string.

module.exports = function (expected, actual) {
  return {
    pass: actual === expected,
    message: `compared ${actual} to ${expected}`
  }
}

Sources

The test builder resolves assertion references using source and name accepted in source://name format.

Source Resolved To Example
npm An npm package with an assertion as the main exported module npm://@assertions/is-equal:v1
local A Javascript file (on the runner's filesystem) that exports an assertion as default local://is-equal
npm
Version Pinning

📌 An npm assertion reference should include a valid npm package version. Unlike npm itself, an npm assertion reference without a version will default to v1 instead of latest.

ℹ️ assertion: npm://@assertions/is-equal
✅ assertion: npm://@assertions/is-equal:1
✅ assertion: npm://@assertions/is-equal:v1
✅ assertion: npm://@assertions/is-equal:v1.0.0
✅ assertion: npm://@assertions/is-equal:latest
@assertions

A collection of first-party assertions is available on npm within the @assertions organisation.

Package Test
@assertions/is-equal actual is equal in value to expected
@assertions/is-strictly-equal actual is equal in value and type to expected
@assertions/starts-with actual starts with expected
@assertions/directory-exists path expected exists and is a directory

Third-party assertions are discoverable via 🔎 actions-assert on npm.

Distributing Assertions

Add 🔖 actions-assert to package.json keywords for an assertion to be discoverable via npm search.

Examples

SemVer Aliases Are Prefixed

prompt/actions-semver-aliases generates aliases for a Semantic Version with an optional prefix, in this example, the job tests that the optional prefix is applied to each alias.

on: push

jobs:
  test-aliases-are-prefixed:
    runs-on: ubuntu-latest
    steps:
      - name: Generate SemVer aliases with prefix
        id: prefixed
        uses: prompt/actions-semver-aliases@v1
        with:
          version: "3.14.1"
          prefix: "v"
          major: true
          minor: false
      - name: Assert alias is prefixed
        uses: prompt/actions-assert@v4
        with:
          assertion: npm://@assertions/starts-with:v1
          each: true
          actual: "${{ steps.prefixed.outputs.list }}"
          expected: "v"
          error-message: "SemVer Alias is not prefixed with v"

A complete test Workflow for prompt/actions-semver-aliases using multiple assertions is available in .github/workflows/test.yml.

Delete Invalid Tags

A repository may restrict tags to commits that include a specific file; in this example, the job deletes a newly created tag if the distributable directory (dist) does not exist.

on:
  push:
    tags:
      - "**"

jobs:
  validate-tag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: prompt/actions-assert@v4
        with:
          assertion: npm://@assertions/directory-exists:v1
          expected: dist
          error-message: "A commit without a dist is not allowed to be tagged"
      - if: failure()
        name: Delete tag
        uses: prompt/actions-delete-tag@v1

Automatic Release Packaging

A Workflow packages the Action automatically when a collaborator created a new tag. Any reference to this Action in a Workflow must use a tag (mutable) or the commit hash of a tag (immutable).

✅ uses: prompt/actions-assert@v2
✅ uses: prompt/[email protected]
✅ uses: prompt/actions-assert@0d888b7601af756fff1ffc9d0d0dca8fcc214f0a
❌ uses: prompt/actions-assert@main

The blog post Package GitHub Actions automatically with GitHub Actions describes how this achieved.

About

🚦 A GitHub Action for asserting actual is expected in GitHub Workflows — designed for GitHub Action integration tests and robust build pipelines

Topics

Resources

License

Stars

Watchers

Forks