{"id":13495225,"url":"https://github.com/lehmannro/assert.sh","last_synced_at":"2025-03-28T16:31:57.892Z","repository":{"id":726106,"uuid":"374129","full_name":"lehmannro/assert.sh","owner":"lehmannro","description":"bash unit testing framework","archived":false,"fork":false,"pushed_at":"2022-01-21T07:52:50.000Z","size":311,"stargazers_count":487,"open_issues_count":17,"forks_count":57,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-08-01T19:54:27.218Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lehmannro.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-11-15T23:26:30.000Z","updated_at":"2024-06-24T17:49:44.000Z","dependencies_parsed_at":"2022-07-18T12:19:07.906Z","dependency_job_id":null,"html_url":"https://github.com/lehmannro/assert.sh","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/lehmannro%2Fassert.sh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lehmannro%2Fassert.sh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lehmannro%2Fassert.sh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lehmannro%2Fassert.sh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lehmannro","download_url":"https://codeload.github.com/lehmannro/assert.sh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222395772,"owners_count":16977622,"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-07-31T19:01:32.691Z","updated_at":"2024-10-31T10:30:49.201Z","avatar_url":"https://github.com/lehmannro.png","language":"Shell","readme":"###########\n assert.sh\n###########\n\n**assert.sh** is test-driven development in the Bourne again shell.\n\n:Version: 1.1\n:Author: Robert Lehmann\n:License: LGPLv3\n\n.. image:: https://travis-ci.org/lehmannro/assert.sh.svg?branch=master\n   :target: https://travis-ci.org/lehmannro/assert.sh\n\nExample\n=======\n\n::\n\n  . assert.sh\n\n  # `echo test` is expected to write \"test\" on stdout\n  assert \"echo test\" \"test\"\n  # `seq 3` is expected to print \"1\", \"2\" and \"3\" on different lines\n  assert \"seq 3\" \"1\\n2\\n3\"\n  # exit code of `true` is expected to be 0\n  assert_raises \"true\"\n  # exit code of `false` is expected to be 1\n  assert_raises \"false\" 1\n  # end of test suite\n  assert_end examples\n\nIf you had written the above snippet into ``tests.sh`` you could invoke it\nwithout any extra hassle::\n\n  $ ./tests.sh\n  all 4 examples tests passed in 0.014s.\n\nWatch out to have ``tests.sh`` executable (``chmod +x tests.sh``), otherwise\nyou need to invoke it with ``bash tests.sh``.\n\nNow, we will add a failing test case to our suite::\n\n  # expect `exit 127` to terminate with code 128\n  assert_raises \"exit 127\" 128\n\nRemember to insert test cases before ``assert_end`` (or write another\n``assert_end`` to the end of your file). Otherwise test statistics will be\nomitted.\n\nWhen run, the output is::\n\n  test #5 \"exit 127\" failed:\n          program terminated with code 127 instead of 128\n  1 of 5 examples tests failed in 0.019s.\n\nThe overall status code is 1 (except if you modified the exit code manually)::\n\n  $ bash tests.sh\n  ...\n  $ echo $?\n  1\n\nFeatures\n========\n\n+ lightweight interface: ``assert`` and ``assert_raises`` *only*\n+ minimal setup -- source ``assert.sh`` and you're done\n+ test grouping in individual suites\n+ time benchmarks with real-time display of test progress\n+ run all tests, stop on first failure, or collect numbers only\n+ automatically set the exit status of the test script\n+ skip individual tests\n\nUse case\n========\n\nYou wrote an application. Following sane development practices, you want to\nprotect yourself against introducing errors with a test suite. Even though most\nlanguages have excellent testing tools, modifying process state (input ``stdin``,\ncommand line arguments ``argv``, environment variables) is awkard in most\nlanguages. The shell was made to do just that, so why don't run the tests in\nyour shell?\n\nInstallation\n============\n\nYou can easily install the latest release (or any other version)::\n\n  wget https://raw.github.com/lehmannro/assert.sh/v1.1/assert.sh\n\nUse the following command to grab a snapshot of the current development\nversion::\n\n  wget https://raw.github.com/lehmannro/assert.sh/master/assert.sh\n\nThere is no additional build/compile step except for changing permissions\n(``chmod +x``) depending on the way you have chosen to install *assert.sh*.\n\nbpkg\n----\n\nThe ``bpkg`` package manager allows you to install *assert.sh* locally::\n\n  bpkg install lehmannro/assert.sh\n\n(Watch out to ``source deps/assert/assert.sh`` instead.)\n\nIf you want to install globally, for your whole system, use::\n\n  bpkg install lehmannro/assert.sh -g\n\nReference\n=========\n\n+ ``assert \u003ccommand\u003e [stdout] [stdin]``\n\n  Check for an expected output when running your command. `stdout` supports all\n  control sequences ``echo -e`` interprets, eg. ``\\n`` for a newline. The\n  default `stdout` is assumed to be empty.\n\n+ ``assert_raises \u003ccommand\u003e [exitcode] [stdin]``\n\n  Verify `command` terminated with the expected status code. The default\n  `exitcode` is assumed to be 0.\n\n+ ``assert_end [suite]``\n\n  Finalize a test suite and print statistics.\n\n+ ``skip``\n\n  Unconditionally skip the following test case.  The skipped test case is\n  *exempt* from any test diagnostics (ie., not accounted for in the total\n  number of tests.)\n\n+ ``skip_if \u003ccommand\u003e``\n\n  Skip the following test case if `command` exits successfully.  (``skip``\n  disclaimer applies.)  Use this if you want to run a test only if some\n  precondition is met, eg. the test needs root privileges or network access.\n\nCommand line options\n--------------------\n\nSee ``assert.sh --help`` for command line options on test runners.\n\n  -v, --verbose    Generate real-time output for every individual test run.\n  -x, --stop       Stop running tests after the first failure.\n                   (Default: run all tests.)\n  -i, --invariant  Do not measure runtime for suites. Useful mainly to parse\n                   test output.\n  -d, --discover   Collect test suites and number of tests only; don't run any\n                   tests.\n  -c, --continue   Do not modify exit code depending on overall suite status.\n  -h               Show brief usage information and exit.\n  --help           Show usage manual and exit.\n\nEnvironment variables\n---------------------\n\n================= ====================\nvariable          corresponding option\n================= ====================\n``$DEBUG``        ``--verbose``\n``$STOP``         ``--stop``\n``$INVARIANT``    ``--invariant``\n``$DISCOVERONLY`` ``--discover-only``\n``$CONTINUE``     ``--continue``\n================= ====================\n\nChangelog\n=========\n\n1.1\n  * Added ``skip`` and ``skip_if`` commands.\n  * Added support for ``set -e`` environments (closes `#6\n    \u003chttps://github.com/lehmannro/assert.sh/pull/6\u003e`_, thanks David Schoen.)\n  * Modified exit code automatically in case *any* test failed in the suite.\n  * Added ``--continue`` flag to avoid tinkering with the exit code.\n  * Removed ``bc`` dependency (closes `#8\n    \u003chttps://github.com/lehmannro/assert.sh/issues/8\u003e`_, thanks Maciej Żok.)\n  * Added installation instructions for `bpkg \u003chttp://bpkg.io/\u003e`_ (closes `#9\n    \u003chttps://github.com/lehmannro/assert.sh/pull/9\u003e`_, thanks Joseph Werle.)\n\n1.0.2\n  * Fixed Mac OS compatibility (closes `#3\n    \u003chttps://github.com/lehmannro/assert.sh/issues/3\u003e`_.)\n\n1.0.1\n  * Added support for ``set -u`` environments (closes `#1\n    \u003chttps://github.com/lehmannro/assert.sh/issues/1\u003e`_.)\n  * Fixed several leaks of stderr.\n  * Fixed propagation of options to nested test suites.\n\nRelated projects\n================\n\n`Advanced Bash-Scripting Guide`__\n  An in-depth exploration of the art of shell scripting by The Linux\n  Documentation Project proposes a mechanism inspired by C, similar to\n  *assert.sh*.\n\n__ http://www.tldp.org/LDP/abs/html/debugging.html\n\n`ShUnit`__\n  ShUnit is a testing framework of the xUnit family for Bourne derived shells.\n  It is quite feature-rich but requires a whole lot of boilerplate to write a\n  basic test suite.  *assert.sh* aims to be lightweight and easy to setup.\n\n__ http://shunit.sourceforge.net/\n\n`shUnit2`__\n  shUnit2 is a modern xUnit-style testing framework. It comes with a bunch of\n  magic to remove unneccessary verbosity. It requires extra care when crafting\n  test cases with many subprocess invocations as you have to fall back to shell\n  features to fetch results.  *assert.sh* wraps this functionality out of the\n  box.\n\n__ http://code.google.com/p/shunit2/\n\n`tap-functions`__\n  A Test Anything Protocol (TAP) producer with an inherently natural-language-\n  style API.  Unfortunately it's only of draft quality and decouples the test\n  runner from analysis, which does not allow for *assert.sh* features such as\n  ``--collect-only`` and ``--stop``.\n\n__ http://testanything.org/wiki/index.php/Tap-functions\n\n`bats`__\n  Another TAP producer with syntactic sugar.  It depends on ``errexit``\n  environments (set -e) to run its tests such that *\"each line is an assertion\n  of truth.\"*\n\n__ https://github.com/sstephenson/bats\n\n`stub.sh`__\n  Helpers to fake binaries and bash builtins. It supports mocking features such\n  as expecting a certain number of invocations and plays well with *assert.sh*.\n\n__ https://github.com/jimeh/stub.sh\n","funding_links":[],"categories":["Shell","Shell Script Development","Applications"],"sub_categories":["Directory Navigation","Testing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flehmannro%2Fassert.sh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flehmannro%2Fassert.sh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flehmannro%2Fassert.sh/lists"}