guidelines/UnitTests

   1 How to add unit test
   2 ====================
   3
   4 Unit test brings some advantages, briefly, we can list some of them (reference
   5 [1](https://en.wikipedia.org/wiki/Unit_testing)):
   6
   7 * Tests reduce bugs in new features;
   8 * Tests reduce bugs in existing features;
   9 * Tests are good documentation;
  10 * Tests reduce the cost of change;
  11 * Tests allow refactoring;
  12
  13 With those advantages in mind, it was required to choose a framework which fits
  14 well with C/C++ code.  Hence, it was chosen (google test)
  15 [https://github.com/google/googletest], because it is largely used and it is
  16 relatively easy learn.
  17
  18 Install and configure google test (manually)
  19 --------------------------------------------
  20
  21 In this section, you will see a brief description of how to install google
  22 test. However, it is strongly recommended that you take a look to the official
  23 repository (https://github.com/google/googletest) and refers to that if you
  24 have any problem to install it. Follow the steps below:
  25
  26 * Install: cmake and pthread
  27 * Clone google test project from: https://github.com/google/googletest and
  28   enter in the project directory
  29 * Inside project directory, type:
  30
  31 ```
  32 cmake -DBUILD_SHARED_LIBS=ON .
  33 make
  34 ```
  35
  36 * After compilation, copy all "*.so" inside directory "googlemock" and
  37   "googlemock/gtest" to "/usr/lib/"
  38 * Done! Now you can compile your tests.
  39
  40 If you have any problem, go to the official repository to find help.
  41
  42 Ps.: Some distros already have googletest packed. If your distro supports it,
  43 you can use it instead of compile.
  44
  45 Create new unit test
  46 --------------------
  47
  48 If you want to add new unit tests for Yosys, just follow the steps below:
  49
  50 * Go to directory "yosys/test/unit/"
  51 * In this directory you can find something similar Yosys's directory structure.
  52   To create your unit test file you have to follow this pattern:
  53   fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the
  54   unit test for kernel/celledges.cc, you will need to create a file like this:
  55   tests/unit/kernel/celledgesTest.cc;
  56 * Implement your unit test
  57
  58 Run unit test
  59 -------------
  60
  61 To compile and run all unit tests, just go to yosys root directory and type:
  62 ```
  63 make unit-test
  64 ```
  65
  66 If you want to remove all unit test files, type:
  67 ```
  68 make clean-unit-test
  69 ```