# Manual testing of Balkón

## Script 1: Verify generated files

Goals:

  - To verify that Balkón produces the same output in the testing environment
    as it did in development.

  - To verify that ignored files for Git are set correctly.

  - To verify that the files containing expected or "golden" output of tests
    are up to date.

  - To verify that tests are not being skipped.

Prerequisites:

  - Successfully built Balkón from a clone of its Git repository.

Steps:

  1. Clean the Git working tree so that `git status` reports no differences.

  2. Run automated Balkón tests using `cabal run`.

  3. Verify that all tests passed.

  4. Verify that `git status` reports no differences.

  5. Verify that a file named `spannedLoremIpsum20em.actual` was generated by
     automated tests in the directory `.golden/shapedRuns/`.

      - For example by running the command
        `ls -l .golden/shapedRuns/spannedLoremIpsum20em.actual`
        and checking the file's modification time.


## Script 2: Verify visual output for a whole paragraph

Goals:

  - To identify possible visual problems in the output of Balkón,
    such as incorrectly positioned or scaled glyphs.

Prerequisites:

  - Access to files from the Git repository of Balkón.

  - Successfully built Typograffiti.

    - This script was successfully used with
      [Typograffiti commit 1c30cf54](https://git.argonaut-constellation.org/~alcinnz/Typograffiti/tree/1c30cf5417b88c226b7dfd8cf596e09743023fd2)
      built from source.

    - However, the `draw-shaped` executable is currently known to suffer from a
      heavy memory leak. It may crash in as little as half a minute, depending
      on your system resources.

      To avoid overloading your machine, consider limiting the executable's
      data segment size to 1 GiB (`ulimit -Sd 1048576`), then run `draw-shaped`,
      and either stop the process before inspecting the window's contents, or
      screenshot the window for later inspection and terminate the process.

Steps:


  1. Run Typograffiti with the font path, face index, pixel size,
     and scale set according to the contents of the file
     `.golden/shapedRuns/spannedLoremIpsum20em.fontInfo` from Balkón,
     and with input set to be read from the file
     `.golden/shapedRuns/spannedLoremIpsum20em.golden` from Balkón.

  2. Verify that text is displayed in the output window.

  3. If necessary, resize the window so that the whole paragraph can be seen.

  4. Verify all of the following:

      a. The displayed text is legible.

      b. The displayed glyphs appear at correct sizes.
         There should be a small amount of blank space around each
         visible glyph so that it does not overlap with its neighbours,
         but not so much that the text feels disconnected.

      c. The displayed text matches `loremIpsumParagraph` from the file
         `test/Data/Text/ParagraphLayout/ParagraphData.hs` from Balkón,
         character for character, except where a space was replaced
         by a line break.

      d. All displayed lines are aligned to the left edge of the output,
         without any indentation.

      e. All displayed lines are broken before words,
         not in the middle of words and not before punctuation marks.

      f. Lines do not appear to be broken too early.

      g. The horizontal space between each pair of adjacent words
         appears equal.

      h. The vertical space between the baselines of two adjacent lines
         appears equal.

      i. The text begins at the top of the window, with only a small amount
         of blank space below the top of the window that is not large enough to
         insert another line of text.

## Script 3: Verify visual output for pagination

Goals:

  - To identify possible visual problems created by Balkón splitting up
    a paragraph into pages.

Prerequisites:

  - Access to files from the Git repository of Balkón.

  - Successfully built Typograffiti.
    See previous script.

  - Successfully verified visual output for a whole paragraph.
    See previous script.

Steps:

  1. Run Typograffiti with the font path, face index, pixel size,
     and scale set according to the contents of the file
     `.golden/shapedRuns/spannedLoremIpsum20emPage3.fontInfo` from Balkón,
     and with input set to be read from the file
     `.golden/shapedRuns/spannedLoremIpsum20emPage3.golden` from Balkón.

  2. Verify that text is displayed in the output window.

  3. If necessary, resize the window so that the whole paragraph can be seen.

  4. Verify all of the following:

      a. There are three lines of text displayed.

      b. These three lines look exactly the same as lines 7 through 9
         of the paragraph from the previous script.

      c. All displayed lines are aligned to the left edge of the output,
         without any indentation.

      d. The text begins at the top of the window, with only a small amount
         of blank space below the top of the window that is not large enough to
         insert another line of text.

## Script 4: Verify visual output for vertical alignment

Goals:

  - To verify the correct effect of vertical alignment of inline boxes.

Prerequisites:

  - Access to files from the Git repository of Balkón.

  - Successfully built Typograffiti.
    See previous script.

  - Successfully verified visual output for a whole paragraph.
    See previous script.

  - A horizontal on-screen ruler to check baseline alignment.
    In a stacking window manager, the edge of another window can
    fulfil this role.

Steps:

  1. Run Typograffiti with the font path, face index, pixel size,
     and scale set according to the contents of the file
     `.golden/shapedRuns/mixedVerticalAlignment.fontInfo` from Balkón,
     and with input set to be read from the file
     `.golden/shapedRuns/mixedVerticalAlignment.golden` from Balkón.

  2. Verify that text is displayed in the output window.

  3. If necessary, resize the window so that the whole line can be seen.
     Note that there will be one instance of a letter "X" partially overflowing
     the top edge of the window, which is intentional.

  4. Verify all of the following:

      a. There is a line of text displayed, whose (vertically displaced) words
         read, left to right: "up high and higher down low and lower X X
         stretching tall climax preceding the crash"

      b. The baselines of the words "up", "down", and "stretching" are aligned
         to each other.

      c. The baselines of the words "lower" and "crash" are aligned
         to each other.

      d. The baselines of the words "climax" and "the" are aligned
         to each other.

      e. In the sequence of words "up high and higher", each word is placed
         higher than its preceding word.

      f. In the sequence of words "down low and lower", each word is placed
         lower than its preceding word.

      g. The words "climax" and "the" are placed at the top of the window,
         with only a small amount of blank space below the top of the window.

      h. The word "higher" is placed lower than the words "climax" and "the".

      i. The first letter "X" is placed higher than any of the words,
         and the centre of the letter's shape approximately intersects the top
         edge of the window, making only approximately half of it visible.

      j. The second letter "X" is placed lower than any of the words,
         and the letter's shape intersects the baseline of the words
         "lower" and "crash".