{"id":24844570,"url":"https://github.com/jtyers/test.sh","last_synced_at":"2026-05-08T18:32:36.681Z","repository":{"id":109431680,"uuid":"87567855","full_name":"jtyers/test.sh","owner":"jtyers","description":"POSIX-compliant shell script unit test and mocking framework","archived":false,"fork":false,"pushed_at":"2020-08-10T16:36:29.000Z","size":17,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T08:18:14.843Z","etag":null,"topics":["bash","mocking","posix-sh","shell","unittest"],"latest_commit_sha":null,"homepage":null,"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/jtyers.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":"2017-04-07T16:53:16.000Z","updated_at":"2020-08-10T16:36:32.000Z","dependencies_parsed_at":"2023-03-13T14:12:55.216Z","dependency_job_id":null,"html_url":"https://github.com/jtyers/test.sh","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jtyers/test.sh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyers%2Ftest.sh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyers%2Ftest.sh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyers%2Ftest.sh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyers%2Ftest.sh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtyers","download_url":"https://codeload.github.com/jtyers/test.sh/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtyers%2Ftest.sh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32792114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"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":["bash","mocking","posix-sh","shell","unittest"],"created_at":"2025-01-31T09:30:52.385Z","updated_at":"2026-05-08T18:32:36.645Z","avatar_url":"https://github.com/jtyers.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# test.sh\nFrustrated when your well-tested app is let down by much-harder-to-test scripts doing non-app tasks? Can't unit test your scripts because they're fiddling with things that existing unit test frameworks can't mock/stub out?\n\nIf your script calls binaries like `sudo` or `mount`, or changes files in special places like `/proc` or `/sys`, how do you create a reliable test harness without resorting to using a chroot, VM or container?\n\nEnter `test.sh`.\n\n`test.sh` is a shell script unit test and mocking framework. It lets you mock *anything* - any command or shell built-in. It tracks which mocked-out commands are called and the parameters passed so you can assert on those later.\n\nImportantly, `test.sh` only supports testing shell *functions* right now, since that is how I structure my more complex shell scripts. But let's use a simple example to show you what `test.sh` can do.\n\n**NOTE** `test.sh` is new. I use it in my own business. That said, use it but expect it to go wrong on you occasionally. Pull requests and reporting of issues very welcome.\n\n## Requirements\n\n`test.sh` requires [jq](https://github.com/stedolan/jq) and `bash` to run.\n\n## Example\nSuppose I have a function, `create_file()`, which performs a mount, creates a file, calls `sync`, and unmounts.\n\n```bash\n#!/bin/sh\n\n# usage: create_file \u003cdevice to mount\u003e \u003cmount point\u003e \u003cfile name\u003e\ncreate_file() {\n\tlocal _dev=$1\n\tlocal _mp=$2\n\tlocal _fname=$3\n\n\tmount -o noatime,user $_dev $_mp\n\n\techo 'test data' \u003e $_mp/$_fname\n\n\tsync\n\tumount $_mp\n}\n```\n\nNow to unit test it. (Aside: I like to structure my tests in a BDD-like *given*, *when*, *then* style, but you don't have to)\n\n```bash\n#!/usr/bin/env test.sh\n\nsetup() {\n\tsource ./create_file.sh\n}\n\ntestMountAndCreateFiles() {\n\t# given\n\tdummy_device=\"/tmp/test-sh-dummy-device\"\n\tdummy_mountpoint=\"/tmp/test-sh-mp\"\n\tdummy_fname=\"foobar\"\n\n\tmkdir -p $dummy_device $dummy_mountpoint\n\n\tmock_cmd mount\n\tmock_cmd umount\n\tmock_cmd sync\n\n\t# when\n\tcreate_file $dummy_device $dummy_mountpoint $dummy_fname\n\n\t# then\n\n\t# check the file exists and contains the data we want\n\tassert_file_content $dummy_mountpoint/$dummy_fname 'test data'\n\n\t# check our mock commands are called as expected\n\tassert_called mount -o noatime,user $dummy_device $dummy_mountpoint\n\tassert_called sync\n\tassert_called umount $dummy_mountpoint\n}\n```\n\nSo, what's going on here?\n\nWe start with the `setup()` function, which is executed once before each test is run. You can do any setup you want here that applies to all tests. The minimum you need to do is *source your test file*. `test.sh` has no way of knowing the script you intend to test; thus you must source it here so that you can call its functions from your tests.\n\nFollowing `setup()` are your test functions. In the example above all my test functions begin with `test...`, but you can change this.\n\nFirst (in my *given* section), I set up a few pieces of test data and create the directories my script will expect. I then call `mock_cmd` for commands I want to mock; `mock_cmd` will create a shell function which does nothing, and name it after the command. The effect of this is that when my script calls `mount`, the mock function gets called and not the real `mount`. You can also pass simple statements to instruct the mock to do something; e.g. `mock_cmd mount echo mounted!`. `mock_cmd` will also automatically start tracking any calls that are made to the commands you've mocked, which we assert further on in the test.\n\nIn my *when* section I call the code I want to test, passing in my test data.\n\nThe *then* section is where I do my asserts. The asserts are nice and self-documenting where possible.\n* `assert_file_content` does exactly that, allowing you to specify a string that `test.sh` looks for (it has to be an *exact* match; this method of asserting is best for small one-line files, such as files in `/proc`, PID files and so on).\n* `assert_called` checks out mock to see if it was called with the arguments you specify. Notice how I passed in some fancy options to `mount`, and assert on those in the same line?\n\n## Running your tests\n`test.sh` can be run in one of two ways.\n\n- Hashbang: use `#!/usr/bin/env test.sh` or `#!/path/to/test.sh` in the first line of your script\n- Directly: run `/path/to/test.sh mytestfile`\n\n## Change the name of your tests\nBy default `test.sh` looks for functions beginning with the word `test`. Change this using `test.sh -p \u003cprefix\u003e mytestfile`. e.g. `test.sh -p should mytestfile` will look for all functions in `mytestfile` beginning with the string `should` and execute them all.\n\n## Testing order of calls\n`assert_called` by default checks the *most recent* call to a command. You might have a command called several times that you want to assert on. For example, a script that, given a read-only file system, mounts it `rw`, writes a file and remounts `ro`:\n\n```bash\n#!/bin/sh\n\n# usage: create_file \u003cmount point\u003e \u003cfile name\u003e\ncreate_file() {\n\tlocal _mp=$1\n\tlocal _fname=$2\n\n\tmount -o remount,rw $_mp\n\n\techo 'test data' \u003e $_mp/$_fname\n\n\tmount -o remount,ro $_mp\n}\n```\n\nAnd the unit test:\n\n```bash\n#!/usr/bin/env test.sh\n\ntestRemountWriteAndRemountAgain() {\n\t# given\n\tdummy_mountpoint=\"/tmp/test-sh-mp\"\n\tdummy_fname=\"foobar\"\n\n\tmkdir -p $dummy_mountpoint\n\n\tmock_cmd mount\n\n\t# when\n\tcreate_file $dummy_mountpoint $dummy_fname\n\n\t# then\n\n\t# check the file exists and contains the data we want\n\tassert_file_content $dummy_mountpoint/$dummy_fname 'test data'\n\n\t# check our mock commands are called in order\n\tassert_called_n 0 mount -o remount,rw $dummy_mountpoint\n\tassert_called_n 1 mount -o remount,ro $dummy_mountpoint\n}\n```\n\nIn this example, instead of `assert_called` we use `assert_called_n`, aka \"assert that X was called the nth time\". Behind the scenes is an array starting at 0, so to assert against the first call, we specify `assert_called_n 0`, the second call `assert_called_n 1` and so on.\n\n## Other asserts\nI've added asserts as I've use `test.sh` on my own projects. So far there is:\n* `assert_equal` - assert that the two arguments are equal\n* `assert_blank` - assert that the argument is blank\n* `assert_called`, `assert_called_n` - assert calls to mock commands created via `mock_cmd`\n* `assert_file_content \u003cfile\u003e \u003cstring\u003e` - assert that `file` contains content `string`\n* `assert_dir \u003cpath\u003e` - check a path exists and is a directory\n* `assert_file \u003cpath\u003e` - check a path exists and is a file\n* `assert_missing \u003cpath\u003e` - check a path does *not* exist\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtyers%2Ftest.sh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtyers%2Ftest.sh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtyers%2Ftest.sh/lists"}