[Outreachy] Move existing tests to a unit testing framework

[Outreachy] Move existing tests to a unit testing framework

[Luma]

Hi;
My name is Luma, and  I wanted to take a moment to introduce myself
and share some
insights on an essential aspect of  avoiding pipes in git related
commands in test scripts.

I am an outreachy applicant for the December 2023 cohort and look
forward to learning from you.

One common practice in shell scripting is the use of pipes (|) to
chain multiple commands together.
 While pipes are incredibly versatile and useful, excessive use of
them can lead to script complexity.
I plan to avoid overusing pipes in test scripts by: leveraging command
options, using temporary files
and using functions and variables to break down complex pipelines.

If you have any questions on pipes, I'm always here to learn and share
knowledge.

Best regards,
Luma.

Re: [Outreachy] Move existing tests to a unit testing framework

[Junio C Hamano]

Luma <ach.lumap@gmail.com> writes:

> Hi;
> My name is Luma, and  I wanted to take a moment to introduce myself
> and share some
> insights on an essential aspect of  avoiding pipes in git related
> commands in test scripts.
>
> I am an outreachy applicant for the December 2023 cohort and look
> forward to learning from you.

I notice that the title of the message and the immediate topic you
discuss in the body of the message do not match.  I presume that the
topic on the title is what you prefer to work on if the unit testing
framework is ready by the time Outreachy program starts, and the
mention about "do not clobber exit code of Git with pipes in the
tests" is your "dip the tip of a toe in water" microproject?

Welcome to the Git development community.

Do you have a single word name?  If so please disregard the below,
but in case "Luma" is just a nickname (e.g. like I am introducing
myself to my Git friends "Hi, I am Gitster!") you use online, please
read on.

For signing off your patches, we'd prefer to see your real name
used, as Signed-off-by: is meant to have legal significance.  And
because we also expect the authorship identity to match the
name/e-mail of the sign-off, it would mean your patch submissions
are expected to look like:

	From: Luma <ach.lumap@gmail.com>
	Subject: ... title of the patch goes here ...

	... body of the proposed commit log message goes here...

	Signed-off-by: Luma <ach.lumap@gmail.com>

but "Luma" replaced with your full real name.

Thanks.

Re: [Outreachy] Move existing tests to a unit testing framework

[Luma]

oh yes, "Move existing tests to a unit testing framework" was the
only listed project for this current Outreachy cohort. So, I used it
to express my intent.
I appreciate the clarification on authorship identity for patches. I
will update subsequent patches with a legal full name to conform to
the community rules.

Regards.

On Tue, Oct 3, 2023 at 7:51 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Luma <ach.lumap@gmail.com> writes:
>
> > Hi;
> > My name is Luma, and  I wanted to take a moment to introduce myself
> > and share some
> > insights on an essential aspect of  avoiding pipes in git related
> > commands in test scripts.
> >
> > I am an outreachy applicant for the December 2023 cohort and look
> > forward to learning from you.
>
> I notice that the title of the message and the immediate topic you
> discuss in the body of the message do not match.  I presume that the
> topic on the title is what you prefer to work on if the unit testing
> framework is ready by the time Outreachy program starts, and the
> mention about "do not clobber exit code of Git with pipes in the
> tests" is your "dip the tip of a toe in water" microproject?
>
> Welcome to the Git development community.
>
> Do you have a single word name?  If so please disregard the below,
> but in case "Luma" is just a nickname (e.g. like I am introducing
> myself to my Git friends "Hi, I am Gitster!") you use online, please
> read on.
>
> For signing off your patches, we'd prefer to see your real name
> used, as Signed-off-by: is meant to have legal significance.  And
> because we also expect the authorship identity to match the
> name/e-mail of the sign-off, it would mean your patch submissions
> are expected to look like:
>
>         From: Luma <ach.lumap@gmail.com>
>         Subject: ... title of the patch goes here ...
>
>         ... body of the proposed commit log message goes here...
>
>         Signed-off-by: Luma <ach.lumap@gmail.com>
>
> but "Luma" replaced with your full real name.
>
> Thanks.

Re: [Outreachy] Move existing tests to a unit testing framework

[Luma]

Dear Git Community and Mentors,

I hope this email finds you well. My name is Achu Luma, and I am
excited to submit my application for the Outreachy program with the
Git project.
I have been a passionate open-source enthusiast and a dedicated Git
user for two years, and I am thrilled at the opportunity to contribute
to the Git community.

Introduction:
----------------
I study Computer Science from the University of Bamenda. Over the past
4 years, I have gained experience in software development and have
participated in various class projects.

Why I am a Good Fit:
----------------------
1. Proficient with Git: I have a good understanding of Git's version
control system and have successfully used it in both personal and
educational projects.

2. Strong Programming Skills: My programming skills in python, C etc
and experience with git, shell etc make me well-prepared to contribute
to Git's codebase.

3. Open Source Involvement: I have actively contributed to git
open-source project, including
https://public-inbox.org/git/20231003174853.1732-1-ach.lumap@gmail.com/T/#t
, where I have submitted a patch that has been well-received.

Project Idea - Moving Existing Tests to a Unit Testing Framework:
------------------------------------------------------------------
I am excited about "Moving Existing Tests to a Unit Testing Framework".
The objective of this project is to enhance the efficiency and
maintainability of Git's testing infrastructure by porting existing
unit tests to a unit testing framework.

**Project Plan**:
- Evaluate the existing tests in the `t/helper/` directory to identify
those suitable for migration to the unit testing framework.
- Develop a migration strategy and create detailed plans for adapting
these tests.
- Port the identified tests to the unit testing framework while
ensuring they maintain their functionality.
- Verify the correctness and reliability of the migrated tests through
thorough testing and validation.
- Collaborate with the Git community to gather feedback and make
necessary adjustments.

**Timeline**:
- Community Bonding (Oct 2 - Nov 20): Familiarize myself with the Git
project and establish communication channels.
- Coding Phase (Dec 4 - Jan 15): Implement the migration of tests and
seek feedback from mentors and the community.
- Testing and Validation (Jan 15 - Feb 15): Rigorously test the
migrated tests and make improvements based on feedback.
- Documentation and Finalization (Feb 15 - March 1): Document the
migration process and finalize the project.

**Contribution to Git Community**:
I have actively participated in Git's mailing-list discussions and
submitted a patch(
https://public-inbox.org/git/20231003174853.1732-1-ach.lumap@gmail.com/T/#t)
for review. I have received positive feedback on my contributions, and
it has been queued to be merged into official Git branches maintained
by Junio. Additionally, I have been involved in discussions related to
the git project.(https://public-inbox.org/git/CAFR+8DyN8vbuvdgZPkSVqS2=sqconwhx3QfcpJ0+Wi_oCA=s0w@mail.gmail.com/T/#t)

**Proposal Drafts**:
I have shared drafts of this proposal on the Git mailing list
git@vger.kernel.org  and will incorporate valuable feedback provided
by the community.

**Next Steps**:
I am eager to discuss my proposal further and collaborate with the Git
community to ensure the success of this project. I will continue to
engage with the community, seek guidance, and refine my proposal as
per your suggestions.

Thank you for considering my application. I look forward to the
opportunity to contribute to the Git project and help make it even
more robust and reliable.

Best Regards,

On Wed, Oct 4, 2023 at 12:36 AM Luma <ach.lumap@gmail.com> wrote:
>
> oh yes, "Move existing tests to a unit testing framework" was the
> only listed project for this current Outreachy cohort. So, I used it
> to express my intent.
> I appreciate the clarification on authorship identity for patches. I
> will update subsequent patches with a legal full name to conform to
> the community rules.
>
> Regards.
>
> On Tue, Oct 3, 2023 at 7:51 PM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Luma <ach.lumap@gmail.com> writes:
> >
> > > Hi;
> > > My name is Luma, and  I wanted to take a moment to introduce myself
> > > and share some
> > > insights on an essential aspect of  avoiding pipes in git related
> > > commands in test scripts.
> > >
> > > I am an outreachy applicant for the December 2023 cohort and look
> > > forward to learning from you.
> >
> > I notice that the title of the message and the immediate topic you
> > discuss in the body of the message do not match.  I presume that the
> > topic on the title is what you prefer to work on if the unit testing
> > framework is ready by the time Outreachy program starts, and the
> > mention about "do not clobber exit code of Git with pipes in the
> > tests" is your "dip the tip of a toe in water" microproject?
> >
> > Welcome to the Git development community.
> >
> > Do you have a single word name?  If so please disregard the below,
> > but in case "Luma" is just a nickname (e.g. like I am introducing
> > myself to my Git friends "Hi, I am Gitster!") you use online, please
> > read on.
> >
> > For signing off your patches, we'd prefer to see your real name
> > used, as Signed-off-by: is meant to have legal significance.  And
> > because we also expect the authorship identity to match the
> > name/e-mail of the sign-off, it would mean your patch submissions
> > are expected to look like:
> >
> >         From: Luma <ach.lumap@gmail.com>
> >         Subject: ... title of the patch goes here ...
> >
> >         ... body of the proposed commit log message goes here...
> >
> >         Signed-off-by: Luma <ach.lumap@gmail.com>
> >
> > but "Luma" replaced with your full real name.
> >
> > Thanks.

Re: [Outreachy] Move existing tests to a unit testing framework

[Achu Luma]

Dear Git Community and Mentors,

I hope this email finds you well. As a follow-up to my previous
application, I'd like to provide additional details on the process of
migrating existing unit tests from the t/helper/ directory to the new
Git unit test framework.
-- Identify Target Unit Tests: Start by identifying the specific unit
tests in the t/helper/ directory that we want to port to the new Git
unit test framework. Ensure that the tests are suitable for migration
and that the benefits of doing so outweigh the effort(By avoiding
integration tests). The following points have been developed with on
going work on the unit-tests framework visible here: 1-
https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/
2- https://github.com/steadmon/git/blob/unit-tests-asciidoc/Documentation/technical/unit-tests.adoc

-- 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.

--  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"

-- 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...
}");

-- 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.

-- 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();
}

-- Ensure TAP Format Output: Ensure that the C-based tests produce
output in the Test Anything Protocol (TAP) format. This format
includes the test name, status (ok or not ok), and any diagnostic
information.

-- Test Interaction: Ensure that the migrated tests interact correctly
with the new Git unit test framework and any other tests that may be
relevant. Consider dependencies and interactions with other parts of
the Git project.

-- Test Execution: Run the migrated tests to verify that they produce
the expected results when executed as part of the Git project's test
suite. Use the Git testing framework's test runners to execute the
tests.

-- Documentation Update: Update the Git project's documentation to
reflect the changes made during the migration. Include a reference to
the original unit tests in the t/helper/ directory and indicate that
these tests have been ported to the new Git unit test framework.

By following these points, I think I can successfully port existing
unit tests from the t/helper/ directory to use the new Git unit test
framework. This migration helps standardize and streamline the testing
process within the Git project, improving code quality and
maintainability.

Next Steps:

I am eager to discuss these suggestions and collaborate with the Git
community to ensure the success of this project. I will continue to
engage with the community, seek guidance, and refine my proposal as
per your suggestions.
 I look forward to the opportunity to contribute to the Git project
and help make it even more robust and reliable.

Best Regards,
Achu Luma


On Fri, Oct 20, 2023 at 2:15 PM Achu Luma <ach.lumap@gmail.com> wrote:
>
> Dear Git Community and Mentors,
>
> I hope this email finds you well. As a follow-up to my previous application, I'd like to provide additional details on the process of migrating existing unit tests from the t/helper/ directory to the new Git unit test framework.
> -- Identify Target Unit Tests: Start by identifying the specific unit tests in the t/helper/ directory that we want to port to the new Git unit test framework. Ensure that the tests are suitable for migration and that the benefits of doing so outweigh the effort(By avoiding integration tests). The following points have been developed with on going work on the unit-tests framework visible here: 1- https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/
> 2- https://github.com/steadmon/git/blob/unit-tests-asciidoc/Documentation/technical/unit-tests.adoc
>
> -- 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.
>
> --  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"
>
> -- 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...
> }");
>
> -- 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.
>
> -- 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();
> }
>
> -- Ensure TAP Format Output: Ensure that the C-based tests produce output in the Test Anything Protocol (TAP) format. This format includes the test name, status (ok or not ok), and any diagnostic information.
>
> -- Test Interaction: Ensure that the migrated tests interact correctly with the new Git unit test framework and any other tests that may be relevant. Consider dependencies and interactions with other parts of the Git project.
>
> -- Test Execution: Run the migrated tests to verify that they produce the expected results when executed as part of the Git project's test suite. Use the Git testing framework's test runners to execute the tests.
>
> -- Documentation Update: Update the Git project's documentation to reflect the changes made during the migration. Include a reference to the original unit tests in the t/helper/ directory and indicate that these tests have been ported to the new Git unit test framework.
>
> By following these points, I think I can successfully port existing unit tests from the t/helper/ directory to use the new Git unit test framework. This migration helps standardize and streamline the testing process within the Git project, improving code quality and maintainability.
>
> Next Steps:
>
> I am eager to discuss these suggestions and collaborate with the Git community to ensure the success of this project. I will continue to engage with the community, seek guidance, and refine my proposal as per your suggestions.
>  I look forward to the opportunity to contribute to the Git project and help make it even more robust and reliable.
>
> Best Regards,
> Achu Luma
>
> On Mon, Oct 9, 2023 at 10:15 AM Luma <ach.lumap@gmail.com> wrote:
>>
>> Dear Git Community and Mentors,
>>
>> I hope this email finds you well. My name is Achu Luma, and I am
>> excited to submit my application for the Outreachy program with the
>> Git project.
>> I have been a passionate open-source enthusiast and a dedicated Git
>> user for two years, and I am thrilled at the opportunity to contribute
>> to the Git community.
>>
>> Introduction:
>> ----------------
>> I study Computer Science from the University of Bamenda. Over the past
>> 4 years, I have gained experience in software development and have
>> participated in various class projects.
>>
>> Why I am a Good Fit:
>> ----------------------
>> 1. Proficient with Git: I have a good understanding of Git's version
>> control system and have successfully used it in both personal and
>> educational projects.
>>
>> 2. Strong Programming Skills: My programming skills in python, C etc
>> and experience with git, shell etc make me well-prepared to contribute
>> to Git's codebase.
>>
>> 3. Open Source Involvement: I have actively contributed to git
>> open-source project, including
>> https://public-inbox.org/git/20231003174853.1732-1-ach.lumap@gmail.com/T/#t
>> , where I have submitted a patch that has been well-received.
>>
>> Project Idea - Moving Existing Tests to a Unit Testing Framework:
>> ------------------------------------------------------------------
>> I am excited about "Moving Existing Tests to a Unit Testing Framework".
>> The objective of this project is to enhance the efficiency and
>> maintainability of Git's testing infrastructure by porting existing
>> unit tests to a unit testing framework.
>>
>> **Project Plan**:
>> - Evaluate the existing tests in the `t/helper/` directory to identify
>> those suitable for migration to the unit testing framework.
>> - Develop a migration strategy and create detailed plans for adapting
>> these tests.
>> - Port the identified tests to the unit testing framework while
>> ensuring they maintain their functionality.
>> - Verify the correctness and reliability of the migrated tests through
>> thorough testing and validation.
>> - Collaborate with the Git community to gather feedback and make
>> necessary adjustments.
>>
>> **Timeline**:
>> - Community Bonding (Oct 2 - Nov 20): Familiarize myself with the Git
>> project and establish communication channels.
>> - Coding Phase (Dec 4 - Jan 15): Implement the migration of tests and
>> seek feedback from mentors and the community.
>> - Testing and Validation (Jan 15 - Feb 15): Rigorously test the
>> migrated tests and make improvements based on feedback.
>> - Documentation and Finalization (Feb 15 - March 1): Document the
>> migration process and finalize the project.
>>
>> **Contribution to Git Community**:
>> I have actively participated in Git's mailing-list discussions and
>> submitted a patch(
>> https://public-inbox.org/git/20231003174853.1732-1-ach.lumap@gmail.com/T/#t)
>> for review. I have received positive feedback on my contributions, and
>> it has been queued to be merged into official Git branches maintained
>> by Junio. Additionally, I have been involved in discussions related to
>> the git project.(https://public-inbox.org/git/CAFR+8DyN8vbuvdgZPkSVqS2=sqconwhx3QfcpJ0+Wi_oCA=s0w@mail.gmail.com/T/#t)
>>
>> **Proposal Drafts**:
>> I have shared drafts of this proposal on the Git mailing list
>> git@vger.kernel.org  and will incorporate valuable feedback provided
>> by the community.
>>
>> **Next Steps**:
>> I am eager to discuss my proposal further and collaborate with the Git
>> community to ensure the success of this project. I will continue to
>> engage with the community, seek guidance, and refine my proposal as
>> per your suggestions.
>>
>> Thank you for considering my application. I look forward to the
>> opportunity to contribute to the Git project and help make it even
>> more robust and reliable.
>>
>> Best Regards,
>>
>> On Wed, Oct 4, 2023 at 12:36 AM Luma <ach.lumap@gmail.com> wrote:
>> >
>> > oh yes, "Move existing tests to a unit testing framework" was the
>> > only listed project for this current Outreachy cohort. So, I used it
>> > to express my intent.
>> > I appreciate the clarification on authorship identity for patches. I
>> > will update subsequent patches with a legal full name to conform to
>> > the community rules.
>> >
>> > Regards.
>> >
>> > On Tue, Oct 3, 2023 at 7:51 PM Junio C Hamano <gitster@pobox.com> wrote:
>> > >
>> > > Luma <ach.lumap@gmail.com> writes:
>> > >
>> > > > Hi;
>> > > > My name is Luma, and  I wanted to take a moment to introduce myself
>> > > > and share some
>> > > > insights on an essential aspect of  avoiding pipes in git related
>> > > > commands in test scripts.
>> > > >
>> > > > I am an outreachy applicant for the December 2023 cohort and look
>> > > > forward to learning from you.
>> > >
>> > > I notice that the title of the message and the immediate topic you
>> > > discuss in the body of the message do not match.  I presume that the
>> > > topic on the title is what you prefer to work on if the unit testing
>> > > framework is ready by the time Outreachy program starts, and the
>> > > mention about "do not clobber exit code of Git with pipes in the
>> > > tests" is your "dip the tip of a toe in water" microproject?
>> > >
>> > > Welcome to the Git development community.
>> > >
>> > > Do you have a single word name?  If so please disregard the below,
>> > > but in case "Luma" is just a nickname (e.g. like I am introducing
>> > > myself to my Git friends "Hi, I am Gitster!") you use online, please
>> > > read on.
>> > >
>> > > For signing off your patches, we'd prefer to see your real name
>> > > used, as Signed-off-by: is meant to have legal significance.  And
>> > > because we also expect the authorship identity to match the
>> > > name/e-mail of the sign-off, it would mean your patch submissions
>> > > are expected to look like:
>> > >
>> > >         From: Luma <ach.lumap@gmail.com>
>> > >         Subject: ... title of the patch goes here ...
>> > >
>> > >         ... body of the proposed commit log message goes here...
>> > >
>> > >         Signed-off-by: Luma <ach.lumap@gmail.com>
>> > >
>> > > but "Luma" replaced with your full real name.
>> > >
>> > > Thanks.

Re: [Outreachy] Move existing tests to a unit testing framework

[Christian Couder]

On Fri, Oct 20, 2023 at 3:16 PM Achu Luma <ach.lumap@gmail.com> wrote:
>
> Dear Git Community and Mentors,
>
> I hope this email finds you well. As a follow-up to my previous application, I'd like to provide additional details on the process of migrating existing unit tests from the t/helper/ directory to the new Git unit test framework.

Thanks for these details!

> -- Identify Target Unit Tests: Start by identifying the specific unit tests in the t/helper/ directory that we want to port to the new Git unit test framework. Ensure that the tests are suitable for migration and that the benefits of doing so outweigh the effort(By avoiding integration tests). The following points have been developed with on going work on the unit-tests framework visible here:
>
> 1- https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/
> 2- https://github.com/steadmon/git/blob/unit-tests-asciidoc/Documentation/technical/unit-tests.adoc

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.

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.

> -- 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?

> --  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.

> -- 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.

> -- Ensure TAP Format Output: Ensure that the C-based tests produce output in the Test Anything Protocol (TAP) format. This format includes the test name, status (ok or not ok), and any diagnostic information.

That means using TEST* macros in the cmd_main() function, as they
should do the right thing or is there more to be done here?

> -- Test Interaction: Ensure that the migrated tests interact correctly with the new Git unit test framework and any other tests that may be relevant. Consider dependencies and interactions with other parts of the Git project.

I am not sure what work would be needed here. Is there more to do than
compiling the test files? Having an example would be nice.

> -- Test Execution: Run the migrated tests to verify that they produce the expected results when executed as part of the Git project's test suite. Use the Git testing framework's test runners to execute the tests.

Ok.

> -- Documentation Update: Update the Git project's documentation to reflect the changes made during the migration. Include a reference to the original unit tests in the t/helper/ directory and indicate that these tests have been ported to the new Git unit test framework.

I am not sure that we would want that. I think we might instead want
to document things in t/helper/ that we don't want to port to the new
unit test framework and why.

> By following these points, I think I can successfully port existing unit tests from the t/helper/ directory to use the new Git unit test framework. This migration helps standardize and streamline the testing process within the Git project, improving code quality and maintainability.

Yeah!

> Next Steps:
>
> I am eager to discuss these suggestions and collaborate with the Git community to ensure the success of this project. I will continue to engage with the community, seek guidance, and refine my proposal as per your suggestions.
>  I look forward to the opportunity to contribute to the Git project and help make it even more robust and reliable.

Thanks for this application and sorry for the late answer!

Best,
Christian.

Re: [Outreachy] Move existing tests to a unit testing framework

[Achu Luma]

On Mon, Oct 23, 2023 at 2:41 PM Christian Couder
<christian.couder@gmail.com> wrote:
>
> On Fri, Oct 20, 2023 at 3:16 PM Achu Luma <ach.lumap@gmail.com> wrote:
> >
> > Dear Git Community and Mentors,
> >
> > I hope this email finds you well. As a follow-up to my previous application, I'd like to provide additional details on the process of migrating existing unit tests from the t/helper/ directory to the new Git unit test framework.
>
> Thanks for these details!
>
> > -- Identify Target Unit Tests: Start by identifying the specific unit tests in the t/helper/ directory that we want to port to the new Git unit test framework. Ensure that the tests are suitable for migration and that the benefits of doing so outweigh the effort(By avoiding integration tests). The following points have been developed with on going work on the unit-tests framework visible here:
> >
> > 1- https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/
> > 2- https://github.com/steadmon/git/blob/unit-tests-asciidoc/Documentation/technical/unit-tests.adoc
>
> 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@google.com/
:
    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.

> 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.
> > -- 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.
> > --  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);
    }
}
--

> > -- 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
--
> > -- Ensure TAP Format Output: Ensure that the C-based tests produce output in the Test Anything Protocol (TAP) format. This format includes the test name, status (ok or not ok), and any diagnostic information.
>
> That means using TEST* macros in the cmd_main() function, as they
> should do the right thing or is there more to be done here?
>
> > -- Test Interaction: Ensure that the migrated tests interact correctly with the new Git unit test framework and any other tests that may be relevant. Consider dependencies and interactions with other parts of the Git project.
>
> I am not sure what work would be needed here. Is there more to do than
> compiling the test files? Having an example would be nice.
>
> > -- Test Execution: Run the migrated tests to verify that they produce the expected results when executed as part of the Git project's test suite. Use the Git testing framework's test runners to execute the tests.
>
> Ok.
>
> > -- Documentation Update: Update the Git project's documentation to reflect the changes made during the migration. Include a reference to the original unit tests in the t/helper/ directory and indicate that these tests have been ported to the new Git unit test framework.
>
> I am not sure that we would want that. I think we might instead want
> to document things in t/helper/ that we don't want to port to the new
> unit test framework and why.
>
Ok noted.
> > By following these points, I think I can successfully port existing unit tests from the t/helper/ directory to use the new Git unit test framework. This migration helps standardize and streamline the testing process within the Git project, improving code quality and maintainability.
>
> Yeah!
>
> > Next Steps:
> >
> > I am eager to discuss these suggestions and collaborate with the Git community to ensure the success of this project. I will continue to engage with the community, seek guidance, and refine my proposal as per your suggestions.
> >  I look forward to the opportunity to contribute to the Git project and help make it even more robust and reliable.
>
> Thanks for this application and sorry for the late answer!
>
> Best,
> Christian.

I look forward to feedback and better understanding of the new testing
framework.

BR,
Achu Luma.

Re: [Outreachy] Move existing tests to a unit testing framework

[Christian Couder]

On Tue, Oct 24, 2023 at 4:25 PM Achu Luma <ach.lumap@gmail.com> wrote:
>
> On Mon, Oct 23, 2023 at 2:41 PM Christian Couder
> <christian.couder@gmail.com> 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@google.com/
> :
>     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.