{"id":19014297,"url":"https://github.com/elemental-mind/assertium-bash","last_synced_at":"2026-04-29T08:32:38.446Z","repository":{"id":135924067,"uuid":"394146605","full_name":"elemental-mind/assertium-bash","owner":"elemental-mind","description":"An assertion library for bash.","archived":false,"fork":false,"pushed_at":"2021-08-09T04:20:13.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-31T02:10:13.818Z","etag":null,"topics":["assertion-functions","assertion-library","assertions","bash","script","shell","testing"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/elemental-mind.png","metadata":{"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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-09T04:20:10.000Z","updated_at":"2023-05-21T19:11:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"8b4334da-c09f-4b18-bfb0-81fbb48ebd71","html_url":"https://github.com/elemental-mind/assertium-bash","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/elemental-mind/assertium-bash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-mind%2Fassertium-bash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-mind%2Fassertium-bash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-mind%2Fassertium-bash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-mind%2Fassertium-bash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elemental-mind","download_url":"https://codeload.github.com/elemental-mind/assertium-bash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-mind%2Fassertium-bash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32417534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["assertion-functions","assertion-library","assertions","bash","script","shell","testing"],"created_at":"2024-11-08T19:28:46.386Z","updated_at":"2026-04-29T08:32:38.418Z","avatar_url":"https://github.com/elemental-mind.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Assertium - Assertion library for bash\nAssertium exposes an easy to use assert function to use in bash scripts for unit testing purposes.\n\n# Example\nSource:\n````\nsource ./Assertium.sh\n...\n    local myNumber=100\n    local myString=\"Hello World\"\n    local myArray=(1 2 3 4 5 6 7 8 9)\n\n    assert $myNumber -gt 0\n    assert \"$myString\" == \"Hello World\"\n    assert \"$myString\" is alphabetic\n\n    assert myArray[@] none == 5         # -\u003e fails because a value of 5 is in the array\n    assert myArray[@] all is numeric\n\n    assert -f ./examples/HelloWorld.sh\n...\n````\nOutputs:\n````\nPass: 100 -gt 0\nPass: Hello World == Hello World\nPass: Hello World is alphabetic\nFAIL: myArray[@] none == 5\nPass: myArray[@] all is numeric\nPass: -f ./examples/HelloWorld.sh\n````\n\n# Installation\nTo use Assertium you only need the `Assertium.sh` file from the main branch of this repository on the machine where you intend to use it.\n\nOnce downloaded add the following line to your bash script to be able to use the `assert` function:\n\n```\nsource /path/to/Assertium.sh\n```\n\n# Usage\n## Assert values\n```\nassert $myNumber == 1                           # -\u003e Pass: 1 == 1\nassert $myNumber -eq 2                          # -\u003e FAIL: 1 -eq 2\nassert \"$myText\" == \"I equal this string!\"      # -\u003e Pass: ...\n```\nUsage is simple! If you know how to write an if condition in bash you know how to write an assertion: Put everything you would normally put into angle brackets after the assert function specifier. Instead of `if [ \u003cExpression\u003e ] ...` write `assert \u003cExpression\u003e`. \nMake sure that variables that might contain spaces are surrounded by either single or double quotes.\n\nAll comparison operators are supported: `=`, `==`, `!=`, `-eq`, `-gt`, `-ge`, `-lt`, `-le`, `-o`, `-a`. \n\nExpressions with preceding flags (like `-f` to check for file existance) are also possible - given that the second argment is not be one of the following values: `is`, `none`, `all`, `piecewise` or `returns`. To check which other flags are supported check the operator reference in the documentation.\n````\nassert -f ./file/which/should/exist\n```` \n## Assert types\n```\nassert $myNumber is numeric             # -\u003e Pass: 1 is numeric\nassert $myNumber is alphabetic          # -\u003e FAIL: 1 is alphabetic\nassert $myNumber is not alphabetic      # -\u003e Pass: 1 is not alphabetic\nassert \"$myText\" is string              # -\u003e Pass: ...\n```\nAssertium allows you to use the `is` operator to check the content type of a variable. You can negate the type by adding a not after the `is`. The syntax is as follows: `assert \u003cVariable\u003e is [not] \u003cType\u003e`. `Type` can be one of the following:\n- `Number`, `numerical`, `numeric`, `Integer`, `integer` to check for non-decimal numbers as content.\n- `String`, `string`, `Text`, `text` to check for a valid string (composed only of numbers, letters, and `.`, `,`, `?`, `!`).\n- `alphabetic` to check that a variable only contains letters.\n- `alphanumeric` to check that a variable only contains letters and numbers. Also true if only numbers or numbers are present.\n\n## Assert on values of an array\n```\nassert myArray[@] all -gt 0                             # -\u003e Pass: myArray[@] all -gt 0\nassert myArray[@] none == 10                            # -\u003e Pass: myArray[@] none == 10\nassert myArray[@] all is Integer                        # -\u003e Pass: myArray[@] all is Integer\nassert myArray[@] any is alphabetic                     # -\u003e FAIL: myArray[@] any is alphabetic\nassert myStrings[@] any == \"String I am looking for\"    # -\u003e Pass: ...\n```\nAssertium enables assertions on arrays as well. The syntax is as follows: `assert \u003cArrayReference\u003e \u003cQuantifier\u003e \u003cComparativeExpression\u003e`. `ArrayReference` is simply your array variable name followed by `[@]`. `ComparativeExpression` is the assertion operator followed by an optional comparative value (depending on the Expression type). `ComparativeExpression` must be comparative as of now (most of the file assertions don't work, for example). `Quantifier` can be one of the following:\n- `all` to ensure that `ComparativeExpression` evaluates to true on all elements of the array.\n- `none` to ensure that `ComparativeExpression` evaluates to false on all elements of the array.\n- `any` to ensure that `ComparativeExpression` evaluates to true on at least one element of the array.\n\u003e :warning: Make sure to pass the array \"by reference\" -\u003e Only use your array name followed by `[@]` like in the example above. Nothing else. Do not destructure the array through `${myArray[@]}` or any similar forms.\n\n## Assert between arrays\n```\nassert myArray[@] piecewise == myArrayCopy[@]           # -\u003e Pass: myArray[@] piecewise == myArrayCopy[@]\nassert myArray[@] piecewise -gt myMultipliedArray[@]    # -\u003e Pass: myArray[@] piecewise -gt myMultipliedArray[@]\nassert myTextArray[@] piecewise != myMirroredStrings[@] # -\u003e Pass: myTextArray[@] piecewise != myMirroredStrings[@]\n```\nTo compare two arrays element by element use the `piecewise` operator. The syntax is as follows: `assert \u003cArrayReference1\u003e piecewise \u003cComparativeOperator\u003e \u003cArrayReference2\u003e`.\n\u003e :warning: Make sure to pass both arrays \"by reference\" -\u003e Only use your array name followed by `[@]` like in the example above. Nothing else. Do not destructure the arrays through `${myArray[@]}` or any similar forms.\n\n## Full assertion expression reference\nAn exhaustive list of expressions can be found in the documentation in the following path of this repository: `documentation/OperatorReference.md`\n\n# Output/Return values\n## Exit code\nA call to `assert` sets an exit code through `return` depending on the truthiness of the assertion. As an exit code of 0 is generally regarded as successful `0` is used to signal an assertion pass and `1`to signal a failed assertion. Quite unintuitive if you are used to boolean true or false, I know - however this is in line with bash's interpretation of return value truthiness in the if function for example.\n\nTo get the return value after calling `assert` use the `$?` return value variable.\n````\nassert $myVar is numerical\n\nif [ $? == 0 ]\nthen\n    echo Test succeeded!\nelse\n    echo Test failed!\nfi\n````\n## Console output\nBy default Assertium prints assertion results to the console. Passing assertions will be printed in green and preceded by `Pass: `, failing ones will be printed in red and preceded by `FAIL: `. If you'd like to suppress output you can wrap your assertion in a nested expression: `$(assert ...)`.\n\n# Common Questions \u0026 Issues\n## My assertion breaks my code\nThe most common error you will get is:\n```\ntest: too many arguments\n```\nYou probably have passed a string without quotes to the assertion or have passed an array as values (and not by reference). Should you not have done either, raise an issue here providing your sample input.\n\n## My assertion evaluates to true in my code and I don't know why.\nMake sure you don't call any other function between your `assert` call and queriying `$?` - even a simple call to `echo` sets `$?` back to 0.\n\n## I do not want console output/I want different output\nNo problem. You have two options here:\n- Replace all your calls to `assert` with `assert_base`. `assert_base` has the same API - and also sets the same exit code as `assert` that you can grab through `$?` after running `assert_base`.\n- Jump into the source: Change line 9 and 12 in `Assertium.sh` to any output you fancy.\n\n# Contributing\nContributions welcome! Feel free to send pull requests to fix bugs that you have discovered or to add functionality you were missing. Added tests in the `specification/Assertium.h` are a bonus.\n \nTopics that might need attention are:\n- Support for regular expressions as comparisons: Support for `assert \"$myString\" =~ \"^[A-B]+$\"`. For that the test command yould have to replaced with `[[ ]]`. \n- Non-comparative file array assertions: Support e.g. `assert myFilePaths[@] all -f`.\n- Enhanced string assertions: Support operators like `assert $myVar startsWith \"abc\"`, `... contains ...`, `... endsWith ...` to ease readibility by not relying on regular expressions.\n\n# License\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felemental-mind%2Fassertium-bash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felemental-mind%2Fassertium-bash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felemental-mind%2Fassertium-bash/lists"}