laantungir/nostr_core_lib
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

un-nest curl

Browse Source
This commit is contained in:
Laan Tungir
2025-08-16 11:22:44 -04:00
parent 77186c88dd
commit 58cabadc44
5586 changed files with 310 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
curl-8.15.0/docs/tests/CI.md Normal file
View File

@@ -0,0 +1,96 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# Continuous Integration for curl
curl runs in many different environments, so every change is run against a
large number of test suites.
Every pull request is verified for each of the following:
- ... it still builds, warning-free, on Linux and macOS, with both
clang and gcc
- ... it still builds fine on Windows with several MSVC versions
- ... it still builds with cmake on Linux, with gcc and clang
- ... it follows rudimentary code style rules
- ... the test suite still runs 100% fine
- ... the release tarball (the "dist") still works
- ... it builds fine in-tree as well as out-of-tree
- ... code coverage does not shrink drastically
- ... different TLS backends still compile and pass tests
If the pull-request fails one of these tests, it shows up as a red X and you
are expected to fix the problem. If you do not understand when the issue is or
have other problems to fix the complaint, just ask and other project members
can likely help out.
Consider the following table while looking at pull request failures:
| CI platform as shown in PR | State | What to look at next |
| ----------------------------------- | ------ | -------------------------- |
| CI / fuzzing | stable | fuzzing results |
| CI / macos ... | stable | all errors and failures |
| FreeBSD FreeBSD: ... | stable | all errors and failures |
| LGTM analysis: Python | stable | new findings |
| LGTM analysis: C/C++ | stable | new findings |
| buildbot/curl_Schannel_ ... | stable | all errors and failures |
| AppVeyor | flaky | all errors and failures |
| curl.curl (linux ...) | stable | all errors and failures |
| curl.curl (windows ...) | flaky | repetitive errors/failures |
Sometimes the tests fail due to a dependency service temporarily being offline
or otherwise unavailable, for example package downloads. In this case you can
just try to update your pull requests to rerun the tests later as described
below.
## CI servers
Here are the different CI environments that are currently in use, and how they
are configured:
### GitHub Actions
GitHub Actions runs the following tests:
- macOS tests with a variety of different compilation options
- Fuzz tests ([see the curl-fuzzer repo for more
info](https://github.com/curl/curl-fuzzer)).
These are each configured in different files in `.github/workflows`.
### Azure
Not used anymore.
### AppVeyor
AppVeyor runs a variety of different Windows builds, with different compilation
options.
As of November 2021 `@bagder`, `@mback2k`, `@jay`, `@vszakats`, `@dfandrich`
and `@danielgustafsson` have administrator access to the AppVeyor CI
environment. Additional admins/group members can be added on request.
The tests are configured in `appveyor.yml`.
### Zuul
Not used anymore.
### Circle CI
Circle CI runs a basic Linux test suite on Ubuntu for both x86 and ARM
processors. This is configured in `.circleci/config.yml`.
You can [view the full list of CI jobs on Circle CI's
website](https://app.circleci.com/pipelines/github/curl/curl).
`@bagder` has access to edit the "Project Settings" on that page. Additional
admins/group members can be added on request.
### Cirrus CI
Not used anymore.

749
curl-8.15.0/docs/tests/FILEFORMAT.md Normal file
View File

@@ -0,0 +1,749 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# curl test suite file format
The curl test suite's file format is simple and extendable, closely resembling
XML. All data for a single test case resides in a single ASCII file. Labels
mark the beginning and the end of all sections, and each label must be written
in its own line. Comments are either XML-style (enclosed with `<!--` and
`-->`) or shell script style (beginning with `#`) and must appear on their own
lines and not alongside actual test data. Most test data files are
syntactically valid XML, although a few files are not (lack of support for
character entities and the preservation of CR/LF characters at the end of
lines are the biggest differences).
Each test case source exists as a file matching the format
`tests/data/testNUM`, where `NUM` is the unique test number, and must begin
with a `testcase` tag, which encompasses the remainder of the file.
# Preprocessing
When a test is to be executed, the source file is first preprocessed and
variables are substituted by their respective contents and the output version
of the test file is stored as `%LOGDIR/testNUM`. That version is what is read
and used by the test servers.
## Base64 Encoding
In the preprocess stage, a special instruction can be used to have runtests.pl
base64 encode a certain section and insert in the generated output file. This
is in particular good for test cases where the test tool is expected to pass
in base64 encoded content that might use dynamic information that is unique
for this particular test invocation, like the server port number.
To insert a base64 encoded string into the output, use this syntax:
%b64[ data to encode ]b64%
The data to encode can then use any of the existing variables mentioned below,
or even percent-encoded individual bytes. As an example, insert the HTTP
server's port number (in ASCII) followed by a space and the hexadecimal byte
9a:
%b64[%HTTPPORT %9a]b64%
## Hexadecimal decoding
In the preprocess stage, a special instruction can be used to have runtests.pl
generate a sequence of binary bytes.
To insert a sequence of bytes from a hex encoded string, use this syntax:
%hex[ %XX-encoded data to decode ]hex%
Other bytes within the brackets that not percent encoded are inserted as-is.
For example, to insert the binary octets 0, 1 and 255 into the test file:
%hex[%00%01%FF]hex%
## Repeat content
In the preprocess stage, a special instruction can be used to have runtests.pl
generate a repetitive sequence of bytes.
To insert a sequence of repeat bytes, use this syntax to make the `<string>`
get repeated `<number>` of times. The number has to be 1 or larger and the
string may contain `%HH` hexadecimal codes:
%repeat[<number> x <string>]%
For example, to insert the word hello 100 times:
%repeat[100 x hello]%
## Insert capped epoch days
Mostly to test capped cookie expire dates: `%days[NUM]` inserts the number of
seconds for the given number of days into the future, aligned to the nearest
minute. That is the same calculation the cookie engine uses to cap expiration
dates.
## Include file
This instruction allows a test case to include another file. It is helpful to
remember that the ordinary variables are expanded before the include happens
so `%LOGDIR` and the others can be used in the include line.
The filename cannot contain `%` as that letter is used to end the name for
the include instruction:
%include filename%
## Conditional lines
Lines in the test file can be made to appear conditionally on a specific
feature (see the "features" section below) being set or not set. If the
specific feature is present, the following lines are output, otherwise it
outputs nothing, until a following else or `endif` clause. Like this:
%if brotli
Accept-Encoding
%endif
It can also check for the inverse condition, so if the feature is *not* set by
the use of an exclamation mark:
%if !brotli
Accept-Encoding: not-brotli
%endif
You can also make an "else" clause to get output for the opposite condition,
like:
%if brotli
Accept-Encoding: brotli
%else
Accept-Encoding: nothing
%endif
Nested conditions are supported.
# Variables
When the test is preprocessed, a range of "variables" in the test file is
replaced by their content at that time.
Available substitute variables include:
- `%CLIENT6IP` - IPv6 address of the client running curl (including brackets)
- `%CLIENT6IP-NB` - IPv6 address of the client running curl (no brackets)
- `%CLIENTIP` - IPv4 address of the client running curl
- `%CURL` - Path to the curl executable
- `%DATE` - current YYYY-MM-DD date
- `%DEV_NULL` - Null device (e.g. /dev/null)
- `%FILE_PWD` - Current directory, on Windows prefixed with a slash
- `%FTP6PORT` - IPv6 port number of the FTP server
- `%FTPPORT` - Port number of the FTP server
- `%FTPSPORT` - Port number of the FTPS server
- `%FTPTIME2` - Timeout in seconds that should be just sufficient to receive a
response from the test FTP server
- `%GOPHER6PORT` - IPv6 port number of the Gopher server
- `%GOPHERPORT` - Port number of the Gopher server
- `%GOPHERSPORT` - Port number of the Gophers server
- `%HOST6IP` - IPv6 address of the host running this test
- `%HOSTIP` - IPv4 address of the host running this test
- `%HTTP2PORT` - Port number of the HTTP/2 server
- `%HTTP6PORT` - IPv6 port number of the HTTP server
- `%HTTPPORT` - Port number of the HTTP server
- `%HTTPSPORT` - Port number of the HTTPS server
- `%HTTPSPROXYPORT` - Port number of the HTTPS-proxy
- `%HTTPTLS6PORT` - IPv6 port number of the HTTP TLS server
- `%HTTPTLSPORT` - Port number of the HTTP TLS server
- `%HTTPUNIXPATH` - Path to the Unix socket of the HTTP server
- `%IMAP6PORT` - IPv6 port number of the IMAP server
- `%IMAPPORT` - Port number of the IMAP server
- `%LOGDIR` - Log directory relative to %PWD
- `%MQTTPORT` - Port number of the MQTT server
- `%NOLISTENPORT` - Port number where no service is listening
- `%POP36PORT` - IPv6 port number of the POP3 server
- `%POP3PORT` - Port number of the POP3 server
- `%PROXYPORT` - Port number of the HTTP proxy
- `%PWD` - Current directory
- `%RESOLVE` - server/resolve command
- `%RTSP6PORT` - IPv6 port number of the RTSP server
- `%RTSPPORT` - Port number of the RTSP server
- `%SMBPORT` - Port number of the SMB server
- `%SMBSPORT` - Port number of the SMBS server
- `%SMTP6PORT` - IPv6 port number of the SMTP server
- `%SMTPPORT` - Port number of the SMTP server
- `%SOCKSPORT` - Port number of the SOCKS4/5 server
- `%SOCKSUNIXPATH` - Path to the Unix socket of the SOCKS server
- `%SRCDIR` - Full path to the source dir
- `%SCP_PWD` - Current directory friendly for the SSH server for the scp:// protocol
- `%SFTP_PWD` - Current directory friendly for the SSH server for the sftp:// protocol
- `%SSHPORT` - Port number of the SCP/SFTP server
- `%SSHSRVMD5` - MD5 of SSH server's public key
- `%SSHSRVSHA256` - SHA256 of SSH server's public key
- `%TELNETPORT` - Port number of the telnet server
- `%TESTNUMBER` - Number of the test case
- `%TFTP6PORT` - IPv6 port number of the TFTP server
- `%TFTPPORT` - Port number of the TFTP server
- `%USER` - Login ID of the user running the test
- `%VERNUM` - the version number of the tested curl (without -DEV)
- `%VERSION` - the full version number of the tested curl
# `<testcase>`
Each test is always specified entirely within the `testcase` tag. Each test
case is split up in four main sections: `info`, `reply`, `client` and
`verify`.
- **info** provides information about the test case
- **reply** is used for the server to know what to send as a reply for the
requests curl sends
- **client** defines how the client should behave
- **verify** defines how to verify that the data stored after a command has
been run ended up correct
Each main section has a number of available subsections that can be specified,
that are checked/used if specified.
## `<info>`
### `<keywords>`
A newline-separated list of keywords describing what this test case uses and
tests. Try to use already used keywords. These keywords are used for
statistical/informational purposes and for choosing or skipping classes of
tests. Keywords must begin with an alphabetic character, `-`, `[` or `{` and
may actually consist of multiple words separated by spaces which are treated
together as a single identifier. Most keywords are only there to provide a way
for users to skip certain classes of tests, if desired, but a few are treated
specially by the test harness or build system.
When running a unit test and the keywords include `unittest`, the `<tool>`
section can be left empty to use the standard unit test tool name `unitN` where
`N` is the test number.
The `text-ci` make target automatically skips test with the `flaky` keyword.
Tests that have strict timing dependencies have the `timing-dependent` keyword.
These are intended to eventually be treated specially on CI builds which are
often run on overloaded machines with unpredictable timing.
Tests using non-7-bit-ASCII characters must provide them with `%hex[]` or
similar.
## `<reply>`
### `<data [nocheck="yes"] [sendzero="yes"] [hex="yes"] [nonewline="yes"] [crlf="yes"]>`
data to be sent to the client on its request and later verified that it
arrived safely. Set `nocheck="yes"` to prevent the test script from verifying
the arrival of this data.
If the data contains `swsclose` anywhere within the start and end tag, and
this is an HTTP test, then the connection is closed by the server after this
response is sent. If not, the connection is kept persistent.
If the data contains `swsbounce` anywhere within the start and end tag, then
the HTTP server overrides the part number response returned for a subsequent
request made by the same test to `previous part number + 1`. For example, if a
test makes a request which causes the server to return `<data>` that contains
keyword `swsbounce` then for the next response it ignores the requested part
number and instead returns `<data1>`. And if `<data1>` contains keyword
`swsbounce` then the next response is `<data2>` and so on. This is useful for
auth tests and similar.
`sendzero=yes` means that the (FTP) server "sends" the data even if the size
is zero bytes. Used to verify curl's behavior on zero bytes transfers.
`hex=yes` means that the data is a sequence of hex pairs. It gets decoded and
used as "raw" data.
`nonewline=yes` means that the last byte (the trailing newline character)
should be cut off from the data before sending or comparing it.
`crlf=yes` forces *header* newlines to become CRLF even if not written so in
the source file. Note that this makes runtests.pl parse and "guess" what is a
header and what is not in order to apply the CRLF line endings appropriately.
For FTP file listings, the `<data>` section is be used *only* if you make sure
that there has been a CWD done first to a directory named `test-[NUM]` where
`NUM` is the test case number. Otherwise the ftp server cannot know from which
test file to load the list content.
### `<dataNUM [crlf="yes"]>`
Send back this contents instead of the `<data>` one. The `NUM` is set by:
- The test number in the request line is >10000 and this is the remainder
of [test case number]%10000.
- The request was HTTP and included digest details, which adds 1000 to `NUM`
- If an HTTP request is NTLM type-1, it adds 1001 to `NUM`
- If an HTTP request is NTLM type-3, it adds 1002 to `NUM`
- If an HTTP request is Basic and `NUM` is already >=1000, it adds 1 to `NUM`
- If an HTTP request is Negotiate, `NUM` gets incremented by one for each
request with Negotiate authorization header on the same test case.
Dynamically changing `NUM` in this way allows the test harness to be used to
test authentication negotiation where several different requests must be sent
to complete a transfer. The response to each request is found in its own data
section. Validating the entire negotiation sequence can be done by specifying
a `datacheck` section.
### `<connect>`
The connect section is used instead of the 'data' for all CONNECT
requests. The remainder of the rules for the data section then apply but with
a connect prefix.
### `<socks>`
Address type and address details as logged by the SOCKS proxy.
### `<datacheck [mode="text"] [nonewline="yes"] [crlf="yes"]>`
if the data is sent but this is what should be checked afterwards. If
`nonewline=yes` is set, runtests cuts off the trailing newline from the data
before comparing with the one actually received by the client.
Use the `mode="text"` attribute if the output is in text mode on platforms
that have a text/binary difference.
### `<datacheckNUM [nonewline="yes"] [mode="text"] [crlf="yes"]>`
The contents of numbered `datacheck` sections are appended to the non-numbered
one.
### `<size>`
number to return on an ftp SIZE command (set to -1 to make this command fail)
### `<mdtm>`
what to send back if the client sends a (FTP) `MDTM` command, set to -1 to
have it return that the file does not exist
### `<postcmd>`
special purpose server-command to control its behavior *after* the
reply is sent
For HTTP/HTTPS, these are supported:
`wait [secs]` - Pause for the given time
### `<servercmd>`
Special-commands for the server.
The first line of this file is always set to `Testnum [number]` by the test
script, to allow servers to read that to know what test the client is about to
issue.
#### For FTP/SMTP/POP/IMAP
- `REPLY [command] [return value] [response string]` - Changes how the server
responds to the [command]. [response string] is evaluated as a perl string,
so it can contain embedded \r\n, for example. There is a special [command]
named "welcome" (without quotes) which is the string sent immediately on
connect as a welcome.
- `REPLYLF` (like above but sends the response terminated with LF-only and not
CRLF)
- `COUNT [command] [num]` - Do the `REPLY` change for `[command]` only `[num]`
times and then go back to the built-in approach
- `DELAY [command] [secs]` - Delay responding to this command for the given
time
- `RETRWEIRDO` - Enable the "weirdo" RETR case when multiple response lines
appear at once when a file is transferred
- `RETRNOSIZE` - Make sure the RETR response does not contain the size of the
file
- `RETRSIZE [size]` - Force RETR response to contain the specified size
- `NOSAVE` - Do not actually save what is received
- `SLOWDOWN` - Send FTP responses with 0.01 sec delay between each byte
- `SLOWDOWNDATA` - Send FTP responses with 0.01 sec delay between each data
byte
- `PASVBADIP` - makes PASV send back an illegal IP in its 227 response
- `CAPA [capabilities]` - Enables support for and specifies a list of space
separated capabilities to return to the client for the IMAP `CAPABILITY`,
POP3 `CAPA` and SMTP `EHLO` commands
- `AUTH [mechanisms]` - Enables support for SASL authentication and specifies
a list of space separated mechanisms for IMAP, POP3 and SMTP
- `STOR [msg]` respond with this instead of default after `STOR`
#### For HTTP/HTTPS
- `auth_required` if this is set and a POST/PUT is made without auth, the
server does NOT wait for the full request body to get sent
- `delay: [msecs]` - delay this amount after connection
- `idle` - do nothing after receiving the request, just "sit idle"
- `stream` - continuously send data to the client, never-ending
- `writedelay: [msecs]` delay this amount between reply packets
- `skip: [num]` - instructs the server to ignore reading this many bytes from
a PUT or POST request
- `rtp: part [num] channel [num] size [num]` - stream a fake RTP packet for
the given part on a chosen channel with the given payload size
- `connection-monitor` - When used, this logs `[DISCONNECT]` to the
`server.input` log when the connection is disconnected.
- `upgrade` - when an HTTP upgrade header is found, the server upgrades to
http2
- `swsclose` - instruct server to close connection after response
- `no-expect` - do not read the request body if Expect: is present
#### For TFTP
`writedelay: [secs]` delay this amount between reply packets (each packet
being 512 bytes payload)
### `<dns>`
Commands for the test DNS server.
- `A: [dotted ipv4 address]` - set IPv4 address to return
- `AAAA: [numerical IPv6 address]` - set IPv6 address to return, with or
without `[]`
## `<client>`
### `<server>`
What server(s) this test case requires/uses. Available servers:
- `dict`
- `file`
- `ftp`
- `ftp-ipv6`
- `ftps`
- `gopher`
- `gopher-ipv6`
- `gophers`
- `http`
- `http/2`
- `http-ipv6`
- `http-proxy`
- `https`
- `https-proxy`
- `https-mtls`
- `httptls+srp`
- `httptls+srp-ipv6`
- `http-unix`
- `imap`
- `mqtt`
- `none`
- `pop3`
- `rtsp`
- `rtsp-ipv6`
- `scp`
- `sftp`
- `smb`
- `smtp`
- `socks4`
- `socks5`
- `socks5unix`
- `telnet`
- `tftp`
Give only one per line. This subsection is mandatory (use `none` if no servers
are required). Servers that require a special server certificate can have the
PEM certificate filename (found in the `certs` directory) appended to the
server name separated by a space.
### `<features>`
A list of features that MUST be present in the client/library for this test to
be able to run. If a required feature is not present then the test is SKIPPED.
Alternatively a feature can be prefixed with an exclamation mark to indicate a
feature is NOT required. If the feature is present then the test is SKIPPED.
Features testable here are:
- `--libcurl`
- `alt-svc`
- `aws` - built with **aws-sigv4** support
- `AppleIDN`
- `asyn-rr` - c-ares is used for additional records only
- `brotli`
- `c-ares` - c-ares is used for (all) name resolves
- `CharConv`
- `codeset-utf8`. If the running codeset is UTF-8 capable.
- `cookies`
- `crypto`
- `Debug`
- `digest`
- `DoH`
- `getrlimit`
- `GnuTLS`
- `GSS-API`
- `h2c`
- `headers-api`
- `HSTS`
- `HTTP-auth`
- `http/2`
- `http/3`
- `HTTPS-proxy`
- `HTTPSRR`
- `IDN`
- `IPv6`
- `Kerberos`
- `Largefile`
- `large-time` (time_t is larger than 32-bit)
- `large-size` (size_t is larger than 32-bit)
- `libssh2`
- `libssh`
- `oldlibssh` (versions before 0.9.4)
- `libz`
- `local-http`. The HTTP server runs on 127.0.0.1
- `manual`
- `mbedtls`
- `Mime`
- `netrc`
- `nghttpx`
- `nghttpx-h3`
- `NTLM`
- `NTLM_WB`
- `OpenSSL`
- `override-dns` - this build can use a "fake" DNS server
- `parsedate`
- `proxy`
- `PSL`
- `rustls`
- `Schannel`
- `shuffle-dns`
- `socks`
- `SPNEGO`
- `SSL`
- `SSLpinning`
- `SSPI`
- `threaded-resolver`
- `TLS-SRP`
- `TrackMemory`
- `typecheck`
- `threadsafe`
- `Unicode`
- `unittest`
- `UnixSockets`
- `verbose-strings`
- `wakeup`
- `win32`
- `WinIDN`
- `wolfssh`
- `wolfssl`
- `xattr`
- `zstd`
as well as each protocol that curl supports. A protocol only needs to be
specified if it is different from the server (useful when the server is
`none`).
### `<killserver>`
Using the same syntax as in `<server>` but when mentioned here these servers
are explicitly KILLED when this test case is completed. Only use this if there
is no other alternatives. Using this of course requires subsequent tests to
restart servers.
### `<precheck>`
A command line that if set gets run by the test script before the test. If an
output is displayed by the command or if the return code is non-zero, the test
is skipped and the (single-line) output is displayed as reason for not running
the test.
### `<tool>`
Name of tool to invoke instead of "curl". This tool must be built and exist
either in the `libtest/` directory (if the tool name starts with `lib`) or in
the `unit/` directory (if the tool name starts with `unit`).
### `<name>`
Brief test case description, shown when the test runs.
### `<setenv>`
variable1=contents1
variable2=contents2
variable3
Set the given environment variables to the specified value before the actual
command is run. They are restored back to their former values again after the
command has been run.
If the variable name has no assignment, no `=`, then that variable is just
deleted.
### `<command [option="no-q/no-output/no-include/force-output/binary-trace"] [timeout="secs"][delay="secs"][type="perl/shell"]>`
Command line to run.
Note that the URL that gets passed to the server actually controls what data
that is returned. The last slash in the URL must be followed by a number. That
number (N) is used by the test-server to load test case N and return the data
that is defined within the `<reply><data></data></reply>` section.
If there is no test number found above, the HTTP test server uses the number
following the last dot in the given hostname (made so that a CONNECT can still
pass on test number) so that "foo.bar.123" gets treated as test case
123. Alternatively, if an IPv6 address is provided to CONNECT, the last
hexadecimal group in the address is used as the test number. For example the
address "[1234::ff]" would be treated as test case 255.
Set `type="perl"` to write the test case as a perl script. It implies that
there is no memory debugging and valgrind gets shut off for this test.
Set `type="shell"` to write the test case as a shell script. It implies that
there is no memory debugging and valgrind gets shut off for this test.
Set `option="no-output"` to prevent the test script to slap on the `--output`
argument that directs the output to a file. The `--output` is also not added
if the verify/stdout section is used.
Set `option="force-output"` to make use of `--output` even when the test is
otherwise written to verify stdout.
Set `option="no-include"` to prevent the test script to slap on the
`--include` argument.
Set `option="no-q"` avoid using `-q` as the first argument in the curl command
line.
Set `option="binary-trace"` to use `--trace` instead of `--trace-ascii` for
tracing. Suitable for binary-oriented protocols such as MQTT.
Set `timeout="secs"` to override default server logs advisor read lock
timeout. This timeout is used by the test harness, once that the command has
completed execution, to wait for the test server to write out server side log
files and remove the lock that advised not to read them. The "secs" parameter
is the not negative integer number of seconds for the timeout. This `timeout`
attribute is documented for completeness sake, but is deep test harness stuff
and only needed for singular and specific test cases. Avoid using it.
Set `delay="secs"` to introduce a time delay once that the command has
completed execution and before the `<postcheck>` section runs. The "secs"
parameter is the not negative integer number of seconds for the delay. This
'delay' attribute is intended for specific test cases, and normally not
needed.
### `<file name="%LOGDIR/filename" [nonewline="yes"]>`
This creates the named file with this content before the test case is run,
which is useful if the test case needs a file to act on.
If `nonewline="yes"` is used, the created file gets the final newline stripped
off.
### `<file1>`
1 to 4 can be appended to 'file' to create more files.
### `<file2>`
### `<file3>`
### `<file4>`
### `<stdin [nonewline="yes"]>`
Pass this given data on stdin to the tool.
If `nonewline` is set, we cut off the trailing newline of this given data
before comparing with the one actually received by the client
## `<disable>`
If `test-duphandle` is a listed item here, this is not run when
`--test-duphandle` is used.
## `<verify>`
### `<errorcode>`
numerical error code curl is supposed to return. Specify a list of accepted
error codes by separating multiple numbers with comma. See test 237 for an
example.
### `<strip>`
One regex per line that is removed from the protocol dumps before the
comparison is made. This is useful to remove dependencies on dynamically
changing protocol data such as port numbers or user-agent strings.
### `<strippart>`
One perl op per line that operates on the protocol dump. This is pretty
advanced. Example: `s/^EPRT .*/EPRT stripped/`.
### `<postcheck>`
A command line that if set gets run by the test script after the test. If the
command exists with a non-zero status code, the test is considered failed.
### `<notexists>`
A list of directory entries that are checked for after the test has completed
and that must not exist. A listed entry existing causes the test to fail.
### `<protocol [nonewline="yes"][crlf="yes"]>`
the protocol dump curl should transmit, if `nonewline` is set, we cut off the
trailing newline of this given data before comparing with the one actually
sent by the client The `<strip>` and `<strippart>` rules are applied before
comparisons are made.
`crlf=yes` forces the newlines to become CRLF even if not written so in the
test.
### `<proxy [nonewline="yes"][crlf="yes"]>`
The protocol dump curl should transmit to an HTTP proxy (when the http-proxy
server is used), if `nonewline` is set, we cut off the trailing newline of
this given data before comparing with the one actually sent by the client The
`<strip>` and `<strippart>` rules are applied before comparisons are made.
### `<stderr [mode="text"] [nonewline="yes"] [crlf="yes"]>`
This verifies that this data was passed to stderr.
Use the mode="text" attribute if the output is in text mode on platforms that
have a text/binary difference.
`crlf=yes` forces the newlines to become CRLF even if not written so in the
test.
If `nonewline` is set, we cut off the trailing newline of this given data
before comparing with the one actually received by the client
### `<stdout [mode="text"] [nonewline="yes"] [crlf="yes"] [loadfile="filename"]>`
This verifies that this data was passed to stdout.
Use the mode="text" attribute if the output is in text mode on platforms that
have a text/binary difference.
If `nonewline` is set, we cut off the trailing newline of this given data
before comparing with the one actually received by the client
`crlf=yes` forces the newlines to become CRLF even if not written so in the
test.
`loadfile="filename"` makes loading the data from an external file.
### `<limit>`
When this test runs and curl was built with debug enabled, runtests make sure
that the set limits are not exceeded. Supported limits:
Allocations: [number of allocation calls]
Maximum allocated: [maximum concurrent memory allocated]
### `<file name="%LOGDIR/filename" [mode="text"]>`
The file's contents must be identical to this after the test is complete. Use
the mode="text" attribute if the output is in text mode on platforms that have
a text/binary difference.
### `<file1>`
1 to 4 can be appended to 'file' to compare more files.
### `<file2>`
### `<file3>`
### `<file4>`
### `<stripfile>`
One perl op per line that operates on the output file or stdout before being
compared with what is stored in the test file. This is pretty
advanced. Example: "s/^EPRT .*/EPRT stripped/"
### `<stripfile1>`
1 to 4 can be appended to `stripfile` to strip the corresponding `<fileN>`
content
### `<stripfile2>`
### `<stripfile3>`
### `<stripfile4>`
### `<upload [crlf="yes"] [nonewline="yes"]>`
the contents of the upload data curl should have sent
`crlf=yes` forces *upload* newlines to become CRLF even if not written so in
the source file.
`nonewline=yes` means that the last byte (the trailing newline character)
should be cut off from the upload data before comparing it.
### `<valgrind>`
disable - disables the valgrind log check for this test

150
curl-8.15.0/docs/tests/HTTP.md Normal file
View File

@@ -0,0 +1,150 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# The curl HTTP Test Suite
This is an additional test suite using a combination of Apache httpd and nghttpx servers to perform various tests beyond the capabilities of the standard curl test suite.
# Usage
The test cases and necessary files are in `tests/http`. You can invoke
`pytest` from there or from the top level curl checkout and it finds all
tests.
```
curl> pytest test/http
platform darwin -- Python 3.9.15, pytest-6.2.0, py-1.10.0, pluggy-0.13.1
rootdir: /Users/sei/projects/curl
collected 5 items
tests/http/test_01_basic.py .....
```
Pytest takes arguments. `-v` increases its verbosity and can be used several times. `-k <expr>` can be used to run only matching test cases. The `expr` can be something resembling a python test or just a string that needs to match test cases in their names.
```
curl/tests/http> pytest -vv -k test_01_02
```
runs all test cases that have `test_01_02` in their name. This does not have to be the start of the name.
Depending on your setup, some test cases may be skipped and appear as `s` in
the output. If you run pytest verbose, it also gives you the reason for
skipping.
# Prerequisites
You need:
1. a recent Python, the `cryptography` module and, of course, `pytest`
2. an apache httpd development version. On Debian/Ubuntu, the package `apache2-dev` has this
3. a local `curl` project build
3. optionally, a `nghttpx` with HTTP/3 enabled or h3 test cases are skipped
### Configuration
Via curl's `configure` script you may specify:
* `--with-test-nghttpx=<path-of-nghttpx>` if you have nghttpx to use somewhere outside your `$PATH`.
* `--with-test-httpd=<httpd-install-path>` if you have an Apache httpd installed somewhere else. On Debian/Ubuntu it will otherwise look into `/usr/bin` and `/usr/sbin` to find those.
* `--with-test-caddy=<caddy-install-path>` if you have a Caddy web server installed somewhere else.
* `--with-test-vsftpd=<vsftpd-install-path>` if you have a vsftpd ftp server installed somewhere else.
## Usage Tips
Several test cases are parameterized, for example with the HTTP version to use. If you want to run a test with a particular protocol only, use a command line like:
```
curl/tests/http> pytest -k "test_02_06 and h2"
```
Test cases can be repeated, with the `pytest-repeat` module (`pip install pytest-repeat`). Like in:
```
curl/tests/http> pytest -k "test_02_06 and h2" --count=100
```
which then runs this test case a hundred times. In case of flaky tests, you can make pytest stop on the first one with:
```
curl/tests/http> pytest -k "test_02_06 and h2" --count=100 --maxfail=1
```
which allow you to inspect output and log files for the failed run. Speaking of log files, the verbosity of pytest is also used to collect curl trace output. If you specify `-v` three times, the `curl` command is started with `--trace`:
```
curl/tests/http> pytest -vvv -k "test_02_06 and h2" --count=100 --maxfail=1
```
all of curl's output and trace file are found in `tests/http/gen/curl`.
## Writing Tests
There is a lot of [`pytest` documentation](https://docs.pytest.org/) with examples. No use in repeating that here. Assuming you are somewhat familiar with it, it is useful how *this* general test suite is setup. Especially if you want to add test cases.
### Servers
In `conftest.py` 3 "fixtures" are defined that are used by all test cases:
1. `env`: the test environment. It is an instance of class
`testenv/env.py:Env`. It holds all information about paths, availability of
features (HTTP/3), port numbers to use, domains and SSL certificates for
those.
2. `httpd`: the Apache httpd instance, configured and started, then stopped at
the end of the test suite. It has sites configured for the domains from
`env`. It also loads a local module `mod_curltest?` and makes it available
in certain locations. (more on mod_curltest below).
3. `nghttpx`: an instance of nghttpx that provides HTTP/3 support. `nghttpx`
proxies those requests to the `httpd` server. In a direct mapping, so you
may access all the resources under the same path as with HTTP/2. Only the
port number used for HTTP/3 requests are different.
`pytest` manages these fixture so that they are created once and terminated
before exit. This means you can `Ctrl-C` a running pytest and the server then
shutdowns. Only when you brutally chop its head off, might there be servers
left behind.
### Test Cases
Tests making use of these fixtures have them in their parameter list. This tells pytest that a particular test needs them, so it has to create them. Since one can invoke pytest for just a single test, it is important that a test references the ones it needs.
All test cases start with `test_` in their name. We use a double number scheme to group them. This makes it ease to run only specific tests and also give a short mnemonic to communicate trouble with others in the project. Otherwise you are free to name test cases as you think fitting.
Tests are grouped thematically in a file with a single Python test class. This is convenient if you need a special "fixture" for several tests. "fixtures" can have "class" scope.
There is a curl helper class that knows how to invoke curl and interpret its output. Among other things, it does add the local CA to the command line, so that SSL connections to the test servers are verified. Nothing prevents anyone from running curl directly, for specific uses not covered by the `CurlClient` class.
### mod_curltest
The module source code is found in `testenv/mod_curltest`. It is compiled using the `apxs` command, commonly provided via the `apache2-dev` package. Compilation is quick and done once at the start of a test run.
The module adds 2 "handlers" to the Apache server (right now). Handler are pieces of code that receive HTTP requests and generate the response. Those handlers are:
* `curltest-echo`: hooked up on the path `/curltest/echo`. This one echoes a request and copies all data from the request body to the response body. Useful for simulating upload and checking that the data arrived as intended.
* `curltest-tweak`: hooked up on the path `/curltest/tweak`. This handler is more of a Swiss army knife. It interprets parameters from the URL query string to drive its behavior.
* `status=nnn`: generate a response with HTTP status code `nnn`.
* `chunks=n`: generate `n` chunks of data in the response body, defaults to 3.
* `chunk_size=nnn`: each chunk should contain `nnn` bytes of data. Maximum is 16KB right now.
* `chunkd_delay=duration`: wait `duration` time between writing chunks
* `delay=duration`: wait `duration` time to send the response headers
* `body_error=(timeout|reset)`: produce an error after the first chunk in the response body
* `id=str`: add `str` in the response header `request-id`
`duration` values are integers, optionally followed by a unit. Units are:
* `d`: days (probably not useful here)
* `h`: hours
* `mi`: minutes
* `s`: seconds (the default)
* `ms`: milliseconds
As you can see, `mod_curltest`'s tweak handler allows Apache to simulate many
kinds of responses. An example of its use is `test_03_01` where responses are
delayed using `chunk_delay`. This gives the response a defined duration and the
test uses that to reload `httpd` in the middle of the first request. A graceful
reload in httpd lets ongoing requests finish, but closes the connection
afterwards and tears down the serving process. The following request then needs
to open a new connection. This is verified by the test case.

321
curl-8.15.0/docs/tests/TEST-SUITE.md Normal file
View File

@@ -0,0 +1,321 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# The curl Test Suite
# Running
See the "Requires to run" section for prerequisites.
In the root of the curl repository:
./configure && make && make test
To run a specific set of tests (e.g. 303 and 410):
make test TFLAGS="303 410"
To run the tests faster, pass the -j (parallelism) flag:
make test TFLAGS="-j10"
"make test" builds the test suite support code and invokes the 'runtests.pl'
perl script to run all the tests. The value of `TFLAGS` is passed
directly to 'runtests.pl'.
When you run tests via make, the flags `-a` and `-s` are passed, meaning
to continue running tests even after one fails, and to emit short output.
If you would like to not use those flags, you can run 'runtests.pl' directly.
You must `chdir` into the tests directory, then you can run it like so:
./runtests.pl 303 410
You must have run `make test` at least once first to build the support code.
To see what flags are available for runtests.pl, and what output it emits, run:
man ./tests/runtests.1
After a test fails, examine the tests/log directory for stdout, stderr, and
output from the servers used in the test.
## Requires to run
- `perl` (and a Unix-style shell)
- `python` (and a Unix-style shell, for SMB and TELNET tests)
- `python-impacket` (for SMB tests)
- `diff` (when a test fails, a diff is shown)
- `stunnel` (for HTTPS and FTPS tests)
- `openssl` (the command line tool, for generating test server certificates)
- `openssh` or `SunSSH` (for SCP and SFTP tests)
- `nghttpx` (for HTTP/2 and HTTP/3 tests)
- An available `en_US.UTF-8` locale
### Installation of impacket
The Python-based test servers support Python 3.
Please install python-impacket in the correct Python environment.
You can use pip or your OS' package manager to install 'impacket'.
On Debian/Ubuntu the package name is 'python3-impacket'
On FreeBSD the package name is 'py311-impacket'
On any system where pip is available: 'python3 -m pip install impacket'
You may also need to manually install the Python package 'six'
as that may be a missing requirement for impacket.
## Event-based
If curl is built with `Debug` enabled (see below), then the `runtests.pl`
script offers a `-e` option (or `--test-event`) that makes it perform
*event-based*. Such tests invokes the curl tool with `--test-event`, a
debug-only option made for this purpose.
Performing event-based means that the curl tool uses the
`curl_multi_socket_action()` API call to drive the transfer(s), instead of
the otherwise "normal" functions it would use. This allows us to test drive
the socket_action API. Transfers done this way should work exactly the same
as with the non-event based API.
To be able to use `--test-event` together with `--parallel`, curl requires
*libuv* to be present and enabled in the build: `configure --enable-libuv`
## Duplicated handles
If curl is built with `Debug` enabled (see below), then the `runtests.pl`
script offers a `--test-duphandle` option. When enabled, curl always
duplicates the easy handle and does its transfers using the new one instead
of the original. This is done entirely for testing purpose to verify that
everything works exactly the same when this is done; confirming that the
`curl_easy_duphandle()` function duplicates everything that it should.
### Port numbers used by test servers
All test servers run on "random" port numbers. All tests must be written to
use the suitable variables instead of fixed port numbers so that test cases
continue to work independently of what port numbers the test servers
actually use.
See [`FILEFORMAT`](FILEFORMAT.md) for the port number variables.
### Test servers
The test suite runs stand-alone servers on random ports to which it makes
requests. For SSL tests, it runs stunnel to handle encryption to the regular
servers. For SSH, it runs a standard OpenSSH server.
The listen port numbers for the test servers are picked randomly to allow
users to run multiple test cases concurrently and to not collide with other
existing services that might listen to ports on the machine.
The HTTP server supports listening on a Unix domain socket, the default
location is 'http.sock'.
For HTTP/2 and HTTP/3 testing an installed `nghttpx` is used. HTTP/3 tests
check if nghttpx supports the protocol. To override the nghttpx used, set
the environment variable `NGHTTPX`. The default can also be changed by
specifying `--with-test-nghttpx=<path>` as argument to `configure`.
### DNS server
There is a test DNS server to allow tests to resolve hostnames to verify
those code paths. This server is started like all the other servers within
the `<servers>` section.
To make a curl build actually use the test DNS server requires a debug
build. When such a test runs, the environment variable `CURL_DNS_SERVER` is
set to identify the IP address and port number of the DNS server to use.
- curl built to use c-ares for resolving automatically asks that server for
host information
- curl built to use `getaddrinfo()` for resolving *and* is built with c-ares
1.26.0 or later, gets a special work-around. In such builds, when the
environment variable is set, curl instead invokes a getaddrinfo wrapper
that emulates the function and acknowledges the DNS server environment
variable. This way, the getaddrinfo-using code paths in curl are verified,
and yet the custom responses from the test DNS server are used.
curl that is built to support a custom DNS server in a test gets the
`override-dns` feature set.
When curl ask for HTTPS-RR, c-ares is always used and in debug builds such
asks respects the dns server environment variable as well.
The test DNS server only has a few limited responses. When asked for
- type `A` response, it returns the address `127.0.0.1` three times
- type `AAAA` response, it returns the address `::1` three times
- other types, it returns a blank response without answers
### Shell startup scripts
Tests which use the ssh test server, SCP/SFTP tests, might be badly
influenced by the output of system wide or user specific shell startup
scripts, .bashrc, .profile, /etc/csh.cshrc, .login, /etc/bashrc, etc. which
output text messages or escape sequences on user login. When these shell
startup messages or escape sequences are output they might corrupt the
expected stream of data which flows to the sftp-server or from the ssh
client which can result in bad test behavior or even prevent the test server
from running.
If the test suite ssh or sftp server fails to start up and logs the message
'Received message too long' then you are certainly suffering the unwanted
output of a shell startup script. Locate, cleanup or adjust the shell
script.
### Memory test
The test script checks that all allocated memory is freed properly IF curl
has been built with the `CURLDEBUG` define set. The script automatically
detects if that is the case, and it uses the `memanalyze.pl` script to
analyze the memory debugging output.
Also, if you run tests on a machine where valgrind is found, the script uses
valgrind to run the test with (unless you use `-n`) to further verify
correctness.
The `runtests.pl` `-t` option enables torture testing mode. It runs each
test many times and makes each different memory allocation fail on each
successive run. This tests the out of memory error handling code to ensure
that memory leaks do not occur even in those situations. It can help to
compile curl with `CPPFLAGS=-DMEMDEBUG_LOG_SYNC` when using this option, to
ensure that the memory log file is properly written even if curl crashes.
### Debug
If a test case fails, you can conveniently get the script to invoke the
debugger (gdb) for you with the server running and the same command line
parameters that failed. Just invoke `runtests.pl <test number> -g` and then
just type 'run' in the debugger to perform the command through the debugger.
### Logs
All logs are generated in the log/ subdirectory (it is emptied first in the
runtests.pl script). They remain in there after a test run.
### Log Verbosity
A curl build with `--enable-debug` offers more verbose output in the logs.
This applies not only for test cases, but also when running it standalone
with `curl -v`. While a curl debug built is
***not suitable for production***, it is often helpful in tracking down
problems.
Sometimes, one needs detailed logging of operations, but does not want
to drown in output. The newly introduced *connection filters* allows one to
dynamically increase log verbosity for a particular *filter type*. Example:
CURL_DEBUG=ssl curl -v https://curl.se
makes the `ssl` connection filter log more details. One may do that for
every filter type and also use a combination of names, separated by `,` or
space.
CURL_DEBUG=ssl,http/2 curl -v https://curl.se
The order of filter type names is not relevant. Names used here are
case insensitive. Note that these names are implementation internals and
subject to change.
Some, likely stable names are `tcp`, `ssl`, `http/2`. For a current list,
one may search the sources for `struct Curl_cftype` definitions and find
the names there. Also, some filters are only available with certain build
options, of course.
### Test input files
All test cases are put in the `data/` subdirectory. Each test is stored in
the file named according to the test number.
See [`FILEFORMAT`](FILEFORMAT.md) for a description of the test case file
format.
### Code coverage
gcc provides a tool that can determine the code coverage figures for the
test suite. To use it, configure curl with `CFLAGS='-fprofile-arcs
-ftest-coverage -g -O0'`. Make sure you run the normal and torture tests to
get more full coverage, i.e. do:
make test
make test-torture
The graphical tool `ggcov` can be used to browse the source and create
coverage reports on \*nix hosts:
ggcov -r lib src
The text mode tool `gcov` may also be used, but it does not handle object
files in more than one directory correctly.
### Remote testing
The runtests.pl script provides some hooks to allow curl to be tested on a
machine where perl can not be run. The test framework in this case runs on
a workstation where perl is available, while curl itself is run on a remote
system using ssh or some other remote execution method. See the comments at
the beginning of runtests.pl for details.
## Test case numbering
Test cases used to be numbered by category ranges, but the ranges filled
up. Subsets of tests can now be selected by passing keywords to the
runtests.pl script via the make `TFLAGS` variable.
New tests are added by finding a free number in `tests/data/Makefile.am`.
## Write tests
Here's a quick description on writing test cases. We basically have three
kinds of tests: the ones that test the curl tool, the ones that build small
applications and test libcurl directly and the unit tests that test
individual (possibly internal) functions.
### test data
Each test has a master file that controls all the test data. What to read,
what the protocol exchange should look like, what exit code to expect and
what command line arguments to use etc.
These files are `tests/data/test[num]` where `[num]` is just a unique
identifier described above, and the XML-like file format of them is
described in the separate [`FILEFORMAT`](FILEFORMAT.md) document.
### curl tests
A test case that runs the curl tool and verifies that it gets the correct
data, it sends the correct data, it uses the correct protocol primitives
etc.
### libcurl tests
The libcurl tests are identical to the curl ones, except that they use a
specific and dedicated custom-built program to run instead of "curl". This
tool is built from source code placed in `tests/libtest` and if you want to
make a new libcurl test that is where you add your code.
### unit tests
Unit tests are placed in `tests/unit`. There is a tests/unit/README
describing the specific set of checks and macros that may be used when
writing tests that verify behaviors of specific individual functions.
The unit tests depend on curl being built with debug enabled.
### test bundles
Individual tests are bundled into single executables, one for libtests, one
for unit tests and one for servers. The executables' first argument is
the name of libtest, unit test or server respectively.
In these executables, the build process automatically renames the entry point
to a unique symbol. `test` becomes `test_<tool>`, e.g. `test_lib1598` or
`test_unit1305`. For servers `main` becomes `main_sws` for the `sws` server,
and so on. Other common symbols may also be suffixed the same way.