kcgiregress.3

NAME

kcgiregress, kcgi_regress_cgi, kcgi_regress_fcgi — regression framework for kcgi

SYNOPSIS

#include <kcgiregress.h>

int
kcgi_regress_cgi(int (*client)(void *), void *clientData, int (*server)(void *), void *serverData);

int
kcgi_regress_fcgi(int (*client)(void *), void *clientData, int (*server)(void *), void *serverData);

DESCRIPTION

Automated testing platform for kcgi(3). Allow for emulated CGI or FastCGI environments over a local network port.

The server callback is invoked with argument serverArg within a CGI or FastCGI environment as if it were spawned by a web server, upon which the usual khttp_parse(3) or khttp_fcgi_init(3) and khttp_fcgi_parse(3) functions are usually used to test behaviour. The client callback communicates with the server over port 17123. Usually this is orchestrated with libcurl(3). The port number is fixed. Clients are restricted to the HTTP GET, OPTIONS, and POST methods.

Both of these callbacks must return zero on failure, non-zero on success.

To compile and link, use pkg-config(1) as follows:

% cc `pkg-config --cflags kcgi-regress` -c -o sample.o sample.c
% cc -o sample sample.o `pkg-config --libs kcgi-regress`

kcgi(3) components should use their respective pkg-config(1) identifiers, such as "kcgi-json" for kcgijson(3) output. Applications using libcurl(3) should further use curl-config(1) as well, or on some systems, pkg-config(1) with "libcurl".

RETURN VALUES

These functions return zero on failure, non-zero on success.

EXAMPLES

The following regression test simply checks that the server responds. Its only check is for operation and HTTP status code (201).

#include <stdarg.h>
#include <stdint.h>
#include <stdlib.h>
#include <curl/curl.h>
#include <kcgi.h>
#include <kcgijson.h>
#include <kcgiregress.h>

static int
server(void *arg)
{
  struct kreq      r;

  if (khttp_parse(&r, NULL, 0, NULL, 0, 0) != KCGI_OK)
    return 0;
  khttp_head(&r, kresps[KRESP_STATUS],
    "%s", khttps[KHTTP_201]);
  khttp_head(&r, kresps[KRESP_CONTENT_TYPE],
    "%s", kmimetypes[KMIME_APP_JSON]);
  khttp_body(&r);
  khttp_free(&r);

  return 1;
}

static int
client(void *arg)
{
  CURL    *curl;
  long     http;

  if ((curl = curl_easy_init()) == NULL)
    return 0;
  curl_easy_setopt(curl, CURLOPT_URL,
    "http://localhost:17123/index.json");
  if (curl_easy_perform(curl) != CURLE_OK)
    return 0;
  curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http);
  curl_easy_cleanup(curl);
  curl_global_cleanup();

  return http == 201;
}

int
main(void)
{
  return kcgi_regress_cgi
    (client, NULL, server, NULL) ? 0 : 1;
}

To compile this simple regression test, the kcgi(3), kcgiregress(3), kcgijson(3), and libcurl(3) libraries and headers are needed, along with further dependencies. Let the file be named sample.c.

% export PKGS="kcgi-regress kcgi-json libcurl"
% cc `pkg-config --cflags $PKGS` -c sample.c
% cc -o sample sample.o `pkg-config --libs $PKGS`

This assumes that libcurl(3) has its configuration recognised by pkg-config(1), which isn't always the case: sometimes curl-config(1) is required.

AUTHORS