From 3e2349f632002b1eddb8258c69c676b9331e3ea0 Mon Sep 17 00:00:00 2001 From: Kyle Bowman Date: Sat, 29 Mar 2025 21:41:59 -0400 Subject: [PATCH 1/1] release: initial release --- .gitignore | 1 + Dockerfile | 3 +++ LICENSE | 9 ++++++++ Makefile | 39 +++++++++++++++++++++++++++++++ README.md | 51 +++++++++++++++++++++++++++++++++++++++++ lib/example.sh | 9 ++++++++ tests/test_example.bats | 22 ++++++++++++++++++ 7 files changed, 134 insertions(+) create mode 100644 .gitignore create mode 100644 Dockerfile create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 lib/example.sh create mode 100644 tests/test_example.bats diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..24e5b0a --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.build diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..315f6d2 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,3 @@ +FROM debian:bookworm-20250317-slim +RUN apt update \ + && apt install -y bats \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2d97a03 --- /dev/null +++ b/LICENSE @@ -0,0 +1,9 @@ +MIT License + +Copyright 2025 Kyle Bowman + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..7d2a5f6 --- /dev/null +++ b/Makefile @@ -0,0 +1,39 @@ +CONTAINER_CMD:=/usr/bin/podman + +IMAGE_NAME=my_bats +CONTAINER_NAME=my_bats_container +CONTAINER_MOUNT:=/workspace +CONTAINER_BATS:=/usr/bin/bats + +.PHONY: build clean help test + +help: + @echo "Mounts the current directory and runs shell-based tests in a sandboxed." + @echo + @echo "Make targest include the following:" + @echo + @echo " help (default) prints this message." + @echo " build builds the container." + @echo " clean removes container, image, and sentinel file." + @echo " test runs tests at $(PWD)/tests/*.bats" + @echo + +clean: + $(CONTAINER_CMD) rm $(CONTAINER_NAME) || echo "Skipping rm container." + $(CONTAINER_CMD) rmi $(IMAGE_NAME) || echo "Skipping rm image." + rm .build || echo "Skipping rm .build." + +# Use sentinel file: .build. +# If Dockerfile is newer than .build, rebuild it. +# Otherwise, don't rebuild it. +build: .build +.build: Dockerfile + $(CONTAINER_CMD) build -t $(IMAGE_NAME) --file=Dockerfile && touch .build + +test: .build + $(CONTAINER_CMD) rm $(CONTAINER_NAME) || echo "Skipping rm container." + $(CONTAINER_CMD) run \ + --interactive --tty \ + --name=$(CONTAINER_NAME) \ + --volume=$(PWD):$(CONTAINER_MOUNT) my_bats \ + $(CONTAINER_BATS) $(CONTAINER_MOUNT)/tests \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..331c9ae --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# Overview + +This repo is a template to help you do the following: + +1. Define a library of shell scripts. +2. Define a suite of tests for that library. +3. Define a container so you can run tests in a sandbox. + +You can run build the container and run the tests with `make test`. + +# About the Belfry Name + +I'm referring to this pattern as the Belfry pattern. + +This pattern is based on containers and BATS (Bash Automated Testing System). +The phrase "bats in the belfry" comes to mind. A belfry is a tower, which we +all understand is the ideal vessel for storing small flying mammals. +Furthermore, saying someone has "bats in the belfry" suggests they are to +"crazy" or "eccentric". That's fun too. + +# Prerequisites + +If you use a Linux-based operating system, you probably have `bash` and `make` +installed already. Aside from that, you need a way to run containers from the +command line. Docker and Podman should work fine; their interfaces are +compatible for the purposes of this project. + +Whatever you choose, make sure to run `which docker` or `which podman`. +Check the Makefile. Ensure that `CONTAINER_CMD` matches the response from the +which command. + +At this point, you can run `make test` to test the examples in the repo. + +# Usage + +Once you've installed docker, you can start testing scripts by doing the +following: + +1. Write your library in the `lib` directory. +2. Write your tests in the `tests` directory. Save them with a `.bats` extension. +3. Run `make tests`. +4. (Optional) Run `make clean` to remove the container that you built. +5. (Optional) Clean up any remaining images manually w/ `podman` or `docker`. + +# References + +* [Dockerfile Reference](https://docs.docker.com/reference/dockerfile/) +* [Docker CLI Reference](https://docs.docker.com/reference/cli/docker/) +* [BATS Documentation](https://bats-core.readthedocs.io/) +* [GNU Make Manual](https://www.gnu.org/software/make/manual/) +* [GNU Bash Manual](https://www.gnu.org/software/bash/manual/bash.html) \ No newline at end of file diff --git a/lib/example.sh b/lib/example.sh new file mode 100644 index 0000000..2106154 --- /dev/null +++ b/lib/example.sh @@ -0,0 +1,9 @@ +#!/bin/bash + +echo_hello () { + if echo "hello"; then + return 0 + else + return 1 + fi +} \ No newline at end of file diff --git a/tests/test_example.bats b/tests/test_example.bats new file mode 100644 index 0000000..3d7bcd9 --- /dev/null +++ b/tests/test_example.bats @@ -0,0 +1,22 @@ +#!/usr/bin/env bats + +setup() { + # Run before each test case + # Example: start container, prepare environment + LIB_DIR="$(dirname $(dirname "$BATS_TEST_FILENAME"))/lib" + . "$LIB_DIR"/example.sh +} + +teardown() { + # Run after each test case + # Example: stop/remove container, clean up resources + echo "Teardown running" +} + +@test "ensure echo_hello runs" { + echo_hello +} + +@test "my_test2 should fail" { + ! (exit 1) +} \ No newline at end of file -- 2.39.5