Test2 Manual Completion Report

No Comments

Follows the report by Chad Granum (aka EXODIST) for his grant: Test2 Manual.

Test2 Manual grant complete

This is a completion report for the Test2 manual grant.


  • Test2::Manual

    Original description:

    A brief introduction and table of contents.

    Completed form:

    Jumping off point with a map of the manual layout/table of contents.
  • Test2::Manual::Tooling

    Original description:

    This section will cover writing test tools. This would be a root document
    with several other page links.

    Complete form:

    The tooling page is the portal to all tooling tutorials. This section
    covers writing test tools.
  • Test2::Manual::Maintenance / Test2::Manual::Anatomy

    Original Description:

    This section will cover maintaining Test2 itself. This will be a root
    document pointing to pages that explain the internals, and how they work

    Final Form:

    I renamed this section to Test2::Tools::Anatomy. This section covers docs
    about Test2 internals and implementation details. This section is more
    complete and useful than I originally intended.

Completeness Criteria

Original criteria section from my proposal:

The manual will be included in a Test2 release on cpan. The manual will
have all expected sections, with no significant gaps or TODO sections.

Test2::Manual, with all the specified sections is now included in the Test2-Suite distribution on cpan. There are no TODO's or gaps in the sections that were part of my proposal, though there are TODO's in a third section that went beyond the scope of my grant.

The version with the complete manual is Test2-Suite-0.000114.

Bonus Material

I went beyond the scope of my original grant report and added the Test2::Manual::Testing section. This section is still incomplete, but was not part of my original grant proposal anyway, as such all the content that is complete is a nice bonus.

I also added the Test2::Manual::Concurrency and Test2::Manual::Contributing pages.

Revisiting the inch-stones

  • Migrating from Test::Builder


    Conversion notes and examples for people moving from Test::Builder. This
    will detail how tools might have changed, what is gone, and introduce some
    new or replacement concepts.

    This is done as Test2::Manual::Tooling::TestBuilder.

  • Simple OK tool


    This is the most basic tool you can write, and is valuable for explaining
    the key concepts universal to all Test2 tools.

    This section is complete, Test2::Manual::Tooling::FirstTool.

  • The Test2 API


    This covers Test2::API, and all the functionality it exposes.

    This was not done as a single section. Instead there are handful of tutorials which show how to use some of the most common API functions.

  • The 'Context' object


    Explain what the context object is, why it is important, and how to use it

    This did not need its own section. The Test2::Manual::Tooling::FirstTool covers all the important points about the context object from a tool writers perspective. Everything else is covered by the Test2::Manual::Anatomy::Context document.

  • The 'Hub' object and API


    Explanation of the hub objects and how they work.

    This section is not necessary. Tool developers no longer need to directly interact with hubs. The things that would have been covered here are now part of the context and API pages.

  • Custom Hubs


    How to write a hub subclass (essential for Subtest like tools).

    I decided not to write this section. A custom hub should rarely if ever be needed from the perspective of someone writing a new tool. The Test2::Manual::Tooling::Subtests covers the documentation I was going to write related to subtest like tools.

  • Custom event types


    How to write an event.

    The event API underwent a major rewrite since my grant proposal, custom event types are now discouraged, as such this is not a necessary section.

  • Custom output formatters


    How to write an output formatter.

    This section was completed as Test2::Manual::Tooling::Formatter.

  • Writing IPC drivers


    How to write a custom IPC Driver.

    This section is not necessary, writing a custom IPC driver is not something to undertake lightly, and is not something a normal tool author needs to know about.

  • Component map


    Map of all Test2 components.

    This is complete as Test2::Manual::Anatomy::EndToEnd. This is a more useful page than the originally specified one would ahve been.

  • Basic building blocks


    Explanation of low-level infrastructure such as Test2::Util::HashBase.

    There is no building blocks page, instead there are pages for specific building blocks.

  • How the 'Context' works


    Detailed overview of the Context object, and implementation details.

    This was done as Test2::Manual::Anatomy::Context.

  • The hub stack


    What the hub stack is, and why it is important.

    This is done as Test2::Manual::Anatomy::Hubs.

  • The IPC system internals


    How IPC works, and more importantly how it can fail.

    This is complete as Test2::Manual::Anatomy::IPC, except the failures of the IPC system have been reduced and handled better making the "how it can fail" component unnecessary.

  • Utilities


    The utilities library, and important implementation details.

    Done as Test2::Manual::Anatomy::Utilities.

  • Performance Notes

    Test2 is now faster than Test::Builder making this section unnecessary.

Leave a comment

About TPF

The Perl Foundation - supporting the Perl community since 2000. Find out more at www.perlfoundation.org.

About this Entry

This page contains a single entry by Alberto Simões published on April 24, 2018 5:11 PM.

Grant Report : Complete YAML::PP - March 2018 was the previous entry in this blog.

The Perl Conference Newsletter: 04/26/2018 is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.


OpenID accepted here Learn more about OpenID
Powered by Movable Type 6.2.2