Merge pull request #43 from exoticlibraries/dev

Dev

.github/workflows/main.yml

@@ -8,7 +8,7 @@ on:
     branches: [ main ]
 
 jobs:
-  build:
+  exotic-regression:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -54,6 +54,7 @@ jobs:
           sudo mkdir /opt/cmake
           sudo wget https://github.com/Kitware/CMake/releases/download/v3.17.2/cmake-3.17.2-Linux-x86_64.sh
           sudo sh cmake-3.17.2-Linux-x86_64.sh --prefix=/opt/cmake --skip-license
+          sudo apt-get install gcc-multilib g++-multilib
         
       - name: Run Cmake Regression
         run: |
@@ -63,7 +64,7 @@ jobs:
             
   build-and-deploy-gh_pages:
     runs-on: ubuntu-latest
-    needs: execute-cmake-regression
+    needs: exotic-regression
     if: github.event_name == 'push' && contains(github.ref, 'refs/heads/main')
     steps:
       - name: Checkout 🛎️

README.md

@@ -19,11 +19,12 @@ The test results can be outputed as various format JunitXML, Test Anything Proto
 ___
 
 ## Table of content
+- [Features](#features)
 - [Standards Compliance and Portability](#standards-compliance-and-portability)
 - [Installation](#installation)
     - [Install](#install)
         - [Windows](#windows)
-        - [Linux](#linux)
+        - [Unix, Linux, Mac](#unix-linux-mac)
         - [Other platforms](#other-platforms)
 - [Documentation](#documentation)
 - [Usage](#usage)
@@ -38,6 +39,23 @@ ___
 - [References](#references)
 - [License](#license)
 
+## Features
+
+- Single header only, just download cester.h and you are good to go.
+- Automatic test detection, registration and execution, just write your test and run.
+- Isolated unit testing, each test case is executed in it own process so a crashed test can be properly reported.
+- Very portable, compatiple with ANSI C and C++98 without any trade off in functionalities.
+- A test instance object to share data between multiple test case to avoid the global scope pollution.
+- Provides simple API for mocking functions with gcc compiler options.
+- Generate report in various output formats, junitxml, text, tap, tapV13.
+- Does not produce any warnings even with strict warning options turned on.
+- Test for failures such as segfault, memory leak, premature termination e.t.c.
+- Rich collection of assertions for various type with proper reporting.
+- Modular, excluded un-used features from your test, [selective_compilation](https://exoticlibraries.github.io/libcester/docs/selective_compilation.html).
+- No extra dependencies needed, once you have the C or C++ standard library available.
+- Support test fixture to setup and tear down resources used by the test cases.
+- Detail docuentation with examples and API references.
+
 ## Standards Compliance and Portability
 
 The project is compliant with the original C language specification ISO/IEC 9899:1990 and the first POSIX specification IEEE Std 1003.1-1988 which ensures the project compatibility in various environments. It also makes use of features in the newer revisions ISO/IEC 9899:1999 and IEEE Std 1003.1-2001 whenever possible. 
@@ -58,7 +76,7 @@ Install the library using powershell. It auto detect your insalled C and C++ com
 & $([scriptblock]::Create((New-Object Net.WebClient).DownloadString("https://exoticlibraries.github.io/magic/install.ps1"))) libcester
 ```
 
-### Linux
+### Unix, Linux, Mac
 
 Use the remote installation script to install libcester with bash. If the command is executes with super user priviledge (sudo) it will be installed in the folder /usr/include else it will be installed in the folder /usr/local/include. Or you can specify where to install it using the option `--installfolder=./` 
 
@@ -81,10 +99,14 @@ Some of the documentation pages are listed below:
  - [Helper Macros](https://exoticlibraries.github.io/libcester/docs/macros.html)
  - [Manual Tests Registration](https://exoticlibraries.github.io/libcester/docs/manual_test_registration.html)
  - [Cester Options](https://exoticlibraries.github.io/libcester/docs/options.html)
+ - [Test Fixtures](https://exoticlibraries.github.io/libcester/docs/fixtures.html)
  - [Output Formats](https://exoticlibraries.github.io/libcester/docs/output_formats.html)
  - [Testing for failures](https://exoticlibraries.github.io/libcester/docs/test_for_failure.html)
+ - [Testing Output Streams](https://exoticlibraries.github.io/libcester/docs/testing_stream.html)
  - [How it works](https://exoticlibraries.github.io/libcester/how_it_works/index.html)
 
+ For some know unfixed issues see the page [known_issues](file:///C:/Users/thecarisma/Documents/OPEN_SOURCE/EXOTIC_LIBRARIES/libcester/docs/build/html/docs/known_issues.html).
+
 ## Usage
 
 ### Writing and Running test
@@ -203,7 +225,13 @@ If no test was ran or your test cases were not detected, in most cases it becaus
 e.g. in gcc 
 
 ```bash
-gcc -D__BASE_FILE__=\"/the/path/to/yout/testfile.c\" testfile.c -I.
+gcc -D__BASE_FILE__=\"/the/path/to/your/testfile.c\" testfile.c -I.
+```
+
+Setting for Visual C compiler
+
+```powershell
+cl /D__BASE_FILE__=\"/the/path/to/your/testfile.c\" testfile.c
 ```
 
 You can also define the `__BASE_FILE__` at the beginning of your test file with the absolute 

docs/docs/index.rst

@@ -17,4 +17,6 @@ Documentation
    macros
    fixtures
    assertions
-   testing_stream
+   testing_stream
+   selective_compilation
+   known_issues

docs/docs/known_issues.rst

@@ -0,0 +1,57 @@
+
+.. index::
+	single: known_issues
+
+Known Unfixed Issues
+========================
+
+There are some issues detected that cannot or has not not been fixed in the framework, and some 
+features that is close to impossible to implements, these two group of farts are highlighted here:
+
+C++ Dynamic Deallocation
+-------------------------------------------
+
+In C++ it impossible to use the shared test instance variable to share objects that are automatically 
+deallocated when they fall out of scope. For example if a **std::vector** object is to be used to 
+share data across multiple test case and the data is added to the vector object in one of the 
+fixture function (CESTER_BEFORE_ALL, CESTER_BEFORE_EACH), all the test cases relying on the data 
+will fail as the vector object will call it deallocator at the end of the fixture function, hence 
+it will be null in all the test cases.
+
+The solution in this case is to use the global scope for such object and not the `shared_instance->arg` 
+variable, the `shared_instance->ar` will work fine for dynamically allocated objects. 
+
+Instead of 
+
+.. code:: c
+
+	//...
+	CESTER_BEFORE_ALL(inst,  
+		std::vector<int> setup;
+		inst->arg = & setup;
+	)
+
+	CESTER_TEST(vector_push_back, inst, {
+		std::vector<int> setup = *(std::vector<int> *)(inst->arg);
+		setup.push_back(20);
+	})
+	//...
+
+Define in global scope instead
+
+.. code:: c
+
+	//...
+	CESTER_BODY(
+		std::vector<int> setup;
+	)
+
+	CESTER_TEST(vector_push_back, inst, {
+		setup.push_back(20);
+	})
+	//...
+
+This isssue was reported `MarcelInTO <https://github.com/MarcelInTO>`_ in issue 
+`50 <https://github.com/exoticlibraries/libcester/issues/50>`_.
+
+

docs/docs/macros.rst

@@ -784,6 +784,12 @@ This macro was added in `PR 14 <https://github.com/exoticlibraries/libcester/pul
 `nicolasnoble <https://github.com/nicolasnoble>`_.
 
 
+#define CESTER_EXCLUDE_WINDOWS_H
+---------------------------------
+
+Define the macro CESTER_EXCLUDE_WINDOWS_H to prevent the inclusion of the `windows.h` header file.
+Use this to get around conflicts in the windows API and your test.
+
 CESTER_CHANGE_STREAM
 ---------------------
 

docs/docs/selective_compilation.rst

@@ -0,0 +1,86 @@
+
+.. index::
+	single: selective_compilation
+
+Selective Modular Features
+=============================
+
+libcester is build in a very modular manner such that most of the component can be removed and 
+the main feature which is running and reporting test still take place. By excluding some features 
+the generated binary will be smaller compare to when all the features are left to 
+be compiled, by excluding some features libcester is guaranteed to work on various platforms even 
+with very minimal resources.
+
+
+Do not Include windows.h
+-------------------------
+
+Including the **windows.h** header causes problem in some test, so it important to provide 
+solution in such case. By defining the macro `CESTER_EXCLUDE_WINDOWS_H` the windows.h file will 
+not be included in the test. 
+
+The main reason for including the windows.h in libcester is just for printing the text output format with 
+color as the windows terminal by default does not recognize the ASI escape code without changing 
+the mode. So this means that on windows terminal with the old mode the raw ansi code will be written 
+into the terminal else the option is set to no color. This will also disable the execution of test 
+case in independent processes and will rely on signal for recovery from critical error on windows.
+
+The issue related to this was first reported by `MarcelInTO <https://github.com/MarcelInTO>`_ in the pr 
+`47 <https://github.com/exoticlibraries/libcester/pull/47>`_.
+
+Exclude time report
+------------------------
+
+Time keeping causes problem for test which are built for execution on a platform that does not have 
+a proper time keeping mechanism or does not support floating point data types, example of such platform 
+is the PlayStation 1. 
+
+By defining the macro `CESTER_NO_TIME` before including cester.h all the time keeping feature will be 
+disabled, this also reduce the generated binary by 3kb on Windows 10 64 bit compiled with GCC version 10
+with one test case. This feature was introduced by `nicolasnoble <https://github.com/nicolasnoble>`_ in 
+the pr `14 <https://github.com/exoticlibraries/libcester/pull/14>`_.
+
+By removing this feature all time related feature such as keeping record of how long a test case 
+execution take, specifying how long a test case should run will be disabled.
+
+Remove recovery with signal.h
+-------------------------------
+
+On a platform that does not support running test case on their seperate processes, libcester rely on 
+signal.h to recover from critical faulure such as segfault. But in a situation when you are sure 
+any of the test case will not crash you can disable signal.h recovery by defining the macro 
+`CESTER_NO_SIGNAL`.
+
+By disabling signal revovery method the generated binary size reduce by 1kb on Windows 10 64 bit 
+compiled with GCC version 10 with one test case.
+
+Disable memory test
+---------------------
+
+The framework has a very minimal memory test feature that track the amount of memory allocated, 
+it lifecycle and report failure for the test case if it leak any memory, try to use freed memory or 
+trying to free an already freed memory. 
+
+This feature is optional as it might cause issues on some platform, this can also be diabled by 
+defining the macro `CESTER_NO_MEM_TEST` before including cester.h this reduces the generated binary 
+size reduce by 2kb on Windows 10 64 bit compiled with GCC version 10 with one test case.
+
+Select Reporter To Compile
+----------------------------
+WIP
+
+Exclude JunitXml Report
+''''''''''''''''''''''''
+WIP
+
+Exclude Text Report
+'''''''''''''''''''''
+WIP
+
+Exclude Tap Report
+''''''''''''''''''''
+WIP
+
+Exclude TapV13 Report
+'''''''''''''''''''''
+WIP