Package: groktest
test-type: doctestGroktestGroktest is a test framework that's inspired by Python's long standingdoctestlibrary.Similarities todoctest:A test suite is a plain text file containing more or more testsA test is anexpressionaccompanied by anexpected resultA test is run by evaluating the expression in the applicable
language environment to generate acomputed resultA test passes when itscomputed resultmatches isexpected resultand fails otherwiseDifferences todoctest:Test expressions may be defined in any supported language (currently
Python, bash planned, support for other languages over time)Expected results may contain format-expressions, which are used to
match expected output to a pattern with optional value capture to
runtime state variables (see examples below)Tests are not sensitive to white-space by defaultTest options do not require adoctest:prefixFront-matter in test files may be used to configure a test suiteWhy?Python'sdoctestpaved the way for computational documents like
Jupyter Notebooks, R Markdown, and Quarto. It was one of the first of
its kind. We owe a debt of grattutude to Tim Peters for the original
work and to Jim Fulton for advancing its use.The rationale fordoctestis that examples provide a high-signal,
low-noise representation of developer intent.Tests are framed within comments (rather than using comments), which
encourages a narrative mode of testingExamples are often easier to understand (grok) than a series of
assertionsExample output can replace a large number of explicit assertions,
providing more test coverage with fewer expresionsdoctesthowever presents some key problems.Result comparison can use an ellipsis...to match any output; while
the match is geedy, it can match invalid output and mast errorsThe framework is Python specific and difficult to apply to cases
outside PythonPattern matching is limited to a single 'match all' patternOutput from tests cannot be captured for use in subsequent testsGroktest addresses these issues while maintaining the originaldoctestvalue proposition.Not supported in GroktestGroktest is in its early development phases. Its immediate goal is to be
a near drop-in replacement fordoctestfor tests defined in standalone
plain text files.Groktest is not designed to test Python doc strings. Usedoctestfor
that.While Groktest is designed to be language independent, it will take some
time to get this right. In order of priority, Groktest will support:Tests defined using Python expressions (under development)Tests defined as shell commands with bash/sh as the first target (planned)Other runtimes as the project evolves (e.g R, Node, Julia, Erlang,
etc.)ExamplesThe simplest example is an exact match.>>> 'The number 42 is overused in examples'
'The number 42 is overused in examples'Ingroktestyou can provide aformat expression, which has the
format{[name][:format]}. The following example asserts that the claim
contains a series of digits.>>> 'The number 42 is overused in examples'  # doctest: +SKIP
'The number {:d} is overused in examples'Matched values can be bound to local variables.>>> 'The number 42 is overused in examples'  # doctest: +SKIP
'The number {n} is overused in examples'

>>> n == 42  # doctest: +SKIP
TrueOutput parsing is provided by Richard Jones' outstandingparselibrary.To match anything, use{}.>>> 'Another tedious example is the use of "ham" and "spam"'
... # doctest: +SKIP
'Another tedious example is {}'Multiline expressions are continued on subsequent lines using....>>> (1 +
... 2 + 4)
7Front matter is used to configure tests.---
test-config:
  ps1: '> '
  ps2: '+ '
---

> "This should be familiar
+ to R developers"Aside: In this case the use of>conflicts with Markdown's syntax for
block quotes. We recommend indenting tests with four spaces in Markdown
files.Custom format types may be defined in test font matter.---
test-config:
  match-types:
    id: [a-f0-9]{8}
---

>>> 'Sample id is abcd1234'  # doctest: +SKIP
Sample id is {:id}What works?A this point Groktest is in early development and nothing much of use is
available.Refer to Groktest tests to see what works. Run them to verify!$ groktest *.md docs/*.mdContributingPlease feel free to reach out if you'd like to contribute to this
project. While we don't have a contribution policy we will get there! In
the meantime, use the following guidelines:Use theproject issue
trackerto ask questions,
report bugs, and suggest features.Contributions will be accepted via pull requests.All tests intests.mdshould pass.All source code is formatted usingblack- expect any contribution
to be reformatted on this basis.Before working on a contribution, we recommend opening an issue to
get early feedback.We expect contributors to follow generally accepted standards of
respect and kindness to others.