KCGIREGRESS(3)

NAME
kcgiregress, kcgi_regress_cgi, kcgi_regress_fcgi - regression framework for kcgi

LIBRARY
libkcgiregress

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
Written by Kristaps Dzonsons <kristaps@bsd.lv>.