Use fptest as testing framework

.github/workflows/ci.yml

@@ -2,20 +2,21 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, use-fptest ]
   pull_request:
     branches: [ master ]
 
 jobs:
   macos-11-big-sur:
+    # if: false (uncomment to skip job)
     runs-on: macos-11
     steps:
       - name: Install FPC
         run: |
           brew update
           brew install fpc
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Compile SDL2 unit
         uses: suve/GHActions-FPC@v0.4.0
         with:
@@ -52,25 +53,17 @@ jobs:
         run: |
           sdl2-config --version
           sdl2-config --libs
-      - name: Test 1 - Compile Init Test
-        uses: suve/GHActions-FPC@v0.4.0
-        with:
-          source: tests/testinit.pas
-          flags: Fl/usr/local/lib
-          verbosity: ewnh
-      - name: Test 1 - Run Init Test
-        run: |
-          ./tests/testinit
-      - name: Test 2 - Compile Version Test
+      - name: Compile SDL2-for-Pascal Test Framework (fptest) and Test Cases
         uses: suve/GHActions-FPC@v0.4.0
         with:
-          source: tests/testversion.pas
-          flags: Fl/usr/local/lib
+          source: tests/sdl2forpascaltests.pas
+          flags: Fl/usr/local/lib Fuunits Futests/fptest/src Futests/fptest/3rdparty/epiktimer
           verbosity: ewnh
-      - name: Test 2 - Run Version Test
+      - name: Run SDL2-for-Pascal Tests
         run: |
-          ./tests/testversion
+          ./tests/sdl2forpascaltests
   ubuntu-20-04:
+    # if: false (uncomment to skip job)
     runs-on: ubuntu-20.04
     steps:
       - name: Install FPC
@@ -79,7 +72,7 @@ jobs:
            sudo apt update
            sudo apt install fpc
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Compile SDL2 unit
         uses: suve/GHActions-FPC@v0.4.0
         with:
@@ -112,32 +105,24 @@ jobs:
           verbosity: ewnh
       - name: Install SDL2 library
         run: sudo apt-get install libsdl2-dev
-      - name: Test 1 - Compile Init Test
+      - name: Compile SDL2-for-Pascal Test Framework (fptest) and Test Cases
         uses: suve/GHActions-FPC@v0.4.0
         with:
-          source: tests/testinit.pas
+          source: tests/sdl2forpascaltests.pas
+          flags: Fuunits Futests/fptest/src Futests/fptest/3rdparty/epiktimer
           verbosity: ewnh
-      - name: Test 1 - Run Init Test
+      - name: Run SDL2-for-Pascal Tests
         run: |
-          mkdir ~/tmp
-          export XDG_RUNTIME_DIR=~/tmp
-          ./tests/testinit
-      - name: Test 2 - Compile Version Test
-        uses: suve/GHActions-FPC@v0.4.0
-        with:
-          source: tests/testversion.pas
-          verbosity: ewnh
-      - name: Test 2 - Run Version Test
-        run: |
-          ./tests/testversion
+          ./tests/sdl2forpascaltests
   windows-2022:
+    # if: false (uncomment to skip job)
     runs-on: windows-2022
     steps:
       - name: Install Lazarus
         run: |
           choco install lazarus
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Compile SDL2 unit
         uses: suve/GHActions-FPC@v0.4.0
         with:
@@ -168,14 +153,14 @@ jobs:
         with:
           source: units/sdl2_ttf.pas
           verbosity: ewnh
-      - name: Test 1 - Compile Init Test
+      - name: Copy SDL2 library file to execution folder
+        run: copy tests/dll/SDL2.dll tests
+      - name: Compile SDL2-for-Pascal Test Framework (fptest) and Test Cases
         uses: suve/GHActions-FPC@v0.4.0
         with:
-          source: tests/testinit.pas
-          flags: Flunits
+          source: tests/sdl2forpascaltests.pas
+          flags: Fuunits Futests/fptest/src Futests/fptest/3rdparty/epiktimer
           verbosity: ewnh
-      #  !!! Since no SDL2.DLL is available via chocolatey, the run will fail.
-      #      TODO: Find solution to install SDL2 binary.
-      #  - name: Test 1 - Run Init Test
-      #    run: |
-      #      ./tests/testinit.exe
+      - name: Run SDL2-for-Pascal Tests
+        run: |
+          ./tests/sdl2forpascaltests.exe

tests/README.md

@@ -1,5 +1,23 @@
-# Tests folder
+# Tests for SDL2-for-Pascal Units
+
+## Goal
+These test cases are meant to ensure a basic quality of the
+[SDL2-for-Pascal Units](https://github.com/PascalGameDevelopment/SDL2-for-Pascal).
+
+## Testing Framework
+We use the [fptest](https://github.com/graemeg/fptest) testing framework to
+perform the testing. For more details on this framework see the _README.adoc_ file.
+
+We modified it:
+- many accompanied files (e. g. demo files) are not shipped (go to
+[fptest](https://github.com/graemeg/fptest) to get the full package)
+- it allows for checking of (classic) pointers now
+- we applied a [fix](https://github.com/graemeg/epiktimer/pull/4) to the
+[EpikTimer](https://wiki.freepascal.org/EpikTimer) unit
+
+## Writing a test
+Just add a test case to *sdl2testcases.pas* by extending the test classes or
+add a new test class if suitable.
+
 
-See issue #22.
 
-Delete this file if the first test has been added.

tests/dll/README-SDL.txt

@@ -0,0 +1,13 @@
+
+Please distribute this file with the SDL runtime environment:
+
+The Simple DirectMedia Layer (SDL for short) is a cross-platform library
+designed to make it easy to write multi-media software, such as games
+and emulators.
+
+The Simple DirectMedia Layer library source code is available from:
+https://www.libsdl.org/
+
+This library is distributed under the terms of the zlib license:
+http://www.zlib.net/zlib_license.html
+

tests/fptest/3rdparty/epiktimer/README.txt

@@ -0,0 +1,128 @@
+
+
+  Description: Precision timer/stopwatch component for Lazarus/FPC
+  Author: Tom Lisjac <netdxr@gmail.com>
+  Contributors:
+    * Felipe Monteiro de Carvalho <felipemonteiro.carvalho@gmail.com>
+    * Marcel Minderhoud
+  License: Modifyed LGPL (The same as Free Pascal RTL and LCL)
+  Copyright (C) 2003-2006 by Tom Lisjac, Felipe Monteiro de Carvalho and Marcel Minderhoud
+  Latest version can be obtained at: http://wiki.lazarus.freepascal.org/EpikTimer
+
+ Contents:
+
+   1. The EpikTimer.pas component and palette icon
+   2. ETPackage.lpk package for installation
+   3. ETDemo demonstration app and host system clock evaluator
+
+ -----------------------------------------------------------------
+
+ The EpikTimer Component
+
+  Documentation:
+    See epiktimer.pas for detailed discussion of timebase sources, timing
+    accuracy and clock correlation techniques that can provide traceable
+    precision during long term measurements.
+
+  Installation:
+    - In Components/Open Package File, open etpackage.lpk.
+    - Compile the component to verify that everything is there.
+    - Install and let Lazarus rebuild
+    - Component will be in the System Palette (stopwatch-ruler icon)
+
+  Usage:
+    Drop the component on a form. The component contains a single timer
+    instance and parameterless calls to start, stop, elapsed and clear
+    will implicitly reference it. If the timer is named ET:
+
+    Procedure InstrumentedCall;
+    Begin
+      ET.Clear; // optional... timer is cleared at creation
+      ET.Start;
+      ExecuteFirstTimedSection;
+      ET.Stop; // the timer is actually paused and can be restarted later
+      TimedSection1:=ET.Elapsed; // store the elapsed in a global
+      MakeAnUntimedOverheadCall; // not counted in the timer
+      ET.Start; //resume the timer... continue accumulating ticks
+      CallTimedSection2;
+      TimedSection2:=ET.Elapsed; //timer keeps running... we've just sample it.
+      CallTimedSection3;
+      CallSomethingElse;
+      TimedSection3:=ET.Elapsed; //keep counting... tap the elapsed
+      CallTimedSection4;
+      TimedSection4:=ET.Elapsed; //keep counting... tap the elapsed
+      ET.clear // done... timer is stopped and zeroed
+    end;
+
+    You can also create any number of timers from a single component on
+    the form by declaring a TimerData record and passing it as a parameter
+    to start, stop, elapsed and clear using the overloaded methods in the
+    component. An example would be:
+
+    Function TimedExecution:Extended;
+      Var DiskAccessTime:TimerData;
+    Begin
+      ET.Clear(DiskAccessTimer); // Declared timers *must* be cleared before use. 
+      ET.Start(DiskAccessTimer);
+      ExecuteTheTimedSection;
+      Result:=ET.Elapsed(DiskAccessTimer); // the timer keeps running...
+      etc...
+
+    See etdemo.pas for additional examples of component usage
+
+ The ETDemo Application
+
+   The ETDemo application does not require EpikTimer to be installed in order
+   to compile and operate. I never liked having to install a palette full of
+   components only to find out that I didn't like any of them! :)
+
+   Installation
+
+     Open etdemo.lpi and compile it.
+
+   Operation
+
+     As the program comes up, it will create and initialize 10 invisible timer
+     forms that can be spawned from the main program's Stopwatch group box. A
+     progress bar is supposed to reduce the boredom.
+
+     Host Hardware Information
+
+       This group evaluates the host system and reports if it finds hardware
+       support for the Pentium Time Stamp Counter. If so, you'll be able to get
+       a snapshot of it's value along with the microsecond ticks from your
+       OS clock. The sizes of the hardware and system ticks isn't as important
+       as the rates that they change. On a Linux system, the system ticks value
+       represent microseconds of Epoch time.
+
+     Timebase Calibration
+
+       If your system lacks the TSC or a microsecond resolution system clock,
+       EpikTimer falls back to using gated measurements for setting the
+       internal tick frequencies. Timing is non-deterministic when calling
+       the Linux kernel so some averaging and smoothing of the resulting jitter
+       is helpful. If EpikTimer is in this mode, long term accuracy isn't
+       guaranteed... but short term comparitive measurements can still be made.
+
+       Pressing "Calibrate" performs overhead extraction and gates the selected
+       timebase against the best timebase gate available on a given host. The 
+       results are displayed in the memo boxes.
+
+    Timebase Correlation
+
+       This is the default mode for measuring the TSC frequency and provides a
+       reliable mechanism for synchronizing the TSC ticks to the system clock.
+       If the system clock is maintained via NTP and the CorrelateTimebases
+       method is called at regular intervals, the TSC stream can display the
+       same long term accuracy (at very high resolutions) as the quality of
+       the system's synchronizing time source.
+
+    Timer/Stopwatch Functions
+
+       This section implements a single stopwatch using the component's internal
+       timer data record. The Spawn Timers group box will bring up the 10 timers
+       that were created and initialized during program startup.
+
+
+      ----------------- End of EpikTimer Release Documentation ------------------
+