API.adoc

Testing API

file(filename, [content, …​]) [< content]

tig_script(name, content, [content, …​])

steps(content, [content, …​])

keystrokes([-append | -keysym | -repeat=<int>] key-sequence, [key-sequence, …​])

Key sequences are given as Python strings, and accept the same string escapes as Python. Example: '\134' encodes a literal backslash.
+ The key sequence may also contain special embedded codes: %(keysym:<name>), %(keypause:<seconds>), or %(keysignal:<signal>).
+ %(keysym:<name>) will be translated into the raw characters associated with the symbolic key name. <name> may be any form accepted by 'bind' in ~/.tigrc, or any terminal capability name known to tput. Examples: %(keysym:Left), %(keysym:Ctrl-A).
+ As a convenience, the -keysym option causes subsequent arguments to be interpreted as a series of keysym names. Example:

	keystrokes -keysym 'Down' 'Up'

::
*`%(keypause:<seconds>)`* will insert a pause in the simulated
keystrokes. If pauses are added, the test timeout may also need to be
increased. +
+
*`%(keysignal:<signal>)`* will send a Unix signal to tig.  The signal
may be given as a number or symbol. Example: `%(keysignal:SIGWINCH)` +
+
To send tig a literal sequence matching the characters of an embedded
code, escape it with a backslash: `\%(keypause:1)`. +
+
Exiting: The passed key sequence should always arrange a clean exit.
Tig will otherwise be shut down by a signal, which is less consistent
for the purpose of testing. +
+
Appending: keystrokes may be defined in multiple passes using `-append`.
This enables composing keystrokes with and without `-keysym`.  The last
call to `keystrokes()` should arrange a clean exit from tig. +
+
Repeating: `-repeat=<int>` can be used to define repeated sequences.
Only one key-sequence argument may be used with `-repeat`.  Example:

	keystrokes -keysym -repeat=20 'Down'

::
Interaction with `steps()`: It is possible to use both `steps()` and
`keystrokes()` in the same test: during test execution, the `steps()`
script will run first, and the simulated keystrokes will be sent to tig
after the script finishes. When used together, `steps()` is modified so
that it does not imply `:quit`. +
+
Whitespace handling: The "Enter" key will be fed to tig as a carriage
return (`\r`). Interior newlines in key sequences, whether literal or
encoded, will be translated to carriage returns before sending them to
tig. But note that leading or trailing whitespace on the key-sequence
argument is ignored. To send "Enter", "Tab", or "Space" as the first or
last key in the sequence, use escape codes or keysyms (_ie_ `\r`,`\t`,
`\040`, `%(keysym:Enter)`, `%(keysym:Tab)`, or `%(keysym:Space)`.) +

stdin([content, …​]) [< content]

tigrc([content, …​]) [< content]

gitconfig(content, …​)

in_work_dir(command, [args, …​])

assert_equals(filename, [whitespace, note, …​]) < expected

assert_not_exists(filename)

assert_vars(count)

test_todo([note, …​])

test_timeout(seconds)

require_git_version(version, [note, …​])

test_require(git-worktree, address-sanitizer, diff-highlight, readline)

test_setup()

test_tig()

Set up a controlled environment and report the test result. Input to be processed via stdin is passed and stderr is captured and can be used for later assertions. Example

test_tig show 1a2b3c4d5e6f

test_graph() < expected

test_case([--before=<string>, --after=<string>, --script=<string>, --args=<string>, --cwd=<string>, --tigrc=<string>, --assert-stderr=<string>, --todo=<string>, --subshell=<string>, --timeout=<string>]) < expected

run_test_cases()