Grant Proposal: Test::Stream Manual
Mon, 16-Nov-2015 by
Makoto Nozaki
edit post
<.
- Test Tool (Plugin) Authors
This section of the manual will cover people who want to write new tools or
plugins that use Test::Stream under the hood. This is probably the most
important audience as it will be necessary if tools are going to be compatible
with each other.
This has been started and can be seen on cpan:
[Test::Stream::Manual::Tooling](https://metacpan.org/pod/Test::Stream::Manual::Tooling).
- Test::Stream Maintainers
This section of the manual will cover people who wish to participate in
Test::Stream development directly. This is important to reduce the bus factor
(which is very close to 1 currently).
This has been started and can be seen on cpan:
[Test::Stream::Manual::Components](https://metacpan.org/pod/Test::Stream::Manual::Components).
## Inch-stones
For test authors:
- Introduction to testing
Introduction to testing using Test::Stream, for beginners. This will cover
planning and simple uses of the `ok()` function.
- Migrating from Test::More (written, but needs refining)
Conversion notes and examples for people moving from Test::More. This will
detail how tools might have changed, what tools are gone, and introduce some
new or replacement tools.
- Core test tools
Introduction to the core/essential tools in Test::Stream. This covers the tools
in the [Test::Stream::Plugin::Core](https://metacpan.org/pod/Test::Stream::Plugin::Core) plugin.
- Custom inline tools
Simple example of writing test functions that wrap around existing ones. This
is done frequently and early enough to justify a beginner page for it.
- Comparison testing
Test::Stream comes with rich tools for comparing data structures. This tool is
big, and should get 2 manual pages. This manual page will cover basic usage.
- Advanced comparisons
This section would over advanced comparison tool usage. This section will
contain recipes and examples. It will also include details on writing custom
comparisons.
- Test::Stream plugins
Overview of all included plugins, including descriptions and basic usage.
- Third party plugins
Place to list notable third party plugins as they are written.
For test tool authors:
- Simple OK plugin
This is the most basic tool you can write, and is valuable for explaining the
key concepts universal to all Test::Stream tools.
- Writing tests for your test tools
This covers [Test::Stream::Plugin::Intercept](https://metacpan.org/pod/Test::Stream::Plugin::Intercept) and how to use it to effectively
and safely test your test tools.
- Advanced Plugins
This covers advanced plugin design, custom import methods, etc.
- Bundles
How to write a bundle.
- The 'Context' object and API
Explain what the context object is, why it is important, and how to use it
effectively.
- The 'Hub' object and API
Explanation of the hub objects and how they work.
- Custom Hubs
How to write a hub subclass (essential for Subtest like tools).
- The 'Sync' package and API
What is tracked by the Sync package, and how to use it properly.
- Custom event types
How to write an event.
- Custom output formatters
How to write an output formatter.
- Custom Test::Stream loaders
How to write a loader.
- Building workflows
How to write workflows for the workflow library.
- Writing IPC drivers
How to write a custom IPC Driver.
For Test::Stream maintainers:
- Component map (written, but needs refining)
Map of all Test::Stream components.
- Basic building blocks
Explanation of low-level infrastructure such as Test::Stream::Exporter,
Test::Stream::HashBase, etc.
- How the 'Context' works
Detailed overview of the Context object, and implementation details.
- How the Sync package works
Detailed overview of the shared state that lives in the Sync package.
- Managing state
The state object, pass/fail logic, etc.
- The hub stack
What the hub stack is, and why it is important.
- Comparison library
Details on the guts of the comparison library.
- Workflow library
Details on the guts of the workflow library.
- The IPC system internals
How IPC works, and more importantly how it can fail.
- Utilities
The utilities library, and important implementation details.
- Performance Notes
Key information about where changes can severely impact performance.
## Project Schedule
I can start as soon as the grant is approved. The work will be done on free
evenings and weekends as time allows. This work can be done in parallel with,
or after my other grant proposal. This proposal should not come first as the
other grant proposal may result in significant changes to what goes into the
manual.
## Completeness Criteria
The manual will be included in a Test::Stream release on cpan. The manual will
have all 3 expected sections, with no significant gaps or TODO sections.
## Bio
My name is Chad Granum. I am known as Exodist on CPAN. I have spent several
years writing Perl for work and for fun. For most of my time in Perl I've
specialized in unit testing tools. [Fennec](https://metacpan.org/pod/Fennec) is a good example of my previous
work.
In January of 2014 Michael Schwern transferred the Test-Simple dist and all of
its components to me. He felt I was the best person to carry the project
forward. Since then I have reached out to the rest of the community to be sure
I was carrying the project forward in the best interests of all.
]]>
Comments (4)
I'm a bit unsure of the assertion that this should not come first. Writing documentation often exposes problems with teachability or usability that can be addressed by making changes to the code.
On the other hand, the code has already been extensively tested, and changes to based on downstream breakage would, I think, be pretty minimal.
What kind of changes do you imagine occurring during the work of the other grant that would render the documentation significantly obsolete?
All the modules already have documentation. So I think the issues that can be exposed with documentation have largely been uncovered. What is left is tying the parts together in a tutorial and cookbook style. Ie you want to do X, look here for a complete guide. Right now the module docs are good reference, but there is not a lot tying each component together for someone completely new.
A good example of things that will change includes a current discussion and pull request. Currently event objects have a to_tap method. A manual would detail writing a new event, and would say to implement to_tap to control its TAP output. However in discussion it has become clear that the event to tap logic should live directly in the formatter. This would be a significant change to the manual if it had already been written.
TPF now has a history of sponsoring documentation manuals: Perlbal and RPerl (more?).
Having a documentation manual for the core piece of what should be the next testing framework for CPAN modules falls within the "quite darn useful" category. :)
This is too early. There are to many areas where things may still change IMO.
