bats-core/bats-file

Common filesystem assertions for Bats

Bats-core: Bash Automated Testing System

Bats is a TAP-compliant testing framework for Bash 3.2 or above. It provides a simple way to verify that the UNIX programs you write behave as expected.

A Bats test file is a Bash script with special syntax for defining test cases. Under the hood, each test case is just a function with a description.

#!/usr/bin/env bats

@test "addition using bc" {
  result="$(echo 2+2 | bc)"
  [ "$result" -eq 4 ]
}

@test "addition using dc" {
  result="$(echo 2 2+p | dc)"
  [ "$result" -eq 4 ]
}

Bats is most useful when testing software written in Bash, but you can use it to test any UNIX program.

Test cases consist of standard shell commands. Bats makes use of Bash's errexit (set -e) option when running test cases. If every command in the test case exits with a 0 status code (success), the test passes. In this way, each line is an assertion of truth.

Table of contents

NOTE The documentation has moved to https://bats-core.readthedocs.io

• Testing
• Support
• Contributing
• Contact
• Version history
• Background
  • What's the plan and why?
  • Why was this fork created?
• Copyright

Testing

bin/bats --tap test

See also the CI settings for the current test environment and scripts.

Support

The Bats source code repository is hosted on GitHub. There you can file bugs on the issue tracker or submit tested pull requests for review.

For real-world examples from open-source projects using Bats, see Projects Using Bats on the wiki.

To learn how to set up your editor for Bats syntax highlighting, see Syntax Highlighting on the wiki.

Contributing

For now see the docs folder for project guides, work with us on the wiki or look at the other communication channels.

Contact

• You can find and chat with us on our Gitter.

Version history

See docs/CHANGELOG.md.

Background

Why was this fork created?

There was an initial call for maintainers for the original Bats repository, but write access to it could not be obtained. With development activity stalled, this fork allowed ongoing maintenance and forward progress for Bats.

Tuesday, September 19, 2017: This was forked from Bats at commit 0360811. It was created via git clone --bare and git push --mirror.

As of Thursday, April 29, 2021: the original Bats has been archived by the owner and is now read-only.

This bats-core repo is now the community-maintained Bats project.

Copyright

The Bats Logo was created by Vukory (Github) and sponsored by SethFalco. If you want to use our logo, have a look at our guidelines.

© 2017-2024 bats-core organization

© 2011-2016 Sam Stephenson

Bats is released under an MIT-style license; see LICENSE.md for details.

See the parent project at GitHub or the AUTHORS file for the current project maintainer team.

bats-file's Issues

maintain changelog

Recent changes haven't been added to the changelog.

Add assert_file_contains, assert_file_size_equals, assert_file_empty, assert_file_not_empty

As described here
https://github.com/ztombol/bats-file/pull/2/commits

assert_file_owner, assert_no_file_owner /dir/owner

As this is my first issue, thank you for forking the repo and adding original content to it. It looks like the original hasn't been touched in years by @ztombol.

I cloned the master and ran the tests, which were all successful. But my test fails:

@test "ownership" {
    touch hello.txt
    assert_file_owner myUser hello.txt
}

Firstly, it asks me for a password (which shouldn't happen during a test), then it emits:
chown: /dir/owner: No such file or directory. I investigated and found the following lines:
https://github.com/peshay/bats-file/blob/4b75a1adbc892d61de059c67ab0c73964f132598/src/file.bash#L287-L288

and
https://github.com/peshay/bats-file/blob/4b75a1adbc892d61de059c67ab0c73964f132598/src/file.bash#L297-L298

It seems that you should not need these as part of the the function. Perhaps they are leftover artifacts from refactoring a test suite? Anyway, I commented them out, and the assert_file_owner function worked as intended.

Interestingly, I looked into the tests, and found that your tests had all passed, because it used the TEST_FIXTURE_ROOT path explicitly to set up the testing files. The function you are testing should only be dependent on the arguments passed to it, and the TEST_FIXTURE_ROOT path should only be used in the test suite.

https://github.com/peshay/bats-file/blob/4b75a1adbc892d61de059c67ab0c73964f132598/test/59-assert-10-assert_file_owner.bats#L6-L23

This all applies also to assert_not_file_owner.

Sorry for the long-winded comment. I'm looking forward to using some more of the functions you've added.

add code coverage

If possible maybe
https://github.com/codecov/example-bash

Failure to run `temp_make` in the `setup_file` block.

I require some common setup for all test cases in a file, but am not able to run make_temp inside the setup_file block.

setup_file() {
    TEMP_REPO_NOTAG="$(temp_make)"
}

 ✗
   (from function `setup_file' in test file test/bump_semver.bats, line 9)
     `TEMP_REPO_NOTAG="$(temp_make)"' failed

   -- ERROR: temp_make --
   Must be called from `setup', `@test' or `teardown'
   --

   bats warning: Executed 1 instead of expected 8 tests

8 tests, 1 failure, 7 not run

Would you consider allowing this?

add tests for new file assert functions

assert function where added to test

• symbolic link
• character special file
• block special file
• socket
• named pipe
  They all need CI tests

sudo required by assert_file_owner?

When I run checks with assert_file_owner it seems to complain about sudo.

If I uncomment the assert_file_owner lines, this passes.

@test "verify we can setup the log location" {
  INT_REPOSITORY_DIR="/tmp"
  LOG_DIR="$INT_REPOSITORY_DIR/logs/"
  rm -rf "$LOG_DIR"
  run log_setup
  assert_dir_exist "$LOG_DIR"
  assert_file_owner tcsuser "$LOG_DIR"  # This seems to be the problem line
}

If I leave either of the second to last line, I get an error like this.

 ✗ verify we can setup the bluray log location
   (in test file test/TCSstart_BLURAY_install.sh.bats, line 144)
     `assert_dir_exist "$LOG_DIR"' failed with status 127
   /opt/bats/lib/bats-file/src/file.bash: line 297: sudo: command not found

Including bats-support as a submodule causes submodule update to fail on projects which use bats-file as a submodule

I am using bats-file for a project, and bats-file is included as a submodule in the repository. Attempting to execute git submodule update --init results in a error.

git submodule update --init --recursive
fatal: No url found for submodule path 'bats/bats-file/bats-support' in .gitmodules
fatal: Failed to recurse into submodule path 'bats/bats-file'

I have managed to work around the issue by rolling back to commit cc3fb8c, but I was wondering if this breaking change is intentional?

Make bats-file safe to use under -u

bats-mock fails if optional arguments to getter or setter functions are omitted and the expansion of unset variables / parameters is not allowed (that is, when set -u is used).

Some people are using set -euo pipefail in scripts to enforce a clean coding style. Sourcing such a script for testing may break tests using bats-mock.

How to reproduce:

#!/usr/bin/env bats

load bats-modules/bats-support/load
load bats-modules/bats-file/load

@test "asserting for a non-existent directory behaves as expected when expansion of unset arguments is allowed" {
        set +u

        run assert_dir_exist '/no/such/directory'

        [[ ${status} -eq 1 ]]
        [[ ${output} =~ '-- directory does not exist --' ]]
}

@test "asserting for a non-existent directory fails with unbound variable error when expansion of unset arguments is not allowed" {
        set -u

        run assert_dir_exist '/no/such/directory'

        [[ ${status} -eq 1 ]]
        [[ ! ${output} =~ '-- directory does not exist --' ]]
        [[ ${output} =~ '/file.bash: line '[0-9]*': BATSLIB_FILE_PATH_REM: unbound variable' ]]
}

add more tests for shells and OSes

Like they do in shunit2
https://github.com/kward/shunit2/blob/master/.travis.yml

failed assert_file_exist reports as not executed when teardown() with load

OS: MacOS 11.6.1
Bash: 5.1.12(1) (from MacPorts)
Bats: da56a30 (2022-01-05)
Bats-File: 17fa557 (2020-04-29)

This one took me hours to come up with a reproducible example; I didn't also have the fortitude to dig into the code and figure out the cause or a fix, too -- sorry!

If my program calls assert_file_exist and fails, instead of reporting a failure it will report the test as not being executed, but only when there's a teardown function with a load call in it. Here's a test case; commentary follows:

setup() {
    load 'test_helper/bats-support/load'
    load 'test_helper/bats-assert/load'
    load 'test_helper/bats-file/load'
}

teardown() {
    load 'foofoo'
}


@test "[1] this one executes successfully" {

    foo=/tmp/foo
    touch $foo

    assert_file_exist "$foo"
}

@test "[2] this one will execute and fail" {
    foo=/tmp/foo
    touch $foo

    [[ -e "x$foo" ]]
}

@test "[3] this one will report as not executed" {
    foo=/tmp/foo
    touch $foo

    assert_file_exist "x$foo"
}

@test "[4] this one works fine no matter what" {
    foo=/tmp/foo
    touch $foo

    assert_file_not_exist "x$foo"
}

@test "[5] this one will also execute and fail" {
    foo=/tmp/foo
    touch $foo

    run /bin/false
    assert_success
}

The foofoo.bash file is zero bytes; it just needs to exist.

When run, this produces the following output:

$ test/bats/bin/bats test/99*
 ✓ [1] this one executes successfully
 ✗ [2] this one will execute and fail
   (in test file test/99-bats-issue.bats, line 24)
     `[[ -e "x$foo" ]]' failed
 ✓ [4] this one works fine no matter what
 ✗ [5] this one will also execute and fail
   (from function `assert_success' in file test/test_helper/bats-assert/src/assert_success.bash, line 42,
    in test file test/99-bats-issue.bats, line 46)
     `assert_success' failed

   -- command failed --
   status : 1
   output :
   --

   bats warning: Executed 4 instead of expected 5 tests

5 tests, 2 failures, 1 not run

Notice that one of the tests is shown as not being run, and test #​3 does in fact not show up in the output. If you watch the output closely, though, you'll see it is reported, it's just overwritten -- if you move test #​3 to be the last test, its line won't get overwritten and you'll see it in the output:

$ test/bats/bin/bats test/99*
 ✓ [1] this one executes successfully
 ✗ [2] this one will execute and fail
   (in test file test/99-bats-issue.bats, line 24)
     `[[ -e "x$foo" ]]' failed
 ✓ [4] this one works fine no matter what
 ✗ [5] this one will also execute and fail
   (from function `assert_success' in file test/test_helper/bats-assert/src/assert_success.bash, line 42,
    in test file test/99-bats-issue.bats, line 39)
     `assert_success' failed

   -- command failed --
   status : 1
   output :
   --

   [3] this one will report as not executed                                                                                                       5/5
   bats warning: Executed 4 instead of expected 5 tests

5 tests, 2 failures, 1 not run

If you remove the teardown function (by either deleting it or renaming it), test #​3 will properly show as executing and failing:

$ test/bats/bin/bats test/99*
 ✓ [1] this one executes successfully
 ✗ [2] this one will execute and fail
   (in test file test/99-bats-issue.bats, line 24)
     `[[ -e "x$foo" ]]' failed
 ✗ [3] this one will report as not executed
   (from function `assert_file_exist' in file test/test_helper/bats-file/src/file.bash, line 72,
    in test file test/99-bats-issue.bats, line 31)
     `assert_file_exist "x$foo"' failed

   -- file does not exist --
   path : x/tmp/foo
   --

 ✓ [4] this one works fine no matter what
 ✗ [5] this one will also execute and fail
   (from function `assert_success' in file test/test_helper/bats-assert/src/assert_success.bash, line 42,
    in test file test/99-bats-issue.bats, line 46)
     `assert_success' failed

   -- command failed --
   status : 1
   output :
   --


5 tests, 3 failures

The same results can be achieved by removing the load line, e.g.

teardown() {
    : load 'foofoo'
}

I replicated this aberrant behavior with one or two other assert_* commands from bats-file, but I did not test each one.

shellcheck

While I was looking into CI outputs, there was printed lines for the version of the shellcheck. However, while I was looking into .bash files I noticed some anti-patterns such as commands running with backticks etc. So, it is not utilised.

Also, When I run shellcheck against .bash files, I see quite few errors. I think it could be a good practice to run shellcheck both on CI tests and as a pre-commit hook.

Creating this issue for starting a discussion but I can definitely take the task for myself and go ahead.

Renew README

With alle the new functions coming in, the README should be improved so the functions are summarized under specific topics for a better table of contents.
Maybe in code all assert and their corresponding assert_not functions should stay together.

Add installation instructions

Not sure how bats extensions are supposed to be installed in bats eco-system.

bats-core has multiple mechanisms documented:

• https://github.com/bats-core/bats-core#installation

but nothing in their readme how to install other adds-ons:

• https://github.com/bats-core/bats-core#libraries-and-add-ons

so, as both projects have package.json:

• https://github.com/bats-core/bats-core/blob/v1.2.0/package.json
• https://github.com/bats-core/bats-file/blob/v0.3.0/package.json

perhaps this community is npm based, but then the bats-file is not present on npm:

[/tmp] ➔ yarn add bats-file
yarn add v1.22.4
info No lockfile found.
[1/4] 🔍  Resolving packages...
error An unexpected error occurred: "https://registry.yarnpkg.com/bats-file: Not found".
info If you think this is a bug, please open a bug report with the information provided in "/private/tmp/yarn-error.log".
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.

add assert_file_executable

Have a new test function to test if a file is executable or not

bats-file version display 0.2.0 instead of 0.4.0

Hi,

I guess it's a minor issue, but the shields.io is wrong and point to a 0.2.0 while the curent version is 0.4.0.

I assume it's due to the fact that the package.json file is still on version:0.2.0.

see bellow:

  "name": "bats-file",
  "version": "0.2.0",

Best

Jetmartin

Most recent release (0.3.0) much behind 'master' / Any new release planned?

Hello,

I was aware of BATS for a while and recently discovered bats-file. So I started to eagerly integrate it into my tests. That's when I realised that the status of master and the last release v0.3.0 (installed via Homebrew) are significantly apart in time (3 years) and features. It is easy enough to install the bleeding edge via git submodule into my project, so nothing technically stops me from using the latest goodness, but I still wanted to ask if there are any plans to continue putting out actual releases?

I assume that some thought and effort goes into declaring a certain state of the project as a release, compared to just using the latest state in master and given that this is a testing tool, I would not mind to be conservative, going from official release to official release, just that in this particular case the delta is so big. Unless the general view is that master is sufficiently stable and that everyone happily uses just that?

Thanks for the great work on bats-*, it is a really welcome support for scripting.

assert_symlink_to

As described here
ztombol@95896f3

assert_not_file_owner contains (debug?) sudo calls

Using assert_not_file_owner fails when run in non-interactive sessions (and, in practice, most of the time) because it contains calls to sudo. (Issues #37/#38 dealt with a similar problem in assert_file_owner.)

At first glance these calls are unrelated to the assertion itself and are probably leftovers from a debugging sessions.

assert_not_file_owner() {
  local -r owner="$1"
  local -r file="$2"
  if [[ `uname` == "Darwin" ]]; then
  sudo chown root ${TEST_FIXTURE_ROOT}/dir/owner
  sudo chown daemon ${TEST_FIXTURE_ROOT}/dir/notowner
  if [ `stat -f '%Su' "$file"` = "$owner" ]; then
    local -r rem="${BATSLIB_FILE_PATH_REM-}"
    local -r add="${BATSLIB_FILE_PATH_ADD-}"
    batslib_print_kv_single 4 'path' "${file/$rem/$add}" \
      | batslib_decorate "given user is the $owner, but it was expected not to be" \
      | fail
  fi
  elif [[ `uname` == "Linux" ]]; then
  sudo chown root ${TEST_FIXTURE_ROOT}/dir/owner
  sudo chown daemon ${TEST_FIXTURE_ROOT}/dir/notowner
    if [ `stat -c "%U" "$file"` = "$owner" ]; then
    local -r rem="${BATSLIB_FILE_PATH_REM-}"
    local -r add="${BATSLIB_FILE_PATH_ADD-}"
    batslib_print_kv_single 4 'path' "${file/$rem/$add}" \
      | batslib_decorate "given user is the $owner, but it was expected not to be" \
      | fail
  fi
fi
}

add assert_equal_files

compare if two files are the same with cmp --silent

assert_size_not_zero breaks due to hardcoded use of test paths TEST_FIXTURE_ROOT

relates to #27

produces

fallocate: cannot open /dir/notzerobyte: No such file or directory

https://github.com/bats-core/bats-file/blob/master/src/file.bash#L919

assert_file_not_contains is not implemented

In the assert_file_contains function header, it mentions the logical compliment assert_file_not_contains. However this complement does not actually exist.

bats-file npm package removed by security team

According to https://www.npmjs.com/package/bats-file:

Security holding package
This package contained malicious code and was removed from the registry by the npm security team. A placeholder was published to ensure users are not affected in the future.

Please refer to www.npmjs.com/advisories?search=bats-file for more information.

Clicking the link goes to github advisories, but nothing is listed there for bats-file.

Do you have any context on this?

add more file based tests

• assert_file_owner to test if a user is owner of a file
• assert_file_permission to test permissions set on a file
• assert_not_zero if a file is greater 0 byte
• assert_file_set_group_id if set-group-ID is set
• assert_file_set_user_id if set-user-ID is set
• assert_sticky_bit if sticky bit is set on file