name mode size
.Installers 040000
docs 040000
getting_started 040000
img 040000
tests 040000
.gitattributes 100644 28B
.gitignore 100644 79B
CONTRIBUTING.md 100644 1.67kB
CONTRIBUTING_CODE.md 100644 95B
Go to apbin copy 100755 62B
Go to workspace copy 100755 93B
LICENSE-GPL3 100644 35.15kB
README.md 100644 20.52kB
Update apbin copy 100644 262B
bash_unit 100755 19.48kB
location-of-bash-unit 100755 194B
release 100755 2.07kB
README.md
# bash_unit, modified by Apollia Note by Apollia, 04:47:02 10/04/2020: The original author of bash_unit is Pascal Grange. The official bash_unit repo: [https://github.com/pgrange/bash_unit](https://github.com/pgrange/bash_unit) <br>Apollia's modified version of bash_unit: [https://apollia.org/gitlist/bash_unit.git](https://apollia.org/gitlist/bash_unit.git) Please see this repo's commit history for summaries of my changes. [https://apollia.org/gitlist/bash_unit.git/commits/master](https://apollia.org/gitlist/bash_unit.git/commits/master) <br>Since at least 2018, bash_unit has been my favorite way to run unit tests on my Bash programs. Thanks to the original author Pascal Grange, and all the contributors, for making bash_unit so excellent! End of text by Apollia. ---- ![bash\_unit](img/bu_50.png) bash\_unit - bash unit testing enterprise edition framework for professionals ! Synopsis ======== **bash\_unit** \[-f tap\] \[-p &lt;pattern&gt;\] \[test\_file\] Description =========== **bash\_unit** allows you to write unit tests (functions starting with **test**), run them and, in case of failure, displays the stack trace with source file and line number indications to locate the problem. You might want to take a look at [how to get started](getting_started) before continuing reading this documentation. *(by the way, the documentation you are reading is itself tested with bash-unit)* **bash\_unit** is free software you may contribute to. See [CONTRIBUTING.md](CONTRIBUTING.md). Options ======= **-p** *pattern* filters tests to run based on the given pattern. You can specify several patterns by repeating this option for each pattern. **-f** *output\_format* specify an alternative output format. The only supported value is **tap**. How to install **bash\_unit** ============================= installing on Debian/Ubuntu --------------------------- **bash\_unit** deb package is available in the [bash-unit\_deb repo](https://github.com/pgrange/bash-unit_deb/releases). You may install it with the following commands: \`\`\`bash curl <https://pgrange.github.io/bash-unit_deb/keys.asc> | sudo apt-key add - echo deb <https://pgrange.github.io/bash-unit_deb/debian/> unstable/ | sudo tee -a /etc/apt/sources.list.d/bash-unit.list sudo apt update sudo apt install bash-unit \`\`\` installing on Archlinux ----------------------- **bash\_unit** package is available on Archlinux through AUR. In order to install, issue the following command : yaourt -Sys bash_unit other installation ------------------ This will install **bash\_unit** in your current working directory: bash <(curl -s https://raw.githubusercontent.com/pgrange/bash_unit/master/install.sh) You can also download it from the [release page](https://github.com/pgrange/bash_unit/releases). How to run tests ================ To run tests, simply call **bash\_unit** with all your tests files as parameter. For instance to run some **bash\_unit** tests, from **bash\_unit** directory: \`\`\`test ./bash\_unit tests/test\_core.sh \`\`\` \`\`\`output Running tests in tests/test\_core.sh Running test\_assert\_equals\_fails\_when\_not\_equal… SUCCESS Running test\_assert\_equals\_succeed\_when\_equal… SUCCESS Running test\_assert\_fails… SUCCESS Running test\_assert\_fails\_fails… SUCCESS Running test\_assert\_fails\_succeeds… SUCCESS Running test\_assert\_not\_equals\_fails\_when\_equal… SUCCESS Running test\_assert\_not\_equals\_succeeds\_when\_not\_equal… SUCCESS Running test\_assert\_shows\_stderr\_on\_failure… SUCCESS Running test\_assert\_shows\_stdout\_on\_failure… SUCCESS Running test\_assert\_status\_code\_fails… SUCCESS Running test\_assert\_status\_code\_succeeds… SUCCESS Running test\_assert\_succeeds… SUCCESS Running test\_fail\_fails… SUCCESS Running test\_fail\_prints\_failure\_message… SUCCESS Running test\_fail\_prints\_where\_is\_error… SUCCESS Running test\_fake\_actually\_fakes\_the\_command… SUCCESS Running test\_fake\_can\_fake\_inline… SUCCESS Running test\_fake\_echo\_stdin\_when\_no\_params… SUCCESS Running test\_fake\_exports\_faked\_in\_subshells… SUCCESS Running test\_fake\_transmits\_params\_to\_fake\_code… SUCCESS \`\`\` You might also want to run only specific tests, you may do so with the *-p* option. This option accepts a pattern as parameter and filters test functions against this pattern. \`\`\`test ./bash\_unit -p fail\_fails -p assert tests/test\_core.sh \`\`\` \`\`\`output Running tests in tests/test\_core.sh Running test\_assert\_equals\_fails\_when\_not\_equal… SUCCESS Running test\_assert\_equals\_succeed\_when\_equal… SUCCESS Running test\_assert\_fails… SUCCESS Running test\_assert\_fails\_fails… SUCCESS Running test\_assert\_fails\_succeeds… SUCCESS Running test\_assert\_not\_equals\_fails\_when\_equal… SUCCESS Running test\_assert\_not\_equals\_succeeds\_when\_not\_equal… SUCCESS Running test\_assert\_shows\_stderr\_on\_failure… SUCCESS Running test\_assert\_shows\_stdout\_on\_failure… SUCCESS Running test\_assert\_status\_code\_fails… SUCCESS Running test\_assert\_status\_code\_succeeds… SUCCESS Running test\_assert\_succeeds… SUCCESS Running test\_fail\_fails… SUCCESS \`\`\` **bash\_unit** supports the [Test Anything Protocol](http://testanything.org/) so you can ask for a tap formatted output with the *-f* option. \`\`\`test ./bash\_unit -f tap tests/test\_core.sh \`\`\` \`\`\`output \# Running tests in tests/test\_core.sh ok - test\_assert\_equals\_fails\_when\_not\_equal ok - test\_assert\_equals\_succeed\_when\_equal ok - test\_assert\_fails ok - test\_assert\_fails\_fails ok - test\_assert\_fails\_succeeds ok - test\_assert\_not\_equals\_fails\_when\_equal ok - test\_assert\_not\_equals\_succeeds\_when\_not\_equal ok - test\_assert\_shows\_stderr\_on\_failure ok - test\_assert\_shows\_stdout\_on\_failure ok - test\_assert\_status\_code\_fails ok - test\_assert\_status\_code\_succeeds ok - test\_assert\_succeeds ok - test\_fail\_fails ok - test\_fail\_prints\_failure\_message ok - test\_fail\_prints\_where\_is\_error ok - test\_fake\_actually\_fakes\_the\_command ok - test\_fake\_can\_fake\_inline ok - test\_fake\_echo\_stdin\_when\_no\_params ok - test\_fake\_exports\_faked\_in\_subshells ok - test\_fake\_transmits\_params\_to\_fake\_code \`\`\` How to write tests ================== Write your test functions in a file. The name of a test function has to start with **test**. Only functions starting with **test** will be tested. Use the **bash\_unit** assertion functions in your test functions, see below. You may write a **setup** function that will be executed before each test is run. You may write a **teardown** function that will be executed after each test is run. You may write a **setup\_suite** function that will be executed only once before all the tests of your test file. You may write a **teardown\_suite** function that will be executed only once after all the tests of your test file. If you write code outside of any bash function, this code will be executed once at test file loading time since your file is a bash script and **bash\_unit** sources it before running your tests. It is suggested to write a **setup\_suite** function and avoid any code outside a bash function. If you want to keep an eye on a test not yet implemented, prefix the name of the function by **todo** instead of test. Test to do are not executed and do not impact the global status of your test suite but are displayed in **bash\_unit** output. **bash\_unit** changes the current working directory to the one of the running test file. If you need to access files from your test code, for instance the script under test, use path relative to the test file. You may need to change the behavior of some commands to create conditions for your code under test to behave as expected. The **fake** function may help you to do that, see bellow. Test functions ============== **bash\_unit** supports several shell oriented assertion functions. **fail** -------- fail [message] Fails the test and displays an optional message. \`\`\`test test\_can\_fail() { fail "this test failed on purpose" } \`\`\` \`\`\`output Running test\_can\_fail… FAILURE this test failed on purpose doc:2:test\_can\_fail() \`\`\` **assert** ---------- assert <assertion> [message] Evaluates *assertion* and fails if *assertion* fails. *assertion* fails if its evaluation returns a status code different from 0. In case of failure, the standard output and error of the evaluated *assertion* is displayed. The optional message is also displayed. \`\`\`test test\_assert\_fails() { assert false "this test failed, obvioulsy" } test\_assert\_succeed() { assert true } \`\`\` \`\`\`output Running test\_assert\_fails… FAILURE this test failed, obvioulsy doc:2:test\_assert\_fails() Running test\_assert\_succeed… SUCCESS \`\`\` But you probably want to assert less obvious facts. \`\`\`test code() { touch /tmp/the\_file } test\_code\_creates\_the\_file() { code assert "test -e /tmp/the_file" } test\_code\_makes\_the\_file\_executable() { code assert "test -x /tmp/the_file" "/tmp/the_file should be executable" } ``` \`\`\`output Running test\_code\_creates\_the\_file… SUCCESS Running test\_code\_makes\_the\_file\_executable… FAILURE /tmp/the\_file should be executable doc:14:test\_code\_makes\_the\_file\_executable() \`\`\` It may also be fun to use assert to check for the expected content of a file. \`\`\`test code() { echo *not so cool* &gt; /tmp/the\_file } test\_code\_write\_appropriate\_content\_in\_the\_file() { code assert "diff <(echo 'this is cool') /tmp/the_file" } ``` \`\`\`output Running test\_code\_write\_appropriate\_content\_in\_the\_file… FAILURE out&gt; 1c1 out&gt; &lt; this is cool out&gt; --- out&gt; &gt; not so cool doc:8:test\_code\_write\_appropriate\_content\_in\_the\_file() \`\`\` **assert\_fail** ---------------- assert_fail <assertion> [message] Asserts that *assertion* fails. This is the opposite of **assert**. *assertion* fails if its evaluation returns a status code different from 0. If the evaluated expression does not fail, then **assert\_fail** will fail and display the standard output and error of the evaluated *assertion*. The optional message is also displayed. \`\`\`test code() { echo *not so cool* &gt; /tmp/the\_file } test\_code\_does\_not\_write\_cool\_in\_the\_file() { code assert_fails "grep cool /tmp/the_file" "should not write 'cool' in /tmp/the_file" } test\_code\_does\_not\_write\_this\_in\_the\_file() { code assert_fails "grep this /tmp/the_file" "should not write 'this' in /tmp/the_file" } ``` \`\`\`output Running test\_code\_does\_not\_write\_cool\_in\_the\_file… FAILURE should not write *cool* in /tmp/the\_file out&gt; not so cool doc:8:test\_code\_does\_not\_write\_cool\_in\_the\_file() Running test\_code\_does\_not\_write\_this\_in\_the\_file… SUCCESS \`\`\` **assert\_status\_code** ------------------------ assert_status_code <expected_status_code> <assertion> [message] Checks for a precise status code of the evaluation of *assertion*. It may be useful if you want to distinguish between several error conditions in your code. In case of failure, the standard output and error of the evaluated *assertion* is displayed. The optional message is also displayed. \`\`\`test code() { exit 23 } test\_code\_should\_fail\_with\_code\_25() { assert\_status\_code 25 code } \`\`\` \`\`\`output Running test\_code\_should\_fail\_with\_code\_25… FAILURE expected status code 25 but was 23 doc:6:test\_code\_should\_fail\_with\_code\_25() \`\`\` **assert\_equals** ------------------ assert_equals <expected> <actual> [message] Asserts for equality of the two strings *expected* and *actual*. \`\`\`test test\_obvious\_inequality\_with\_assert\_equals(){ assert\_equals "a string" "another string" "a string should be another string" } test\_obvious\_equality\_with\_assert\_equals(){ assert\_equals a a } \`\`\` \`\`\`output Running test\_obvious\_equality\_with\_assert\_equals… SUCCESS Running test\_obvious\_inequality\_with\_assert\_equals… FAILURE a string should be another string expected \[a string\] but was \[another string\] doc:2:test\_obvious\_inequality\_with\_assert\_equals() \`\`\` **assert\_not\_equals** ----------------------- assert_not_equals <unexpected> <actual> [message] Asserts for inequality of the two strings *unexpected* and *actual*. \`\`\`test test\_obvious\_equality\_with\_assert\_not\_equals(){ assert\_not\_equals "a string" "a string" "a string should be different from another string" } test\_obvious\_inequality\_with\_assert\_not\_equals(){ assert\_not\_equals a b } \`\`\` \`\`\`output Running test\_obvious\_equality\_with\_assert\_not\_equals… FAILURE a string should be different from another string expected different value than \[a string\] but was the same doc:2:test\_obvious\_equality\_with\_assert\_not\_equals() Running test\_obvious\_inequality\_with\_assert\_not\_equals… SUCCESS \`\`\` **fake** function ================= fake <command> [replacement code] Fakes *command* and replaces it with *replacement code* (if code is specified) for the rest of the execution of your test. If no replacement code is specified, then it replaces command by one that echoes stdin of fake. This may be useful if you need to simulate an environment for you code under test. For instance: \`\`\`test fake ps echo hello world ps \`\`\` will output: \`\`\`output hello world \`\`\` We can do the same using *stdin* of fake: \`\`\`test fake ps &lt;&lt; EOF hello world EOF ps \`\`\` \`\`\`output hello world \`\`\` It has been asked wether using **fake** results in creating actual fakes or stubs or mocks? or may be spies? or may be they are dummies? The first answer to this question is: it depends. The second is: read this [great and detailed literature](https://www.google.fr/search?tbm=isch&q=fake%20mock%20stub) on this subjet. Using stdin ----------- Here is an exemple, parameterizing fake with its *stdin* to test that code fails when some process does not run and succeeds otherwise: \`\`\`test code() { ps a | grep apache } test\_code\_succeeds\_if\_apache\_runs() { fake ps &lt;&lt;EOF PID TTY TIME CMD 13525 pts/7 00:00:01 bash 24162 pts/7 00:00:00 ps 8387 ? 0:00 /usr/sbin/apache2 -k start EOF assert code "code should succeed when apache is running" } test\_code\_fails\_if\_apache\_does\_not\_run() { fake ps &lt;&lt;EOF PID TTY TIME CMD 13525 pts/7 00:00:01 bash 24162 pts/7 00:00:00 ps EOF assert_fails code "code should fail when apache is not running" } \`\`\` \`\`\`output Running test\_code\_fails\_if\_apache\_does\_not\_run… SUCCESS Running test\_code\_succeeds\_if\_apache\_runs… SUCCESS \`\`\` Using a function ---------------- In a previous exemple, we faked *ps* by specifiyng code inline: \`\`\`test fake ps echo hello world ps \`\`\` \`\`\`output hello world \`\`\` If you need to write more complex code to fake your command, you may abstract this code in a function: \`\`\`test \_ps() { echo hello world } fake ps \_ps ps \`\`\` \`\`\`output hello world \`\`\` Be carefull however that your \_ps function is not exported to sub-processes. It means that, depending on how your code under test works, \_ps may not be defined in the context where ps will be called. For instance: \`\`\`test \_ps() { echo hello world } fake ps \_ps bash -c ps \`\`\` \`\`\`output bash: line 1: \_ps: command not found \`\`\` It depends on your code under test but it is safer to just export functions needed by your fake so that they are available in sub-processes: \`\`\`test \_ps() { echo hello world } export -f \_ps fake ps \_ps bash -c ps \`\`\` \`\`\`output hello world \`\`\` **fake** is also limited by the fact that it defines a *bash* function to override the actual command. In some context the command can not be overriden by a function. For instance if your code under test relies on *exec* to launch *ps*, **fake** will have no effect. **fake** parameters ------------------- **fake** stores parameters given to the fake in the global variable *FAKE\_PARAMS* so that you can use them inside your fake. It may be useful if you need to adapt the behavior on the given parameters. It can also help in asserting the values of these parameters… but this may be quite tricky. For instance, in our previous code that checks apache is running, we have an issue since our code does not use *ps* with the appropriate parameters. So we will try to check that parameters given to ps are *ax*. To do that, the first naive approch would be: \`\`\`test code() { ps a | grep apache } test\_code\_gives\_ps\_appropriate\_parameters() { \_ps() { cat &lt;&lt;EOF PID TTY TIME CMD 13525 pts/7 00:00:01 bash 24162 pts/7 00:00:00 ps 8387 ? 0:00 /usr/sbin/apache2 -k start EOF assert\_equals ax "$FAKE\_PARAMS" } export -f \_ps fake ps \_ps code >/dev/null } ``` This test calls *code*, which calls *ps*, which is actually implemented by *\_ps*. Since *code* does not use *ax* but only *a* as parameters, this test should fail. But… \`\`\`output Running test\_code\_gives\_ps\_appropriate\_parameters… SUCCESS \`\`\` The problem here is that *ps* fail (because of the failed **assert\_equals** assertion). But *ps* is piped with *grep*: \`\`\`shell code() { ps a | grep apache } \`\`\` With bash, the result code of a pipeline equals the result code of the last command of the pipeline. The last command is *grep* and since grep succeeds, the failure of *\_ps* is lost and our test succeeds. We have only succeeded in messing with the test output, nothing more. An alternative may be to activate bash *pipefail* option but this may introduce unwanted side effects. We can also simply not output anything in *\_ps* so that *grep* fails: \`\`\`test code() { ps a | grep apache } test\_code\_gives\_ps\_appropriate\_parameters() { \_ps() { assert\_equals ax "$FAKE\_PARAMS" } export -f \_ps fake ps \_ps code >/dev/null } ``` The problem here is that we use a trick to make the code under test fail but the failure has nothing to do with the actual **assert\_equals** failure. This is really bad, don’t do that. Moreover, **assert\_equals** output is captured by *ps* and this just messes with the display of our test results: \`\`\`output Running test\_code\_gives\_ps\_appropriate\_parameters… \`\`\` The only correct alternative is for the fake *ps* to write *FAKE\_PARAMS* in a file descriptor so that your test can grab them after code execution and assert their value. For instance by writing to a file: \`\`\`test code() { ps a | grep apache } test\_code\_gives\_ps\_appropriate\_parameters() { \_ps() { echo $FAKE\_PARAMS &gt; /tmp/fake\_params } export -f \_ps fake ps \_ps code || true assert_equals ax "$(head -n1 /tmp/fake_params)" } setup() { rm -f /tmp/fake\_params } \`\`\` Here our fake writes to */tmp/fake*. We delete this file in **setup** to be sure that we do not get inapropriate data from a previous test. We assert that the first line of */tmp/fake* equals *ax*. Also, note that we know that *code* will fail and write this to ignore the error: `code || true`. \`\`\`output Running test\_code\_gives\_ps\_appropriate\_parameters… FAILURE expected \[ax\] but was \[a\] doc:14:test\_code\_gives\_ps\_appropriate\_parameters() \`\`\` We can also compact the fake definition: \`\`\`test code() { ps a | grep apache } test\_code\_gives\_ps\_appropriate\_parameters() { fake ps *echo $FAKE\_PARAMS &gt;/tmp/fake\_params* code || true assert_equals ax "$(head -n1 /tmp/fake_params)" } setup() { rm -f /tmp/fake\_params } \`\`\` \`\`\`output Running test\_code\_gives\_ps\_appropriate\_parameters… FAILURE expected \[ax\] but was \[a\] doc:10:test\_code\_gives\_ps\_appropriate\_parameters() \`\`\` Finally, we can avoid the */tmp/fake\_params* temporary file by using *coproc*: \`\`\`test code() { ps a | grep apache } test\_get\_data\_from\_fake() { \#Fasten you seat belt… coproc cat fake ps *echo $FAKE\_PARAMS &gt;&$test\_channel* code || true assert_equals ax "$(head -n1 <&${COPROC[0]})" } \`\`\` \`\`\`output Running test\_get\_data\_from\_fake… FAILURE expected \[ax\] but was \[a\] doc:13:test\_get\_data\_from\_fake() \`\`\`