<commit_before>Tutorial for Writing Test with ht
=================================

This tutorial describes everything one needs to know to use cmd/ht and write
tests and to combine tests into suites.  The tutorial is intended to be used
in interactive trainings; it may seem overly verbose if read silently.


Running ht
----------

`ht` is a command line application which does need external infastructure,
no Java/Ruby/Python runtime, no special libraries, no configuration files,
no registry entries, nothing. Download the version for your operating
system from (github)[https://github.com/vdobler/ht/releases].

Invoking it without any arguments describes it's usage and shows the
available subcommands. Help for the subcommands can be displayed in the
obvious way:

    $ ./ht
 
    $ ./ht help run

Make sure you use the proper version:
 
    $ ./ht version


Writing Tests
-------------

A test is stored as a JSON object in a file. The object needs three fields:

    {
        "Name":    "Some descriptive name, but no fancy characters please",
        "Request": { ... },
        "Checks":  [ ... ]
    }

Note the field names start with a Capital Letter and will be CamelCase.
Note that acronyms will be in all caps, e.g. "URL"

 * `Name` is a string an is needed to display and log the test properly.
 * `Request` is an object and contains information about the request to make
    for this test.
 * `Checks` is an array if checks to perform on the received response.


### JSON5 actually

The files are not JSON but (kinda [json5 comments]) JSON5: You are allowed
to omit the quotation marks `"` around fields names (if they are "normal"
field names) and the last element in an object or an array may have a trailing
comma `,` and you may add comments:


    {
        // This is a line comment
        Name:    "Some descriptive name, but no fancy characters please",
        Request: { ... },
        Checks:  [ ... ],
    }


### The Request URL

The main (and mandatory) field of `Request` is the `URL` which must be a
complete URL including schema, host (optional port) and path. The URL may
contain a fragment, but this won't be sent to the server.

    {
        Name:    "Unic homepage german",
        Request: {
            URL: "https://www.unic.com/de.html",
        },
        Checks:  [ ],
    }

TLS (SSL) secured request can be made, https:// is supported.
Save this as unic-hp1.ht and execute the request:

    $ ./ht run unic-hp1.ht

This should work, i.e. produce a request and print some output indicating
success but it is almost pointless as no checks are done.


### Checks

Checks provide high- (some low-) level checks on the received response.
We'll start with low-level checks as these are easier to understand.

    {
        Name:    "Unic homepage german",
        Request: {
            URL: "https://www.unic.com/de.html",
        },
        Checks:  [
            { Check: "StatusCode", Expect: 200 },
            { Check: "Body", Contains: "Unic" },
        ],
    }

Which check to execute is given in the `Check` field. Note again the
CamelCase nameing scheme.  A list of available checks is given below.
The other fields determine details of the check and are check dependent.
These other fields names have been chosen to allow "reading" the
check definition almost as clear text:

 * Check the status code and expect a value of 200.
 * Check the request body, it must contain "Unic".

You may want to run it (after saving to unic-hp2.ht):

    $ ./ht run unic-hp2.ht

You should see the passed checks.


<commit_msg>all: describe 'record' mode in tutorial<commit_after>Tutorial for Writing Test with ht
=================================

This tutorial describes everything one needs to know to use cmd/ht and write
tests and to combine tests into suites.  The tutorial is intended to be used
in interactive trainings; it may seem overly verbose if read silently.


Running ht
----------

`ht` is a command line application which does need external infastructure,
no Java/Ruby/Python runtime, no special libraries, no configuration files,
no registry entries, nothing. Download the version for your operating
system from (github)[https://github.com/vdobler/ht/releases].

Invoking it without any arguments describes it's usage and shows the
available subcommands. Help for the subcommands can be displayed in the
obvious way:

    $ ./ht
 
    $ ./ht help run

Make sure you use the proper version:
 
    $ ./ht version


Writing Tests
-------------

A test is stored as a JSON object in a file. The object needs three fields:

    {
        "Name":    "Some descriptive name, but no fancy characters please",
        "Request": { ... },
        "Checks":  [ ... ]
    }

Note the field names start with a Capital Letter and will be CamelCase.
Note that acronyms will be in all caps, e.g. "URL"

 * `Name` is a string an is needed to display and log the test properly.
 * `Request` is an object and contains information about the request to make
    for this test.
 * `Checks` is an array if checks to perform on the received response.


### JSON5 actually

The files are not JSON but (kinda [json5 comments]) JSON5: You are allowed
to omit the quotation marks `"` around fields names (if they are "normal"
field names) and the last element in an object or an array may have a trailing
comma `,` and you may add comments:


    {
        // This is a line comment
        Name:    "Some descriptive name, but no fancy characters please",
        Request: { ... },
        Checks:  [ ... ],
    }


### The Request URL

The main (and mandatory) field of `Request` is the `URL` which must be a
complete URL including schema, host (optional port) and path. The URL may
contain a fragment, but this won't be sent to the server.

    {
        Name:    "Unic homepage german",
        Request: {
            URL: "https://www.unic.com/de.html",
        },
        Checks:  [ ],
    }

TLS (SSL) secured request can be made, https:// is supported.
Save this as unic-hp1.ht and execute the request:

    $ ./ht run unic-hp1.ht

This should work, i.e. produce a request and print some output indicating
success but it is almost pointless as no checks are done.


### Checks

Checks provide high- (some low-) level checks on the received response.
We'll start with low-level checks as these are easier to understand.

    {
        Name:    "Unic homepage german",
        Request: {
            URL: "https://www.unic.com/de.html",
        },
        Checks:  [
            { Check: "StatusCode", Expect: 200 },
            { Check: "Body", Contains: "Unic" },
        ],
    }

Which check to execute is given in the `Check` field. Note again the
CamelCase nameing scheme.  A list of available checks is given below.
The other fields determine details of the check and are check dependent.
These other fields names have been chosen to allow "reading" the
check definition almost as clear text:

 * Check the status code and expect a value of 200.
 * Check the request body, it must contain "Unic".

You may want to run it (after saving to unic-hp2.ht):

    $ ./ht run unic-hp2.ht

You should see the passed checks.


Recording Test skeletons with the reverse proxy
-----------------------------------------------

Writing tests is not that complicated and the subsequent sections deal with
all the fancy stuff you can do and configure. But setting up a fresh set
of tests and combining them to a suite requires several files and some
typing (and getting the filenames right).

To faciliate this `ht` comes with a reverse proxy which can record requests
and responses and generate skeleton tests and suites from this recording.
Let's assue you want to create test for `http://your.own.site/`:

    $ ./ht record http://your.own.site/

Point your browser to `http://localhost:8080` and request the pages
you like to check. Wait more than 1 second between click to allow the
reverse proxy to record the different events.

Try two or three pages.  Now point your browser to
`http://localhost:8080/-ADMIN-`. This should display a small form
whith each row displaying one recorded event. You can delete events
if you do not want to generate tests for them by checking the left box 
and clicking "Update" or you can give more meaningful names to the
events than the autogenrated names by typing them into the box and 
clicking Update.

You may continue to surf the website, you may freely switch between the
site and the `-ADMIN-` form. Once you are satisfied you can "Save" the events
to the given folder and combine them to the given suite.

The generated tests have some stub checks and provide a suitable starting
ground for refining the tests and checks.

What and how the reverse proxy captures requests can be controlled 
by command line options. Please see `$ ./ht help record`.



{'fraction_non_alphanumeric': 0.08723235527359238, 'fraction_numerical': 0.003965107057890563, 'mean_word_length': 2.882145998240985, 'pattern_counts': {'":': 6, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3554494', 'n_tokens_mistral': 2398, 'n_tokens_neox': 2282, 'n_words': 1260}