Artifactspublic-v0

curl

master
ply4 git calls42 ms289 KiB2 cachedprotocol v2
131 lines4.1 KiBRaw

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 is a separate static libcurl built that is used exclusively for linking unit test programs. 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 get told. The test case then has output left in the %LOGDIR 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 filename to tests/data/Makefile.am

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 simple example:

c
    #include "unitcheck.h"

    #include "a libcurl header.h" /* from the lib directory */

    static CURLcode test_unit9998(const char *arg)
    {
      UNITTEST_BEGIN_SIMPLE

      /* here you start doing things and checking that the results are good */

      fail_unless(size == 0, "initial size should be zero");
      fail_if(!head, "head should not be initiated to NULL");

      /* you end the test code like this: */

      UNITTEST_END_SIMPLE
    }

Here's an example using optional initialization and cleanup:

c
    #include "unitcheck.h"

    #include "a libcurl header.h" /* from the lib directory */

    static CURLcode t9999_setup(void)
    {
      /* whatever you want done first */
      return CURLE_OK;
    }

    static void t9999_stop(void)
    {
      /* done before shutting down and exiting */
    }

    static CURLcode test_unit9999(const char *arg)
    {
      UNITTEST_BEGIN(t9999_setup())

      /* here you start doing things and checking that the results are good */

      fail_unless(size == 0, "initial size should be zero");
      fail_if(!head, "head should not be initiated to NULL");

      /* you end the test code like this: */

      UNITTEST_END(t9999_stop())
    }

Testing static functions

Lots of internal functions are made static, and they should be static if they are private within a single source file.

The curl build system provides a way to write unit tests that let us properly test these functions while keeping them static in release builds.

A function that is static in the build but should be provided for unit testing needs to replace its static keyword with UNITTEST and it needs to have a prototype provided immediately above it.

An example add_two_integers() function for unit testing:

c
    /* @unittest 1234 */
    UNITTEST int add_two_integers(int a, int b);
    UNITTEST int add_two_integers(int a, int b)
    {
      return a + b;
    }

Since the function is static and is private for this source file, it should not have its prototype in any header file. It must have the @unittest tag referring to which unit test that uses this function in a comment immediately above the function itself.

When building unit tests, the build system automatically generates the lib/unitprotos.h header file with all the prototypes for UNITTEST functions provided in any libcurl C source code files. (This is done by the scripts/extract-unit-protos script.)

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# Unit tests
9The goal is to add tests for *all* functions in libcurl. If functions are too
10big and complicated, we should split them into smaller and testable ones.
12## Build Unit Tests
14`./configure --enable-debug` is required for the unit tests to build. To
15enable unit tests, there is a separate static libcurl built that is used
16exclusively for linking unit test programs. Build everything as normal, and
17then you can run the unit test cases as well.
19## Run Unit Tests
21Unit tests are run as part of the regular test suite. If you have built
22everything to run unit tests, to can do 'make test' at the root level. Or you
23can `cd tests` and `make` and then invoke individual unit tests with
24`./runtests.pl NNNN` where `NNNN` is the specific test number.
26## Debug Unit Tests
28If a specific test fails you get told. The test case then has output left in
29the %LOGDIR subdirectory, but most importantly you can re-run the test again
30using gdb by doing `./runtests.pl -g NNNN`. That is, add a `-g` to make it
31start up gdb and run the same case using that.
33## Write Unit Tests
35We put tests that focus on an area or a specific function into a single C
36source file. The source file should be named `unitNNNN.c` where `NNNN` is a
37previously unused number.
39Add your test to `tests/unit/Makefile.inc` (if it is a unit test). Add your
40test data filename to `tests/data/Makefile.am`
42You also need a separate file called `tests/data/testNNNN` (using the same
43number) that describes your test case. See the test1300 file for inspiration
44and the `tests/FILEFORMAT.md` documentation.
46For the actual C file, here's a simple example:
47~~~c
48 #include "unitcheck.h"
50 #include "a libcurl header.h" /* from the lib directory */
52 static CURLcode test_unit9998(const char *arg)
53 {
54 UNITTEST_BEGIN_SIMPLE
56 /* here you start doing things and checking that the results are good */
58 fail_unless(size == 0, "initial size should be zero");
59 fail_if(!head, "head should not be initiated to NULL");
61 /* you end the test code like this: */
63 UNITTEST_END_SIMPLE
64 }
65~~~
67Here's an example using optional initialization and cleanup:
68~~~c
69 #include "unitcheck.h"
71 #include "a libcurl header.h" /* from the lib directory */
73 static CURLcode t9999_setup(void)
74 {
75 /* whatever you want done first */
76 return CURLE_OK;
77 }
79 static void t9999_stop(void)
80 {
81 /* done before shutting down and exiting */
82 }
84 static CURLcode test_unit9999(const char *arg)
85 {
86 UNITTEST_BEGIN(t9999_setup())
88 /* here you start doing things and checking that the results are good */
90 fail_unless(size == 0, "initial size should be zero");
91 fail_if(!head, "head should not be initiated to NULL");
93 /* you end the test code like this: */
95 UNITTEST_END(t9999_stop())
96 }
97~~~
99## Testing static functions
101Lots of internal functions are made static, and they *should* be static if
102they are private within a single source file.
104The curl build system provides a way to write unit tests that let us properly
105test these functions while keeping them static in release builds.
107A function that is static in the build but should be provided for unit testing
108needs to replace its `static` keyword with `UNITTEST` and it needs to have a
109prototype provided immediately above it.
111An example `add_two_integers()` function for unit testing:
113~~~c
114 /* @unittest 1234 */
115 UNITTEST int add_two_integers(int a, int b);
116 UNITTEST int add_two_integers(int a, int b)
117 {
118 return a + b;
119 }
121~~~
123Since the function is static and is private for this source file, it should
124not have its prototype in any header file. It must have the `@unittest` tag
125referring to which unit test that uses this function in a comment immediately
126above the function itself.
128When building unit tests, the build system automatically generates the
129`lib/unitprotos.h` header file with all the prototypes for `UNITTEST`
130functions provided in any libcurl C source code files. (This is done by the
131`scripts/extract-unit-protos` script.)
Diagnostics4 git calls · 42 ms
CallStatusSizeTime042 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.8 KiB · hit36 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=36
git.response.bytes=1860
git.response.cache=HIT
git.response.duration_ms=36
git.fetch.wants=cfae095208b08f96b1c6d1d1f225ed7bf5664e6c
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1860
git.pkt.payload.max=1839
git.sideband.band1.bytes=1838
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e1fba8ba15a9c0
Request
b778ff2a…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format