From b285939b89165052f609b6e2a81867492df03ad7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 30 Sep 2020 15:12:06 +0200 Subject: tests/unit/README: convert to markdown ... and add to dist! --- tests/unit/Makefile.am | 4 +-- tests/unit/README | 74 -------------------------------------------------- tests/unit/README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 68 insertions(+), 76 deletions(-) delete mode 100644 tests/unit/README create mode 100644 tests/unit/README.md diff --git a/tests/unit/Makefile.am b/tests/unit/Makefile.am index 4bcd47d22..63e11b14f 100644 --- a/tests/unit/Makefile.am +++ b/tests/unit/Makefile.am @@ -5,7 +5,7 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2019, Daniel Stenberg, , et al. +# Copyright (C) 1998 - 2020, Daniel Stenberg, , et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms @@ -48,7 +48,7 @@ AM_CPPFLAGS = -I$(top_srcdir)/include \ -I$(top_srcdir)/tests/libtest endif -EXTRA_DIST = Makefile.inc CMakeLists.txt +EXTRA_DIST = Makefile.inc CMakeLists.txt README.md CFLAGS += @CURL_CFLAG_EXTRAS@ diff --git a/tests/unit/README b/tests/unit/README deleted file mode 100644 index 060b670c6..000000000 --- a/tests/unit/README +++ /dev/null @@ -1,74 +0,0 @@ -Unit tests -========== - -The goal is to add tests for *ALL* functions in libcurl. If functions are too -big and complicated, we should split them into smaller and testable ones. - -Build Unit Tests -================ - -'./configure --enable-debug' is required for the unit tests to build. To -enable unit tests, there will be a separate static libcurl built that will be -used exclusively for linking unit test programs. Just build everything as -normal, and then you can run the unit test cases as well. - -Run Unit Tests -============== - -Unit tests are run as part of the regular test suite. If you have built -everything to run unit tests, to can do 'make test' at the root level. Or you -can 'cd tests' and 'make' and then invoke individual unit tests with -./runtests.pl NNNN where NNNN is the specific test number. - -Debug Unit Tests -================ - -If a specific test fails you will get told. The test case then has output left -in the log/ subdirectory, but most importantly you can re-run the test again -using gdb by doing ./runtests.pl -g NNNN. That is, add a -g to make it start -up gdb and run the same case using that. - -Write Unit Tests -================ - -We put tests that focus on an area or a specific function into a single C -source file. The source file should be named 'unitNNNN.c' where NNNN is a -number that starts with 1300 and you can pick the next free number. - -Add your test to tests/unit/Makefile.inc (if it is a unit test). -Add your test data to tests/data/Makefile.inc - -You also need a separate file called tests/data/testNNNN (using the same -number) that describes your test case. See the test1300 file for inspiration -and the tests/FILEFORMAT documentation. - -For the actual C file, here's a very simple example: - ------------------------ start ------------------------------- -#include "curlcheck.h" - -#include "a libcurl header.h" /* from the lib dir */ - -static CURLcode unit_setup( void ) -{ - /* whatever you want done first */ - return CURLE_OK; -} - -static void unit_stop( void ) -{ - /* done before shutting down and exiting */ -} - -UNITTEST_START - - /* here you start doing things and checking that the results are good */ - - fail_unless( size == 0 , "initial size should be zero" ); - fail_if( head == NULL , "head should not be initiated to NULL" ); - - /* you end the test code like this: */ - -UNITTEST_STOP - ------------------------ end ------------------------------- diff --git a/tests/unit/README.md b/tests/unit/README.md new file mode 100644 index 000000000..2880d1979 --- /dev/null +++ b/tests/unit/README.md @@ -0,0 +1,66 @@ +# Unit tests + +The goal is to add tests for *all* functions in libcurl. If functions are too +big and complicated, we should split them into smaller and testable ones. + +## Build Unit Tests + +`./configure --enable-debug` is required for the unit tests to build. To +enable unit tests, there will be a separate static libcurl built that will be +used exclusively for linking unit test programs. Just build everything as +normal, and then you can run the unit test cases as well. + +## Run Unit Tests + +Unit tests are run as part of the regular test suite. If you have built +everything to run unit tests, to can do 'make test' at the root level. Or you +can `cd tests` and `make` and then invoke individual unit tests with +`./runtests.pl NNNN` where `NNNN` is the specific test number. + +## Debug Unit Tests + +If a specific test fails you will get told. The test case then has output left +in the log/ subdirectory, but most importantly you can re-run the test again +using gdb by doing `./runtests.pl -g NNNN`. That is, add a `-g` to make it +start up gdb and run the same case using that. + +## Write Unit Tests + +We put tests that focus on an area or a specific function into a single C +source file. The source file should be named 'unitNNNN.c' where NNNN is a +previously unused number. + +Add your test to `tests/unit/Makefile.inc` (if it is a unit test). Add your +test data file name to `tests/data/Makefile.inc` + +You also need a separate file called `tests/data/testNNNN` (using the same +number) that describes your test case. See the test1300 file for inspiration +and the `tests/FILEFORMAT.md` documentation. + +For the actual C file, here's a very simple example: +~~~c +#include "curlcheck.h" + +#include "a libcurl header.h" /* from the lib dir */ + +static CURLcode unit_setup( void ) +{ + /* whatever you want done first */ + return CURLE_OK; +} + +static void unit_stop( void ) +{ + /* done before shutting down and exiting */ +} + +UNITTEST_START + + /* here you start doing things and checking that the results are good */ + + fail_unless( size == 0 , "initial size should be zero" ); + fail_if( head == NULL , "head should not be initiated to NULL" ); + + /* you end the test code like this: */ + +UNITTEST_STOP -- cgit v1.2.1