From 8e5a86f8b8f8b044cb28232df2012dba73470fcd Mon Sep 17 00:00:00 2001
From: Jason Bedard <jason@aspect.dev>
Date: Mon, 26 Feb 2024 15:05:14 -0800
Subject: [PATCH] docs: add bats docs

---
 README.md    |  4 ++++
 docs/bats.md | 22 +++++++++++++++++++++-
 lib/bats.bzl | 22 +++++++++++++++++++++-
 3 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0ceef29..a16c892 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,10 @@ For example to use commit `abc123`:
 - [stamping](docs/stamping.md) Support version stamping in custom rules.
 - [base64](docs/base64.md) Starlark Base64 encoder & decoder.
 
+## Testing
+
+- [bats_test]:(docs/bats.md) A test runner for the [Bash Automated Testing System](https://github.com/bats-core/bats-core).
+
 ## Generating documentation
 
 - [docs](docs/docs.md) Rules for generating docs and stamping tests to ensure they are up to date.
diff --git a/docs/bats.md b/docs/bats.md
index 6de99e0..01e0c6f 100644
--- a/docs/bats.md
+++ b/docs/bats.md
@@ -1,6 +1,26 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-Bats test runner
+A test rule that invokes the [Bash Automated Testing System](https://github.com/bats-core/bats-core).
+
+For example, a `bats_test` target containing a single .bat and basic configuration:
+
+```starlark
+bats_test(
+    name = "my_test",
+    size = "small",
+    srcs = [
+        "my_test.bats",
+    ],
+    data = [
+        "data.bin",
+    ],
+    env = {
+        "DATA_PATH": "$(location :data.bin)",
+    },
+    args = ["--timing"],
+)
+```
+
 
 <a id="bats_test"></a>
 
diff --git a/lib/bats.bzl b/lib/bats.bzl
index fbc018b..23c2974 100644
--- a/lib/bats.bzl
+++ b/lib/bats.bzl
@@ -1,4 +1,24 @@
-"Bats test runner"
+"""A test rule that invokes the [Bash Automated Testing System](https://github.com/bats-core/bats-core).
+
+For example, a `bats_test` target containing a single .bat and basic configuration:
+
+```starlark
+bats_test(
+    name = "my_test",
+    size = "small",
+    srcs = [
+        "my_test.bats",
+    ],
+    data = [
+        "data.bin",
+    ],
+    env = {
+        "DATA_PATH": "$(location :data.bin)",
+    },
+    args = ["--timing"],
+)
+```
+"""
 
 load("//lib/private:bats.bzl", _bats_test = "bats_test")