aboutsummaryrefslogtreecommitdiff
path: root/doc/testscript.cli
diff options
context:
space:
mode:
Diffstat (limited to 'doc/testscript.cli')
-rw-r--r--doc/testscript.cli100
1 files changed, 51 insertions, 49 deletions
diff --git a/doc/testscript.cli b/doc/testscript.cli
index 4fe6d72..5e72e92 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -15,7 +15,7 @@
\h0#preface|Preface|
This document describes the \c{build2} Testscript language. It starts with a
-discussion of the motivations behind a separate domain-specific language for
+discussion of the motivation behind a separate domain-specific language for
running tests and then introduces a number of Testscript concepts with
examples. The remainder of the document provides a more formal specification
of the language, including its integration into the build system, conceptual
@@ -25,7 +25,7 @@ used in the \c{build2} project itself.
In this document we use the term \i{Testscript} (capitalized) to refer to the
Testscript language. Just \i{testscript} means code written in this language.
-For example: \"We can pass addition information to testscripts using
+For example: \"We can pass additional information to testscripts using
target-specific variables.\" Finally, \c{testscript} refers to the file name.
We also use the equivalent distinction between \i{Buildfile} (language),
@@ -53,7 +53,7 @@ approach is not portable (there is no Bash or Python on Windows \i{out of the
box}). It is also hard to write concise tests in a general-purpose scripting
language. The result is often a test suite that has grown incomprehensible
with everyone dreading adding new tests. Secondly, it is hard to run such
-tests in parallel without a major effort. Usually this involves having a
+tests in parallel without major effort. Usually this involves having a
separate script for each test and implementing some kind of a test harness.
Testscript is a domain-specific language for running tests. It vaguely
@@ -109,14 +109,14 @@ exe{hello}: cxx{hello} test{testscript}
Let's assume our \c{hello} program expects us to pass the name to greet as a
command line argument. And if we don't pass anything, it prints an error
-following by usage and terminates with a non-zero exit code. We can test
+followed by usage and terminates with a non-zero exit code. We can test
this failure case by adding the following line to the \c{testscript} file:
\
$* 2>- != 0
\
-While it sure is concise, it may look cryptic without explanation. When the
+While it sure is concise, it may look cryptic without an explanation. When the
\c{test} module runs tests, it passes to each testscript the path to the
target of which this testscript is a prerequisite. So in our case the
testscript will receive the path to our \c{hello} executable. The buildfile
@@ -217,9 +217,9 @@ unlike Bash where here-documents always have variable expansions).
This example illustrated a fairly common testing problem: output variability.
In our case we could fix it perfectly since we could easily calculate the
-varying part exactly. But often figuring out the varying part is difficult of
-outright impossible. A good example would be a system error message based on
-the \c{errno} code, such as file not being found. Different C runtimes can
+varying part exactly. But often figuring out the varying part is difficult if
+not outright impossible. A good example would be a system error message based
+on the \c{errno} code, such as file not being found. Different C runtimes can
phrase the message slightly differently or it can be localized. Worse, it can
be a slightly different error code, for example \c{ENOENT} vs \c{ENOTDIR}.
@@ -371,7 +371,7 @@ that removes \c{hello.conf}? It is not necessary because this file will be
automatically registered for cleanup that happens at the end of the test. We
can also register our own files and directories for automatic cleanup. For
example, if the \c{hello} program created the \c{hello.log} file on
-unsuccessful runs, then here is how we could have cleaned it up:
+unsuccessful runs, then this is how we could have cleaned it up:
\
$* ... &hello.log != 0
@@ -419,7 +419,7 @@ The last thing we need to discuss in this example is \c{$~}. This variable
stands for the scope working directory (we will talk more about working
directories at the end of this introduction).
-Besides explicit group scopes each test is automatically placed in its own
+Besides explicit group scopes, each test is automatically placed in its own
implicit test scope. However, we can make the test scope explicit, for
example, for better visual separation of complex tests:
@@ -477,7 +477,7 @@ because the testscript variable lookup continues in the buildfile starting
from the target being tested, then the testscript target, and continuing with
the standard scope lookup (see \l{#model Model and Execution} for details). In
particular, this means we can pass arbitrary information to testscripts using
-target-specific variables. For example, this how we can move the above
+target-specific variables. For example, this is how we can move the above
platform test to \c{buildfile}:
\
@@ -497,8 +497,8 @@ else
...
\
-Note also that in cases you simply need to conditionally pick a value for a
-variable, the \c{build2} evaluation context will often be a more concise
+Note also that in cases where you simply need to conditionally pick a value
+for a variable, the \c{build2} evaluation context will often be a more concise
option. For example:
\
@@ -592,7 +592,7 @@ $out_base/
└── missing-name/
\
-If all the tests succeed then this working directory structure is
+If all the tests succeed, then this working directory structure is
automatically removed. In case of a failure, however, it is left behind in
case you need to examine the output of the failed tests. It will be
automatically cleaned on the subsequent run, before executing any tests.
@@ -752,7 +752,7 @@ using cxx # Load the C++ module (sets sets cxx.target).
test.target = $cxx.target # Set test target to the C++ compiler target.
\
-If this variable is not set explicitly, then it default to \c{build.host}
+If this variable is not set explicitly, then it defaults to \c{build.host}
(which is the platform on which the build system is running) and only native
testing will be supported.
@@ -788,7 +788,7 @@ A scope (both group and test) has an \i{id}. If not specified explicitly (as
part of the description), it is derived automatically from the group/test
location in the testscript file (see \l{#syntax-description Description} for
details). The id of the implicit outermost scope is the script file name
-without the \c{.test} extension. Except if the file name is \c{testscript},
+without the \c{.test} extension, except if the file name is \c{testscript},
in which case the id is empty.
Based on the ids each nested group and test has an \i{id path} that uniquely
@@ -942,12 +942,13 @@ Alternatively, we can use an absolute path:
Inside the scope working directory filesystem names that start with \c{stdin},
\c{stdout}, \c{stderr}, as well as, \c{cmd-} are reserved.
-To executing a test scope its commands (including variable assignments) are
-executed sequentially and in order specified. If any of the commands fails,
-no further commands are executed and the test is considered to have failed.
+To execute a test scope its commands (including variable assignments) are
+executed sequentially and in the order specified. If any of the commands
+fails, no further commands are executed and the test is considered to have
+failed.
Executing a group scope starts with performing its setup commands (including
-variable assignments) sequentially and in order specified. If any of them
+variable assignments) sequentially and in the order specified. If any of them
fail, the group execution is terminated and the group is considered to have
failed.
@@ -956,8 +957,8 @@ executed. Because scopes are isolated and tests are assumed not to depend on
each other, the execution of inner scopes can be performed in parallel.
After completing the execution of the inner scopes, if all of them succeeded,
-the teardown commands are executed sequentially and in order specified. Again,
-if any of them fail, the group execution is terminated and the group is
+the teardown commands are executed sequentially and in the order specified.
+Again, if any of them fail, the group execution is terminated and the group is
considered to have failed.
As an example, consider the following version of \c{basics.test}:
@@ -980,14 +981,14 @@ test0
\
At the top level, both \c{test0} and \c{group} can start executing in
-parallel. Inside \c{group}, first the two setup command are executed
+parallel. Inside \c{group}, first the two setup commands are executed
sequentially. Once the setup is completed, \c{test1}, \c{test2}, \c{test3}
can all be executed in parallel (along with \c{test0} which may still be
running). Once the three inner tests complete successfully, the \c{group}'s
-teardown command are executed sequentially. At the top level, the script
+teardown commands are executed sequentially. At the top level, the script
is completed only when both \c{test0} and \c{group} complete.
-The following annotated version illustrated a possible thread scheduling
+The following annotated version illustrates a possible thread scheduling
for this example:
\
@@ -1138,12 +1139,12 @@ foo = '$foo\bar'
\
Inside double-quoted strings only the \c{\"\\$(} character set needs to be
-escaped. Inside double-quoted here-document fragments \- only \c{\\$(} (in
-here-documents quotes are taken literally).
+escaped. Inside double-quoted here-document fragments \- only \c{\\$(} (since
+in here-documents quotes are taken literally).
The lexical structure of a line depends on its type. The line type could be
dictated by the preceding construct, as is the case for here-document
-fragments. Otherwise the line type is determined by examining the leading
+fragments. Otherwise, the line type is determined by examining the leading
character and, if that fails to determine the line type, leading tokens,
as described next.
@@ -1223,7 +1224,7 @@ contexts):
quotes as literals. The \c{$(} characters are recognized as tokens.||
Besides having a varying lexical structure, parsing some line types involves
-performing expansions (variable expansions, function calls, and evaluations
+performing expansions (variable expansions, function calls, and evaluation
contexts). The following table summarizes the mapping of line types to lexing
modes and indicates whether they are parsed with expansions:
@@ -1316,10 +1317,10 @@ bar - line continuation
# foo - comment
\
-Rule right-hand-sides that start on a new line describe the line-level syntax
-and ones that start on the same line describes the syntax inside the line. If
-a rule contains multiple lines, then each line matches a separate line in the
-input.
+A rule's right-hand-sides that start on a new line describe the line-level
+syntax and ones that start on the same line describes the syntax inside the
+line. If a rule contains multiple lines, then each line matches a separate
+line in the input.
If a multiplier appears in front of a line then it specifies the number of
repetitions of the entire line. For example, from the following three rules,
@@ -1740,13 +1741,13 @@ A command pipe can combine several commands with a pipe (\c{stdout} of the
left-hand-side command is connected to \c{stdin} of the right-hand-side). The
logical result of a command pipe is the logical AND of all its commands.
-A command begins with a command path following by options/arguments,
-redirects, and cleanups, all optional and in any order.
+A command begins with a command path followed by options/arguments, redirects,
+and cleanups, all optional and in any order.
-A command may specify an exist code check. If executing a command results in
+A command may specify an exit code check. If executing a command results in
an abnormal process termination, then the whole outer construct (e.g., test,
setup/teardown, etc) summarily fails. Otherwise (that is, in case of a normal
-termination) the exit code is checked. If omitted, then the test is expected
+termination), the exit code is checked. If omitted, then the test is expected
to succeed (0 exit code). The logical result of executing a command is
therefore a boolean value which is used in the higher-level constructs (pipe
and expression).
@@ -1929,7 +1930,7 @@ sequences, not even line continuations \- each line is taken literally.
If the end marker on the command line is double-quoted, then the here-document
lines are parsed as if they were double-quoted except that the double quote
-itself is not treated as special. In this mode we can use variables
+itself is not treated as special. In this mode we can use variable
expansions, function calls, and evaluation contexts. However, we have to
escape the \c{$(\\} character set.
@@ -2008,7 +2009,7 @@ $* >>~/EOO/
EOO
\
-The following match flag are recognized:
+The following match flags are recognized:
\dl|
@@ -2066,7 +2067,7 @@ the following more traditional form:
\
Only characters from the \c{.()|*+?{\}\\0123456789,=!} set are allowed as
-syntax line-chars with presence of any other character being an error.
+syntax line-chars with the presence of any other characters being an error.
A blank line as well as the \c{//} sequence (assuming \c{/} is the introducer)
are treated as an empty line-char. For the purpose of matching, newlines are
@@ -2083,9 +2084,9 @@ line-regex.
cleanup: ('&'|'&?'|'&!') (<file>|<dir>)
\
-If a command creates extra files or directories, then they can be register for
-automatic cleanup at the end of the scope (test or group). Files mentioned in
-redirects are registered automatically. Additionally, certain builtins (for
+If a command creates extra files or directories, then they can be registered
+for automatic cleanup at the end of the scope (test or group). Files mentioned
+in redirects are registered automatically. Additionally, certain builtins (for
example \c{touch} and \c{mkdir}) also register their output files/directories
automatically (as described in each builtin's documentation).
@@ -2141,7 +2142,7 @@ components being optional.
If the first line in the description does not contain any whitespaces, then it
is assumed to be the test or test group id. If the next line is followed by a
-blank line, then it is assume to be the test or test group summary. After the
+blank line, then it is assumed to be the test or test group summary. After the
blank line come optional details which are free-form.
The trailing description can only be used to specify the id or summary (but
@@ -2150,7 +2151,7 @@ not both).
If an id is not specified then it is automatically derived from the test or
test group location. If the test or test group is contained directly in the
top-level testscript file, then just its start line number is used as an id.
-Otherwise, if the test or test group reside in an included file, then the
+Otherwise, if the test or test group resides in an included file, then the
start line number (inside the included file) is prefixed with the line number
of the \c{include} directive followed by the included file name (without the
extension) in the form \c{<line>-<file>-}. This process is repeated
@@ -2300,15 +2301,16 @@ is ECMAScript (more specifically, ECMA-262-based C++11 regular expressions).
\li|\n\c{-n}
- Suppress automatic printing of the pattern space at the end of the script.|
+ Suppress automatic printing of the pattern space at the end of the script
+ execution.|
\li|\n\c{-e <script>}\n
Editing commands to be executed (required).||
To perform the transformation \c{sed} reads each line of input (without the
-newline) into the pattern space. It then executes the script commands on
-the pattern space. At the end of the script, unless the \c{-n} option is
+newline) into the pattern space. It then executes the script commands on the
+pattern space. At the end of the script execution, unless the \c{-n} option is
specified, \c{sed} writes the pattern space to \c{stdout} followed by a
newline.
@@ -2431,7 +2433,7 @@ each \i{happy} (non-error) \i{logic branch}. For important code you may also
want to do so for \i{unhappy logic branches}.
It is also a good idea to keep testing in mind as you implement things. When
-tempted to add a small special case just to make the result is a little bit
+tempted to add a small special case just to make the result a little bit
\i{nicer}, remember that you will also have to test this special case.
If the functionality is well exposed in the program, prefer functional to unit