This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-releases-client.git
The following commit(s) were added to refs/heads/main by this push:
new 316a36f Document the transcription test format
316a36f is described below
commit 316a36fdb864851535f7647124399cbe015f92ff
Author: Sean B. Palmer <[email protected]>
AuthorDate: Wed Jul 16 15:49:08 2025 +0100
Document the transcription test format
---
docs/transcription-test-format.md | 114 ++++++++++++++++++++++++++++++++++++++
pyproject.toml | 4 +-
tests/cli_workflow.t | 4 +-
uv.lock | 4 +-
4 files changed, 120 insertions(+), 6 deletions(-)
diff --git a/docs/transcription-test-format.md
b/docs/transcription-test-format.md
new file mode 100644
index 0000000..41a3f04
--- /dev/null
+++ b/docs/transcription-test-format.md
@@ -0,0 +1,114 @@
+# ATR transcript format
+
+We use a transcript format to test the CLI of the ATR client. This is a guide
to that format.
+
+Each `.t` transcript file is a stateful session with a console. Commands are
prefixed by `"$ "`, `"! "`, or `"* "`, depending on whether they are expected
to succeed, fail, or either.
+
+```
+$ echo this should succeed
+this should succeed
+
+! grep -i "this should fail" /does/not/exist
+<.etc.>
+
+* cat /etc/motd
+<.etc.>
+```
+
+Compare also an [example of a longer
file](https://raw.githubusercontent.com/apache/tooling-releases-client/refs/heads/main/tests/cli_workflow.t).
+
+The command must be followed by the expected output of the command. As you can
see even from the short example above, certain helpful syntax is permitted to
help fully characterise inputs and outputs.
+
+## Syntax
+
+### `<.etc.>`
+
+Any further output is ignored. For example, if you `cat` a large file but only
want to match the first two lines:
+
+```
+$ cat large-file.txt
+first line
+second line
+<.etc.>
+```
+
+### `<.exit.>`
+
+All tests stop. This is useful for debugging when you don't want to test the
rest of the file for some reason, e.g. because you know it's broken. You can
also use this to add a long comment to the bottom of a file.
+
+```
+$ echo trivial test
+trivial test
+
+<.exit.>
+
+$ obviously broken test
+???
+```
+
+### `<.skip.>`
+
+You can use `<.etc.>` to skip the entire rest of the input, but `<.skip.>`
allows you to skip to the next interesting thing within a line, or to consume
the rest of the line. It's a non-greedy regular expression match. In practice,
it's often useful for searching within lines.
+
+```
+$ echo we only want to match the middle of this line
+<.skip.>match the middle<.skip.>
+```
+
+### `<.stderr.>`
+
+The ATR transcript format captures all of stdout first, then all of stderr. To
indicate that you are now capturing stderr, use `<.stderr.>` by itself on a
line.
+
+```
+$ dc -e "1 0 /" | less
+<.stderr.>
+
+Math error: divide by 0
+ 0: (main)
+```
+
+If a command is expected to have both stdout and stderr output, stdout must be
characterised first, and stderr separately afterwards. We do not support
interleaving.
+
+### `<# comment #>`
+
+To add a comment anywhere, use the `<# comment #>` syntax. We recommend using
lower case and no trailing punctuation for comments.
+
+```
+<# test that df -h returns 0 #>
+$ df -h /
+<.etc.>
+```
+
+### `<?capture?>`
+
+Sometimes it is necessary to capture part of an output to use later on. We
only support capturing a whole line.
+
+```
+$ dc -e "2 3 + p"
+<?sum?>
+```
+
+The output of this `dc` command is now stored in the `sum` variable.
+
+
+### `<!use!>`
+
+The `<!use!>` syntax allows you to use a stored variable. Stored variables can
be used in inputs and outputs.
+
+```
+$ dc -e "2 3 + p"
+<?five?>
+
+$ test <!five!> -eq 5
+
+$ dc -e "7 2 - p"
+<!five!>
+```
+
+## Origin
+
+This was inspired by the (different, more fully featured) [transcript test
format](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript) in the
Golang standard library, which was [originally developed by Russ
Cox](https://x.com/_myitcv/status/1522687481447129088). Cox was, in turn,
_presumably_ inspired by [Cram](https://bitheap.org/cram/), which is an
independent implementation of the earlier [unified test format developed for
Mercurial](https://wiki.mercurial-scm.org/WritingTe [...]
+
+## TODO
+
+Does this format need a name? What would we call it? Perhaps _Transcript Ace_,
after [reverse
transcriptase](https://en.wikipedia.org/wiki/Reverse_transcriptase)? But it's
more of a technique than a format. You can easily port this to another
language, and adapt it.
diff --git a/pyproject.toml b/pyproject.toml
index c43a246..8aa01cb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -11,7 +11,7 @@ build-backend = "hatchling.build"
[project]
name = "apache-trusted-releases"
-version = "0.20250716.1349"
+version = "0.20250716.1448"
description = "ATR CLI and Python API"
readme = "README.md"
requires-python = ">=3.13"
@@ -72,4 +72,4 @@ select = [
]
[tool.uv]
-exclude-newer = "2025-07-16T13:49:00Z"
+exclude-newer = "2025-07-16T14:48:00Z"
diff --git a/tests/cli_workflow.t b/tests/cli_workflow.t
index b244736..25d60d7 100644
--- a/tests/cli_workflow.t
+++ b/tests/cli_workflow.t
@@ -13,7 +13,7 @@ $ atr dev pat
$ atr set tokens.pat <!pat!>
Set tokens.pat to "<!pat!>".
-<# Delete any existing draft, ignoring errors. #>
+<# delete any existing draft, ignoring errors #>
* atr dev delete tooling-test-example 0.3+cli
<.etc.>
@@ -54,6 +54,6 @@ Vote marked as passed
$ atr announce tooling-test-example 0.3+cli 00003 -m "<!user!>@apache.org" -s
"[ANNOUNCE] Release tooling-test-example 0.3+cli" -b "Release
tooling-test-example 0.3+cli has been announced."
Announcement sent
-<# Tidy up. #>
+<# tidy up #>
* atr dev delete tooling-test-example 0.3+cli
<.etc.>
diff --git a/uv.lock b/uv.lock
index fdf144a..e05994a 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2,7 +2,7 @@ version = 1
requires-python = ">=3.13"
[options]
-exclude-newer = "2025-07-16T13:49:00Z"
+exclude-newer = "2025-07-16T14:48:00Z"
[[package]]
name = "aiohappyeyeballs"
@@ -83,7 +83,7 @@ wheels = [
[[package]]
name = "apache-trusted-releases"
-version = "0.20250716.1349"
+version = "0.20250716.1448"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
