Date: Fri, 30 Dec 2022 21:22:50 -0600 Subject: begin documentation and add lily_begin() and lily_finish() --- doc/01-introduction.html | 24 +++++++++ doc/02-writing-tests.html | 119 +++++++++++++++++++++++++++++++++++++++++++++ doc/03-assertions.html | 89 +++++++++++++++++++++++++++++++++ doc/style.css | 48 ++++++++++++++++++ doc/table-of-contents.html | 17 +++++++ doc/template.html | 22 +++++++++ 6 files changed, 319 insertions(+) create mode 100644 doc/01-introduction.html create mode 100644 doc/02-writing-tests.html create mode 100644 doc/03-assertions.html create mode 100644 doc/style.css create mode 100644 doc/table-of-contents.html create mode 100644 doc/template.html (limited to 'doc') diff --git a/doc/01-introduction.html b/doc/01-introduction.html new file mode 100644 index 0000000..156994b --- /dev/null +++ b/doc/01-introduction.html @@ -0,0 +1,24 @@ + + + + + + + Introduction | lily-test + + +

+ +

Introduction

+ +

lily-test is a single-header midsize unit testing framework written in C89. + +

+ + + diff --git a/doc/02-writing-tests.html b/doc/02-writing-tests.html new file mode 100644 index 0000000..152ccac --- /dev/null +++ b/doc/02-writing-tests.html @@ -0,0 +1,119 @@ + + + + + + + Writing Tests | lily-test + + +

+ +

Writing Tests

+ +

A basic unit test file looks like this:

+ +


+#include "lily-test.h"
+
+LILY_FILE_BEGIN(example_file)
+
+
+LILY_TEST("example test 1")
+{
+	CHECK_EQ(1+1, 2, "%d");
+}
+#include LILY_PUSH_TEST()
+
+
+LILY_TEST("example test 2")
+{
+	CHECK_LT(3.0, 4.0, "%0.2f");
+}
+#include LILY_PUSH_TEST()
+
+
+#define LILY_FILE_END
+#include LILY_REGISTER_TESTS()
+

+ +

This will define a function pointer example_file with signature void () that, when called, will execute the two tests and display to stderr any errors that they generate. While there is more boilerplate than in comparable C++ libraries, this means that lily-test supports test auto-registration. To add a new test, just use the LILY_TEST macro as shown, and then follow the function body with #include LILY_PUSH_TEST() to register it. These macros will only work correctly when used between a LILY_FILE_BEGIN and LILY_FILE_END block, and only when used together; using LILY_TEST without a LILY_PUSH_TEST is probably going to throw up a ton of compile errors.

+ +

Using a single file

+ +

For very small projects, you may be able to get away with using only a single unit test file. In this case, you should set it up along the following lines:

+ +


+#define LILY_IMPLEMENTATION
+#include "lily-test.h"
+
+/* any includes or code to get your tests working */
+
+LILY_FILE_BEGIN(tests)
+
+/* test definitions... */
+
+#define LILY_FILE_END
+#include LILY_REGISTER_TESTS()
+
+int main()
+{
+	lily_begin();
+	tests();
+	lily_finish();
+	return 0;
+}
+

+ + However, in most cases you will want to have multiple test files. + + +

Multiple test files

+ +

You will need, in addition to your unit test files, a header file that contains extern declarations of the function pointers defined by your files and a main C source file that contains a main function to run all of the function pointers. A nice way to set this up is to use X-macros, like this:

+ +


+/* tests.h */
+
+#define TESTS \
+	X(suite_1) \
+	X(suite_2) \
+	X(suite_3) \
+
+
+#define X(suite) extern void (*suite)();
+TESTS
+#undef X
+

+ +


+/* tests_main.c */
+
+#define LILY_IMPLEMENTATION
+#include "lily-test.h"
+
+int main()
+{
+	lily_begin();
+	#define X(suite) suite();
+	TESTS
+	#undef X
+	lily_finish();
+	return 0;
+}
+

+ +

This is convenient, because it means that when you add a new test file you need only add a single line to the definition of the TESTS macro in tests.h and all of the other relevant code is added for you automatically.

+ +

Note that exactly ONE file should define LILY_IMPLEMENTATION. I find it reasonable to make this the same file with the implementation of main but YMMV.

+ +

+ + + diff --git a/doc/03-assertions.html b/doc/03-assertions.html new file mode 100644 index 0000000..92126a8 --- /dev/null +++ b/doc/03-assertions.html @@ -0,0 +1,89 @@ + + + + + + + Assertions | lily-test + + +

+ +

+ + +

Assertions

+ +

There are two different basic types of assertions: checks and requirements. Both checks and requires will mark the overall test as failed if they are false, but a require will also immediately stop executing the test in addition.

+ +

Check Macros

+ +

CHECK(x)

+ +

Marks the test as failed if x is false and prints stringified x.

+ +

CHECK_EQ(x, y, fmt)

+ +

Marks the test as failed if x == y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

CHECK_NEQ(x, y, fmt)

+ +

Marks the test as failed if x != y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

CHECK_LT(x, y, fmt)

+ +

Marks the test as failed if x < y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

CHECK_LE(x, y, fmt)

+ +

Marks the test as failed if x <= y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

CHECK_GT(x, y, fmt)

+ +

Marks the test as failed if x > y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

CHECK_GE(x, y, fmt)

+ +

Marks the test as failed if x >= y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +
+ +

Require Macros

+ +

REQUIRE(x)

+ +

Marks the test as failed and immediately ends test execution if x is false and prints stringified x.

+ +

REQUIRE_EQ(x, y, fmt)

+ +

Marks the test as failed and immediately ends test execution if x == y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

REQUIRE_NEQ(x, y, fmt)

+ +

Marks the test as failed and immediately ends test execution if x != y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

REQUIRE_LT(x, y, fmt)

+ +

Marks the test as failed and immediately ends test execution if x < y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

REQUIRE_LE(x, y, fmt)

+ +

Marks the test as failed and immediately ends test execution if x <= y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

REQUIRE_GT(x, y, fmt)

+ +

Marks the test as failed and immediately ends test execution if x > y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + +

REQUIRE_GE(x, y, fmt)

+ +

Marks the test as failed and immediately ends test execution if x >= y is false. Prints both the stringified names of x and y as well as their values, using the printf format code provided in fmt. + + +

+ + + diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..d6ff59a --- /dev/null +++ b/doc/style.css @@ -0,0 +1,48 @@ +body { + color: #f6f5f4; + background: #181a1b; +} + +#flex-root { + display: flex; + flex-direction: row; + flex-wrap: wrap; + width: 100%; +} + +a { + color: #f57c85; +} + +a:visited { + color: #fa6571; +} + +#toc { + border-style: none solid none none; + border-width: 1px; + border-color: #f57c85; + flex: 1 15 0; + max-width: 15em; + min-height: 15em; +} + +#content { + margin: 0 1em; + flex: 1 1 0; +} + +#footer { + border-style: solid none none none; + border-width: 1px; + border-color: #f57c85; + padding: 1em; +} + +#footer #prev { + float: left; +} + +#footer #next { + float: right; +} diff --git a/doc/table-of-contents.html b/doc/table-of-contents.html new file mode 100644 index 0000000..c450da8 --- /dev/null +++ b/doc/table-of-contents.html @@ -0,0 +1,17 @@ + + + + + + + Table of Contents + + +

+ + diff --git a/doc/template.html b/doc/template.html new file mode 100644 index 0000000..6d4337b --- /dev/null +++ b/doc/template.html @@ -0,0 +1,22 @@ + + + + + + + TEMPLATE + + +

+ +

+ + +

+ + + -- cgit v1.2.1