On Tue, Oct 24, 2023 at 4:25 PM Achu Luma <ach.lumap@xxxxxxxxx> wrote: > > On Mon, Oct 23, 2023 at 2:41 PM Christian Couder > <christian.couder@xxxxxxxxx> wrote: > > Maybe if you have time you could add some descriptions or comments > > related to the above emails and documents. For example you could tell > > what the new unit test framework will be like, how the unit tests will > > look like, etc. Maybe a short overview would be nice. > > > sure, > 1- https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@xxxxxxxxxx/ > : > The emails highlight the significant milestones achieved in > defining and testing the custom TAP > framework for writing git unit tests. It also contains some > examples of implementation such as > that of STRBUF_INIT with output: > ok 1 - static initialization works > 1..1 > > 2- https://github.com/steadmon/git/blob/unit-tests-asciidoc/Documentation/technical/unit-tests.adoc: > From this technical doc, the new unit test framework in the Git > project represents a significant > enhancement, introducing a systematic and efficient approach to > unit testing. The custom git > TAP implementation was selected from several alternatives based > on strict criteria as the most > suitable test framework for porting the unit tests. > The unit tests are written in pure C, eliminating the need for > the previous shell/test-tool helper > setup, simplifying test configuration, data handling, and > reducing testing runtime. > Each unit test is encapsulated as a function and employs a range > of predefined check functions > for validation. These checks can evaluate conditions, compare > integers or characters, validate > strings, and more, providing comprehensive coverage for test scenarios. > > When a test is run using the TEST() macro, it undergoes a series > of checks, and if any check fails, > a diagnostic message is printed to aid in debugging. This > diagnostic output includes information > about the specific check that failed, the file and line number > where it occurred, and a clear comparison > of the expected and actual values. Such detailed reporting > simplifies the identification and resolution > of issues, contributing to codebase stability. > > Additionally, the framework supports features like skipping tests > with explanations, sending custom > diagnostic messages using test_msg(), and marking known-to-fail > checks using TEST_TODO(). > This flexibility allows developers to tailor their tests to > specific scenarios while ensuring a > comprehensive testing suite. Ok, please add all these explanations above as well as those below to your application document. We prefer that you consider your application document like a patch. So you would send to the mailing list several versions of it for review before submitting officially. > > You could also try to apply the patches in the series that adds the > > test framework, or alternatively use the 'seen' branch where the > > series has been merged, and start playing with it by writing, or > > porting, a small example test. > > > ok, I think I can push a patch for one. I don't think it's necessary to send it to the mailing list for now, but it should definitely be part of your application document. > > > -- Create a New C Test File: For each unit test I plan to migrate, create a new C source file (.c) in the Git project's test suite directory(t/unit-tests). Name it appropriately to reflect the purpose of the test. > > > > Could you provide an example of what the new name would be for an > > existing test that is worth porting? > > > Sure... let's consider an existing unit test in t/helper directory > such as t/helper/test-date.c or > its shell named t0006-date.sh, which is part of the current > shell-based test suite. In the context > of the new unit testing framework, this test could be reimagined and renamed as > "t-date.c". The "t-" prefix is typically used for test program files > in Git, and "date" is retained to > reflect the nature of the tests within this suite. Ok. > > > -- Include Necessary Headers:In the new C test file, include the necessary Git unit test framework headers. Typically, this includes headers like "test-lib.h" and others relevant to the specific test. > > > #include "test-lib.h" > > > > Maybe you could continue the above example and tell which headers > > would be needed for it? > > > > > -- Convert Test Logic: Refactor the test logic from the original Shell script into the new C-based test format. Use the testing macros provided by the Git unit test framework, such as test_expect_success, test_expect_failure, etc., to define the tests. > > > test_expect_success("simple progress display", "{ > > > // Test logic here... > > > }"); > > > > Ok, a simple example would be nice too. > > > we can continue with the example used for naming: test-date.c. a > typical t-date.c unit test would look > like the following: > -- > #include "test-lib.h" > #include "date.h" > -- > date.h here is a necessary header file. Now refactoring the test logic > from the original shell script: > -- > #include "test-lib.h" > #include "date.h" > > static void test_parse_dates(void) > { > const char *dates[] = { "invalid_date", "2023-10-17 10:00:00 +0200", NULL }; > > for (const char **argv = dates; *argv; argv++) { > check_int(parse_dates((const char *[]){ *argv, NULL }), 0); > } > } > -- Nice! > > > -- Add Test Descriptions: Provide clear and informative descriptions for each test using the testing macros. These descriptions will help in identifying the purpose of each test when the test suite is run. > > > > This would seem to be part of the previous step, as you would have to > > provide a description when using the testing macro. But Ok. > > > > > -- Define a Test Entry Point: Create a cmd_main function as the entry point for the C-based tests. Inside this function, include the test functions using the testing macros. > > > int cmd_main(int argc, const char **argv) { > > > // Test functions... > > > return test_done(); > > > } > > > > Yeah, continuing an example would be nice. > > > Continuing, we can add a test entrance as follows: > -- > #include "test-lib.h" > #include "date.h" > > static void test_parse_dates(void) > { > const char *dates[] = { "invalid_date", "2023-10-17 10:00:00 +0200", NULL }; > > for (const char **argv = dates; *argv; argv++) { > check_int(parse_dates((const char *[]){ *argv, NULL }), 0); > } > } > > int main(int argc UNUSED, const char **argv UNUSED) > { > TEST(test_parse_dates, "Test date parsing"); > > return test_done(); > } > -- > > A typical unit tests with the custom TAP framework would look > something like above. This might run in theory > but I have not yet run it as I used it here just for demonstration. > The unit tests can be built using > "make unit-tests." Additionally, Makefile can be modified to add the > file to the build: > -- > UNIT_TEST_PROGRAMS += t-date > -- Great! Thanks, Christian.
