Add some sample test programs.

This change adds some sample test cases to share/examples/tests/ demonstrating the basic usage of the atf and plain interfaces. These test programs are fully-functional and are installed as part of the test suite, which guarantees that the sample code remains correct. However, they currently mostly serve as a placeholder for additional examples and may be incomplete (depending on how you look at them). I will see what else can be useful while working on documentation. As a bonus, the addition of these tests exercise the *.test.mk files, one of which (plain.test.mk) was not yet in use, and also demonstrates that it's possible to mix different kinds of test programs into the same test suite. Approved by: rpaulo (mentor)
svn path=/head/; revision=258299
2024-12-11 09:50:12 +00:00 · 2013-11-18 12:57:46 +00:00 · 2013-11-18 12:57:46 +00:00 · 21203fdd06 · 2020-12-20 02:59:44 +00:00
commit 21203fdd06
parent a2b5b37cb7
15 changed files with 735 additions and 0 deletions
--- a/etc/mtree/BSD.tests.dist
+++ b/etc/mtree/BSD.tests.dist
@ -38,6 +38,16 @@
                ..
            ..
        ..
+        share
+            examples
+                tests
+                    atf
+                    ..
+                    plain
+                    ..
+                ..
+            ..
+        ..
        usr.bin
            atf
                atf-sh
--- a/share/Makefile
+++ b/share/Makefile
@ -26,6 +26,7 @@ SUBDIR=	${_colldef} \
 	${_syscons} \
 	tabset \
 	termcap \
+	${_tests} \
 	${_timedef} \
 	${_zoneinfo}

@ -80,6 +81,10 @@ _doc=		doc
 _syscons=	syscons
 .endif

+.if ${MK_TESTS} != "no"
+_tests=		tests
+.endif
+
 .if ${MK_ZONEINFO} != "no"
 _zoneinfo=	zoneinfo
 .endif
--- a/share/examples/Makefile
+++ b/share/examples/Makefile
@ -249,4 +249,8 @@ SUBDIR+=pf
 .endif
 .endif

+.if ${MK_TESTS} != "no"
+SUBDIR+=tests
+.endif
+
 .include <bsd.subdir.mk>
--- a/share/examples/tests/Makefile
+++ b/share/examples/tests/Makefile
@ -0,0 +1,12 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+TESTSDIR=	${TESTSBASE}/share/examples
+
+SUBDIR=		tests
+
+KYUAFILE=	yes
+.PATH:		${.CURDIR:H:H:H}/tests
+
+.include <bsd.test.mk>
--- a/share/examples/tests/README
+++ b/share/examples/tests/README
@ -0,0 +1,37 @@
+$FreeBSD$
+
+This directory contains sample test programs along the Makefile and
+Kyuafile logic to get them build and installed.
+
+The goal of these test programs is to illustrate, via simple and
+heaviliy-commented code, how to construct test programs using all the
+supported interfaces in the system.
+
+If you use any files in here as templates for your own code, please
+remove all comments while doing so and then write your own if necessary.
+
+The subdirectories here contain:
+
+* tests/: Regular directory containing the tests code.  Note that the
+  apparently-redundant tests/tests/ path component here is expected for
+  consistency reasons and required to get the right layout under
+  /usr/tests/.
+
+* tests/atf/: Tests that use the ATF libraries, including atf-c, atf-c++
+  and atf-sh.  See kyua-atf-interface(1) for details.
+
+* tests/plain/: Tests that do not use any testing framework.  See
+  kyua-plain-interface(1) for details.
+
+To inspect the available sample test cases from an installed system:
+
+    $ kyua list -k /usr/tests/share/examples/tests/Kyuafile
+
+To run the full suite of sample test cases:
+
+    $ kyua test -k /usr/tests/share/examples/tests/Kyuafile
+
+And to debug a specific failing test case, if any:
+
+    $ kyua debug -k /usr/tests/share/examples/tests/Kyuafile \
+      atf/cp_test:simple
--- a/share/examples/tests/tests/Makefile
+++ b/share/examples/tests/tests/Makefile
@ -0,0 +1,27 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+# Directory into which the Kyuafile provided by this directory will be
+# installed.
+#
+# This is always a subdirectory of ${TESTSBASE}/.  The remainder of the
+# path has to match the relative path within the source tree in which
+# these files are found modulo the tests/ component at the end.
+#
+# For example: if this Makefile were in src/bin/cp/tests/, its TESTSDIR
+# would point at ${TESTSBASE}/bin/cp/.
+TESTSDIR=	${TESTSBASE}/share/examples/tests
+
+# List of subdirectories into which we want to recurse during the build
+# of the system.  We use TESTS_SUBDIRS instead of SUBDIR because we want
+# the auto-generated Kyuafile to recurse into these directories.
+TESTS_SUBDIRS=	atf plain
+
+# We leave KYUAFILE unset so that bsd.test.mk auto-generates a Kyuafile
+# for us based on the contents of the TESTS_SUBDIRS line above.  The
+# generated file will tell the tests run-time engine to recurse into the
+# directories listed above.
+#KYUAFILE=	auto
+
+.include <bsd.test.mk>
--- a/share/examples/tests/tests/atf/Kyuafile
+++ b/share/examples/tests/tests/atf/Kyuafile
@ -0,0 +1,46 @@
+-- $FreeBSD$
+--
+-- Copyright 2013 Google Inc.
+-- All rights reserved.
+--
+-- Redistribution and use in source and binary forms, with or without
+-- modification, are permitted provided that the following conditions are
+-- met:
+--
+-- * Redistributions of source code must retain the above copyright
+--   notice, this list of conditions and the following disclaimer.
+-- * Redistributions in binary form must reproduce the above copyright
+--   notice, this list of conditions and the following disclaimer in the
+--   documentation and/or other materials provided with the distribution.
+-- * Neither the name of Google Inc. nor the names of its contributors
+--   may be used to endorse or promote products derived from this software
+--   without specific prior written permission.
+--
+-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+-- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+-- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+-- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+-- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+-- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+-- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+-- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+-- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+-- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax(2)
+
+-- All tests provided by the FreeBSD base system should set the test_suite
+-- property to FreeBSD.  This creates a namespace in the configuration file
+-- in which specific run-time properties can be passed to the tests below.
+test_suite('FreeBSD')
+
+-- Register the various test programs into the test suite defined in this
+-- directory.
+--
+-- Note that, while Kyua supports overriding the test case metadata
+-- properties (e.g. their timeout) along the test program definition, you
+-- should not do so for ATF test programs.  The ATF test cases themselves
+-- encode the right values.
+atf_test_program{name='cp_test'}
+atf_test_program{name='printf_test'}
--- a/share/examples/tests/tests/atf/Makefile
+++ b/share/examples/tests/tests/atf/Makefile
@ -0,0 +1,30 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+# Directory into which the Kyuafile provided by this directory will be
+# installed.
+#
+# This is always a subdirectory of ${TESTSBASE}/.  The remainder of the
+# path has to match the relative path within the source tree in which
+# these files are found modulo the tests/ component at the end.
+#
+# For example: if this Makefile were in src/bin/cp/tests/, its TESTSDIR
+# would point at ${TESTSBASE}/bin/cp/.
+TESTSDIR=	${TESTSBASE}/share/examples/tests/atf
+
+# List of test programs to build.  Note that we can build more than one
+# test from a single directory, and this is expected.
+ATF_TESTS_C=	printf_test
+ATF_TESTS_SH=	cp_test
+
+# Tell bsd.test.mk that we are providing a hand-crafted Kyuafile in this
+# directory.  We do so because the file in this directory exists for
+# documentation purposes.
+#
+# In general, however, you should NOT define KYUAFILE at all to allow
+# bsd.test.mk auto-generate one for you based on the ATF_TESTS_*
+# definitions from above.
+KYUAFILE=	yes
+
+.include <atf.test.mk>
--- a/share/examples/tests/tests/atf/cp_test.sh
+++ b/share/examples/tests/tests/atf/cp_test.sh
@ -0,0 +1,119 @@
+# $FreeBSD$
+#
+# Copyright 2013 Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+# INTRODUCTION
+#
+# This sample test program implements various test cases for the cp(1)
+# utility in order to demonstrate the usage of the ATF shell API (see
+# atf-sh-api(3)).
+#
+
+#
+# Auxiliary function to compare two files for equality.
+#
+verify_copy() {
+	if ! cmp -s "${1}" "${2}"; then
+		echo "${1} and ${2} differ, but they should be equal"
+		diff -u "${1}" "${2}"
+		atf_fail "Original and copy do not match"
+	fi
+}
+
+#
+# This is the simplest form of a test case definition: a test case
+# without a header.
+#
+# In most cases, this is the definition you will want to use.  However,
+# make absolutely sure that the test case name is descriptive enough.
+# Multi-word test case names are encouraged.  Keep in mind that these
+# are exposed to the reader in the test reports, and the goal is for
+# the combination of the test program plus the name of the test case to
+# give a pretty clear idea of what specific condition the test is
+# validating.
+#
+atf_test_case simple
+simple_body() {
+	echo 'File 1' >file1
+
+	# The atf_check function is a very powerful function of atf-sh.
+	# It allows you to define checkers for the exit status, the
+	# stdout and the stderr of any command you execute.  If the
+	# result of the command does not match the expectations defined
+	# in the checkers, the test fails and verbosely reports data
+	# behind the problem.
+	#
+	# See atf-check(1) for details.
+	atf_check -s exit:0 -o empty -e empty cp file1 file2
+
+	verify_copy file1 file2
+
+	# Of special note here is that we are NOT deleting the temporary
+	# files we created in this test.  Kyua takes care of this
+	# cleanup automatically and tests can (and should) rely on this
+	# behavior.
+}
+
+#
+# This is a more complex form of a test case definition: a test case
+# with a header and a body.  You should always favor the simpler
+# definition above unless you have to override specific metadata
+# variables.
+#
+# See atf-test-case(4) and kyua-atf-interface(1) for details on all
+# available properties.
+#
+atf_test_case force
+force_head() {
+	# In this specific case, we define a textual description for
+	# the test case, which is later exported to the reports for
+	# documentation purposes.
+	#
+	# However, note again that you should favor highly descriptive
+	# test case names to textual descriptions.
+	atf_set "descr" "Tests that the -f flag causes cp to forcibly" \
+	    "override the destination file"
+}
+force_body() {
+	echo 'File 1' >file1
+	echo 'File 2' >file2
+	chmod 400 file2
+	atf_check cp -f file1 file2
+	verify_copy file1 file2
+}
+
+#
+# Lastly, we tell ATF which test cases exist in this program.  This
+# function should not do anything other than this registration.
+#
+atf_init_test_cases() {
+	atf_add_test_case simple
+	atf_add_test_case force
+}
--- a/share/examples/tests/tests/atf/printf_test.c
+++ b/share/examples/tests/tests/atf/printf_test.c
@ -0,0 +1,155 @@
+/* $FreeBSD$
+ *
+ * Copyright 2013 Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * * Neither the name of Google Inc. nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
+
+/*
+ * INTRODUCTION
+ *
+ * This sample test program implements various test cases for the printf(3)
+ * family of functions in order to demonstrate the usage of the ATF C API
+ * (see atf-c-api(3)).
+ *
+ * Note that this test program is called printf_test because it is intended
+ * to validate various functions of the printf(3) family.  For this reason,
+ * each test is prefixed with the name of the function under test followed
+ * by a description of the specific condition being validated.  You should
+ * use a similar naming scheme for your own tests.
+ */
+
+#include <atf-c.h>
+#include <stdio.h>
+#include <string.h>
+
+/*
+ * This is the simplest form of a test case definition: a test case
+ * without a header.
+ *
+ * In most cases, this is the definition you will want to use.  However,
+ * make absolutely sure that the test case name is descriptive enough.
+ * Multi-word test case names are encouraged.  Keep in mind that these
+ * are exposed to the reader in the test reports, and the goal is for
+ * the combination of the test program plus the name of the test case to
+ * give a pretty clear idea of what specific condition the test is
+ * validating.
+ */
+ATF_TC_WITHOUT_HEAD(snprintf__two_formatters);
+ATF_TC_BODY(snprintf__two_formatters, tc)
+{
+	char buffer[128];
+
+	/* This first require-style check invokes the function we are
+	 * interested in testing.  This will cause the test to fail if
+	 * the condition provided to ATF_REQUIRE is not met. */
+	ATF_REQUIRE(snprintf(buffer, sizeof(buffer), "%s, %s!",
+	    "Hello", "tests") > 0);
+
+	/* This second check-style check compares that the result of the
+	 * snprintf call we performed above is correct.  We use a check
+	 * instead of a require. */
+	ATF_CHECK_STREQ("Hello, tests!", buffer);
+}
+
+/*
+ * This is a more complex form of a test case definition: a test case
+ * with a header and a body.  You should always favor the simpler
+ * definition above unless you have to override specific metadata
+ * variables.
+ *
+ * See atf-test-case(4) and kyua-atf-interface(1) for details on all
+ * available properties.
+ */
+ATF_TC(snprintf__overflow);
+ATF_TC_HEAD(snprintf__overflow, tc)
+{
+	/* In this specific case, we define a textual description for
+	 * the test case, which is later exported to the reports for
+	 * documentation purposes.
+	 *
+	 * However, note again that you should favor highly descriptive
+	 * test case names to textual descriptions.  */
+	atf_tc_set_md_var(tc, "descr", "This test case validates the proper "
+	    "truncation of the output string from snprintf when it does not "
+	    "fit the provided buffer.");
+}
+ATF_TC_BODY(snprintf__overflow, tc)
+{
+	char buffer[10];
+
+	/* This is a similar test to the above, but in this case we do the
+	 * test ourselves and forego the ATF_* macros.  Note that we use the
+	 * atf_tc_fail() function instead of exit(2) or similar because we
+	 * want Kyua to have access to the failure message.
+	 *
+	 * In general, prefer using the ATF_* macros wherever possible.  Only
+	 * resort to manual tests when the macros are unsuitable (and consider
+	 * filing a feature request to get a new macro if you think your case
+	 * is generic enough). */
+	if (snprintf(buffer, sizeof(buffer), "0123456789abcdef") != 16)
+		atf_tc_fail("snprintf did not return the expected number "
+		    "of characters");
+
+	ATF_CHECK(strcmp(buffer, "012345678") == 0);
+}
+
+/*
+ * Another simple test case, but this time with side-effects.  This
+ * particular test case modifies the contents of the current directory
+ * and does not clean up after itself, which is perfectly fine.
+ */
+ATF_TC_WITHOUT_HEAD(fprintf__simple_string);
+ATF_TC_BODY(fprintf__simple_string, tc)
+{
+	const char *contents = "This is a message\n";
+
+	FILE *output = fopen("test.txt", "w");
+	ATF_REQUIRE(fprintf(output, "%s", contents) > 0);
+	fclose(output);
+
+	/* The ATF C library provides more than just macros to verify the
+	 * outcome of expressions.  It also includes various helper functions
+	 * to work with files and processes.  Here is just a simple
+	 * example. */
+	ATF_REQUIRE(atf_utils_compare_file("test.txt", contents));
+
+	/* Of special note here is that we are NOT deleting the
+	 * temporary files we created in this test.  Kyua takes care of
+	 * this cleanup automatically and tests can (and should) rely on
+	 * this behavior. */
+}
+
+/*
+ * Lastly, we tell ATF which test cases exist in this program.  This
+ * function should not do anything other than this registration.
+ */
+ATF_TP_ADD_TCS(tp)
+{
+	ATF_TP_ADD_TC(tp, snprintf__two_formatters);
+	ATF_TP_ADD_TC(tp, snprintf__overflow);
+	ATF_TP_ADD_TC(tp, fprintf__simple_string);
+}
--- a/share/examples/tests/tests/plain/Kyuafile
+++ b/share/examples/tests/tests/plain/Kyuafile
@ -0,0 +1,47 @@
+-- $FreeBSD$
+--
+-- Copyright 2013 Google Inc.
+-- All rights reserved.
+--
+-- Redistribution and use in source and binary forms, with or without
+-- modification, are permitted provided that the following conditions are
+-- met:
+--
+-- * Redistributions of source code must retain the above copyright
+--   notice, this list of conditions and the following disclaimer.
+-- * Redistributions in binary form must reproduce the above copyright
+--   notice, this list of conditions and the following disclaimer in the
+--   documentation and/or other materials provided with the distribution.
+-- * Neither the name of Google Inc. nor the names of its contributors
+--   may be used to endorse or promote products derived from this software
+--   without specific prior written permission.
+--
+-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+-- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+-- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+-- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+-- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+-- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+-- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+-- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+-- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+-- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax(2)
+
+-- All tests provided by the FreeBSD base system should set the test_suite
+-- property to FreeBSD.  This creates a namespace in the configuration file
+-- in which specific run-time properties can be passed to the tests below.
+test_suite('FreeBSD')
+
+-- Register the various test programs into the test suite defined in this
+-- directory.
+--
+-- Because plain test programs cannot define metadata in their code (they
+-- have no mechanism to communicate that to Kyua), we can instead define
+-- any metadata properties in here.  These have the exact same meaning as
+-- their ATF counterparts.  These properties are often useful to define
+-- prerequisites for the execution of the tests.
+plain_test_program{name='cp_test', required_programs='/bin/cp'}
+plain_test_program{name='printf_test'}
--- a/share/examples/tests/tests/plain/Makefile
+++ b/share/examples/tests/tests/plain/Makefile
@ -0,0 +1,30 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+# Directory into which the Kyuafile provided by this directory will be
+# installed.
+#
+# This is always a subdirectory of ${TESTSBASE}/.  The remainder of the
+# path has to match the relative path within the source tree in which
+# these files are found modulo the tests/ component at the end.
+#
+# For example: if this Makefile were in src/bin/cp/tests/, its TESTSDIR
+# would point at ${TESTSBASE}/bin/cp/.
+TESTSDIR=	${TESTSBASE}/share/examples/tests/plain
+
+# List of test programs to build.  Note that we can build more than one
+# test from a single directory, and this is expected.
+PLAIN_TESTS_C=	printf_test
+PLAIN_TESTS_SH=	cp_test
+
+# Tell bsd.test.mk that we are providing a hand-crafted Kyuafile in this
+# directory.  We do so because the file in this directory exists for
+# documentation purposes.
+#
+# In general, however, you should NOT define KYUAFILE at all to allow
+# bsd.test.mk auto-generate one for you based on the PLAIN_TESTS_*
+# definitions from above.
+KYUAFILE=	yes
+
+.include <plain.test.mk>
--- a/share/examples/tests/tests/plain/cp_test
+++ b/share/examples/tests/tests/plain/cp_test
@ -0,0 +1,84 @@
+# $FreeBSD$
+#
+# Copyright 2013 Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+# INTRODUCTION
+#
+# This plain test program mimics the structure and contents of its
+# ATF-based counterpart.  It attempts to represent various test cases
+# in different separate functions and just calls them all from main.
+#
+# In reality, plain test programs can be much simpler.  All they have
+# to do is return 0 on success and non-0 otherwise.
+#
+
+set -e
+
+# Prints an error message and exits.
+err() {
+	echo "${@}" 1>&2
+	exit 1
+}
+
+# Auxiliary function to compare two files for equality.
+verify_copy() {
+	if ! cmp -s "${1}" "${2}"; then
+		diff -u "${1}" "${2}"
+		err "${1} and ${2} differ, but they should be equal"
+	fi
+}
+
+simple_test() {
+	echo 'File 1' >file1
+	cp file1 file2 || err "cp failed"
+	verify_copy file1 file2
+}
+
+force_test() {
+	echo 'File 1' >file1
+	echo 'File 2' >file2
+	chmod 400 file2
+	cp -f file1 file2 || err "cp failed"
+	verify_copy file1 file2
+}
+
+# If you have read the cp_test.sh counterpart in the atf/ directory, you
+# may think that the sequencing of tests below and the exposed behavior
+# to the user is very similar.  But you'd be wrong.
+#
+# There are two major differences with this and the ATF version.  The
+# first is that the code below has no provisions to detect failures in
+# one test and continue running the other tests: the first failure
+# causes the whole test program to exit.  The second is that this
+# particular "main" has no arguments: without ATF, all test programs may
+# expose a different command-line interface, and this is an issue for
+# consistency purposes.
+simple_test
+force_test
--- a/share/examples/tests/tests/plain/printf_test.c
+++ b/share/examples/tests/tests/plain/printf_test.c
@ -0,0 +1,119 @@
+/* $FreeBSD$
+ *
+ * Copyright 2013 Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * * Neither the name of Google Inc. nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
+
+/*
+ * INTRODUCTION
+ *
+ * This plain test program mimics the structure and contents of its
+ * ATF-based counterpart.  It attempts to represent various test cases
+ * in different separate functions and just calls them all from main().
+ *
+ * In reality, plain test programs can be much simpler.  All they have
+ * to do is return 0 on success and non-0 otherwise.
+ */
+
+#include <err.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static void
+snprintf__two_formatters(void)
+{
+	char buffer[128];
+
+	if (snprintf(buffer, sizeof(buffer), "%s, %s!", "Hello",
+	    "tests") <= 0)
+		errx(EXIT_FAILURE, "snprintf with two formatters failed");
+
+	if (strcmp(buffer, "Hello, tests!") != 0)
+		errx(EXIT_FAILURE, "Bad formatting: got %s", buffer);
+}
+
+static void
+snprintf__overflow(void)
+{
+	char buffer[10];
+
+	if (snprintf(buffer, sizeof(buffer), "0123456789abcdef") != 16)
+		errx(EXIT_FAILURE, "snprintf did not return the expected "
+		    "number of characters");
+
+	if (strcmp(buffer, "012345678") != 0)
+		errx(EXIT_FAILURE, "Bad formatting: got %s", buffer);
+}
+
+static void
+fprintf__simple_string(void)
+{
+	FILE *file;
+	char buffer[128];
+	size_t length;
+	const char *contents = "This is a message\n";
+
+	file = fopen("test.txt", "w+");
+	if (fprintf(file, "%s", contents) <= 0)
+		err(EXIT_FAILURE, "fprintf failed to write to file");
+	rewind(file);
+	length = fread(buffer, 1, sizeof(buffer) - 1, file);
+	if (length != strlen(contents))
+		err(EXIT_FAILURE, "fread failed");
+	buffer[length] = '\0';
+	fclose(file);
+
+	if (strcmp(buffer, contents) != 0)
+		errx(EXIT_FAILURE, "Written and read data differ");
+
+	/* Of special note here is that we are NOT deleting the temporary
+	 * files we created in this test.  Kyua takes care of this cleanup
+	 * automatically and tests can (and should) rely on this behavior. */
+}
+
+int
+main(void)
+{
+	/* If you have read the printf_test.c counterpart in the atf/
+	 * directory, you may think that the sequencing of tests below and
+	 * the exposed behavior to the user is very similar.  But you'd be
+	 * wrong.
+	 *
+	 * There are two major differences with this and the ATF version.
+	 * The first is that the code below has no provisions to detect
+	 * failures in one test and continue running the other tests: the
+	 * first failure causes the whole test program to exit.  The second
+	 * is that this particular main() has no arguments: without ATF,
+	 * all test programs may expose a different command-line interface,
+	 * and this is an issue for consistency purposes. */
+	snprintf__two_formatters();
+	snprintf__overflow();
+	fprintf__simple_string();
+
+	return EXIT_SUCCESS;
+}
--- a/share/tests/Makefile
+++ b/share/tests/Makefile
@ -0,0 +1,10 @@
+# $FreeBSD$
+
+.include <bsd.own.mk>
+
+TESTSDIR=	${TESTSBASE}/share
+
+.PATH:		${.CURDIR:H:H}/tests
+KYUAFILE=	yes
+
+.include <bsd.test.mk>