{"id":16343889,"url":"https://github.com/dawoox/hub-workshop-criterion","last_synced_at":"2025-06-15T20:40:11.359Z","repository":{"id":219245831,"uuid":"748399330","full_name":"Dawoox/HUB-Workshop-Criterion","owner":"Dawoox","description":"Workshop on Criterion, and how/why to use it","archived":false,"fork":false,"pushed_at":"2024-01-29T14:00:32.000Z","size":514,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-05T01:44:12.348Z","etag":null,"topics":["criterion","epitech-workshop"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dawoox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-25T22:10:02.000Z","updated_at":"2024-01-30T02:54:08.000Z","dependencies_parsed_at":"2024-12-27T18:00:22.276Z","dependency_job_id":null,"html_url":"https://github.com/Dawoox/HUB-Workshop-Criterion","commit_stats":{"total_commits":15,"total_committers":2,"mean_commits":7.5,"dds":0.1333333333333333,"last_synced_commit":"de284d06c6d6898a1193eb0e2e0e3b0cc8b6a329"},"previous_names":["dawoox/hub-workshop-criterion"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dawoox/HUB-Workshop-Criterion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dawoox%2FHUB-Workshop-Criterion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dawoox%2FHUB-Workshop-Criterion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dawoox%2FHUB-Workshop-Criterion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dawoox%2FHUB-Workshop-Criterion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dawoox","download_url":"https://codeload.github.com/Dawoox/HUB-Workshop-Criterion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dawoox%2FHUB-Workshop-Criterion/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260046450,"owners_count":22950854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["criterion","epitech-workshop"],"created_at":"2024-10-11T00:26:09.897Z","updated_at":"2025-06-15T20:40:11.320Z","avatar_url":"https://github.com/Dawoox.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Criterion: what is it, why use it, how to use it.\n\n## What is it ?\n\nCriterion is a C/C++ testing framework. It's made to be as simple as it can get while still providing powerful features to make it usable in a wide range of use cases.\n\n## Why use it ?\n\nFirst because without unit tests (we will come back later on what is a unit test and what it's not) at Epitech you won't go far. Unit tests are mandatory to valid your stumper and count for your grade on **every** project.\nBut those rules at Epitech are here for a reason.\n\n\u003e Unit tests are what you are not: reliable\n\nIt might sound dumb, but you especialy  are not as reliable as you think, you will forget to test something when implementing a new feature or fixing an old bug. And depending on the project, if there is not a fail-safe mechanism to warn you when you break something the consequences can be quite literally life or death.\nNo need to worry during your cursus the chance you work on a nuclear plant are quite low (but never zero!), but you might fail a project because when implementing the last thing, on the last day, you broke half of the functions without noticing.\nTesting is a way to ensure that a given function give the correct output, or at least the same every time. It also help to think about every edge-case where your top-of-the-line algorithm could (and will) fail.\n\n## How to use it?\n\nSo now we know what is it, and why it's important to use such testing framework in our code, but how do we use it ?\n\n### Installing Criterion\n\nFirst we need to install criterion (because after all criterion is 'just' a C/C++ library).\nIt will depends on your system so pick the one that correspond to your need.\n\n| Plateform | Command |\n| ---- | ---- |\n| **Ubuntu / Debian** | `apt-get install libcriterion-dev` |\n| **Arch Linux** | `yay -S criterion` |\n| **Nix** | `nix-env -iA ixpkgs#criterion` |\n| **NixOS** | *add* `nixpkgs#criterion` *into your configuration.nix* |\n| **Fedora 38** | Click [here](https://intra.epitech.eu/file/Public/technical-documentations/C/install_criterion.sh) to download a script that install criterion |\n| **Windows** | Click [here](https://github.com/Snaipe/Criterion) to build it from the sources |\n\u003e *Note that to download the Fedora 38 script you need to be logged on the Epitech Intranet website*\n\n![](./doc/pkg_meme.png)\n\n### Using it\n\nTake the project given in the `my_verry_interresting_project` folder. It's made to be as bare bone as it can get. The given Makefile implements the basic rule-set (all, clean, fclean, re). And here comme the interesting part: **we need to edit the Makefile.**\nBecause think of it, we need to compile another binary, with another list of source, it can be a mess really quickly if we don't do it well.\nWe can go with this by two way: either we make another Makefile for our tests, or we improve the current one. In this workshop I will show you how to improve the given Makefile, as it's my personal way of doing this, but both are valid if you follow the standards.\n\nSo let's add a new rule, per standard let's called it `unit_tests`\n```Makefile\nunit_tests:\n\t#DoSomething\n```\n\nThis rule need to compile something, and thus we need the list to thing to compile.\n\nLet's add a new list of sources and the corresponding objects.\n```Makefile\nTEST_SRC = empty\n\nTEST_OBJ = $(TEST_SRC:.c=.o)\n```\n\nFinally we can wrote the line to compile those objects, let's get back to our `unit_tests` line:\n```Makefile\nunit_tests: $(TEST_OBJ)\n\t$(CC) $(TEST_OBJ) $(CFLAGS) -o unit_tests\n```\n\nAnd let's not forget to update our `clean` and `fclean` rules:\n```Makefile\nclean:\n\t@ rm -f $(OBJ)\n\t@ rm -f $(TEST_OBJ)\n\t@ find . -name \"*.gcda\" -delete -o -name \"*.gcno\" -delete\n\nfclean:\n\t@ rm -f $(NAME)\n\t@ rm -f unit_tests\n```\n\nWe are still missing an important part, we need to give a special set of flags to gcc to let it know that we want to compile with our criterion library and with the special magic needed to add coverage (we will come back on that later).\n\nTo do that, let's edit once again the `unit_tests` rule:\n```Makefile\nunit_tests: CFLAGS += -lcriterion --coverage -g3\nunit_tests: $(TEST_OBJ)\n\t$(CC) $(TEST_OBJ) $(CFLAGS) -o unit_tests\n```\n\nLet's breakdown what those do:\n* `-lcriterion` add the criterion library when we compile\n* `--coverage` will tell the compiler to generate special files when running the tests (those `.gcda` or `.gcno`)\n* `-g3` enable the 'debug' mode to keep tracking stuff in the binary so that a debugger could better indicate us where is the issue\n\nBut you might notice an issue, we compile our test only .. with our tests, so they can test anything! That's where we need a bit of trickery, we need to compile our test **without** our main, as Criterion add it's own, but we cannot simply remove our main.c file or our program will never compile on it's own.\n\nThat's why we need to edit a final time our Makefile, edit your Makefile so that it's the same as the snippet bellow, we will breakdown what we change just after.\n```Makefile\nSRC = calculator.c\n\nTEST_SRC := $(SRC)\n\nSRC += main.c\n```\nThis allow use to have in `SRC` the list of all our source code with the main, and in `TEST_SRC` the same without our main, and with our tests (those will be added later).\n\n![](./doc/compile_meme.jpg)\n\n### Writing our first test\n\nWe're getting here, after all this setup we can write our first test!\nPer standard we will put our tests in the `tests` folder, for this time the folder is already created, so you just need to create a file called `my_test.c` in it.\n\nHere is the syntax of a Criterion test:\n```c\n/*\n** EPITECH PROJECT, 2024\n** HUB-Workshop-Criterion\n** File description:\n** my_test.c\n*/\n\n#include \u003ccriterion/criterion.h\u003e\n\nTest(basic, example) {\n    cr_assert_eq((1 + 1), 2);\n}\n```\n\n\u003e *Don't forget to include the criterion library!*\n\nIn the example above, I wrote a test in the `basic` group, with the name `example`.\nAnd the test pass if `(1 + 1)` is equal to `2`;\n\nLet's add this file to our Makefile:\n```Makefile\nTEST_SRC := $(SRC)\nTEST_SRC += ./tests/my_test.c\n```\n\n### Write your own tests\n\nNew it's your part, write at least 4 tests for each function (add and mul).\nDon't hesitate to ask questions if you don't know what/how to test.\n\nPass at the next section **only** if you have 8 or more tests and if they all pass.\n\n### Every is working, and the tests passed !\n\nGreat, our code is working, our tests are reporting 100% passed, any developer would be happy in this situation.\n\nBut now come the issue, we need to implement a new function, something that divide by two a given integer. And here is the dangerous part: we didn't wrote that code, some did it for us, here is the code that is given to you\n```c\nint div_by_two(int a)\n{\n\treturn ((a \u003e\u003e 1) + 1);\n}\n```\n\n![](./doc/confused_cat.png)\n\u003cbr\u003e\n*Copy and paste this snippet of code into calculator.c, no need to worry about calculator.h it's already filled with the needed prototype.*\n\nWrite 4 more functions to test if the function operate as wanted.\nIf it doesn't, you might want to change the implementation, maybe there is another way to divide something by 2?\nRemember you **cannot** edit the main to test if the function is working.\n\n## And voila\n\nYou now know how to use Criterion, why use it, and how to integrate it in your existing Makefile. Don't hesitate to ask questions if you need, use the remaining time to try adding tests to one of our existing project.\n\nIf you need more documentation on how to do something, you can find explained snippets in the `examples` folder, you can also search on the [Epitech wiki](https://epitech-2022-technical-documentation.readthedocs.io/en/latest/criterion.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdawoox%2Fhub-workshop-criterion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdawoox%2Fhub-workshop-criterion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdawoox%2Fhub-workshop-criterion/lists"}