Upgrade Notice

The CPAN Testers Wiki site has been upgraded since you last accessed the site. Please press the F5 key or CTRL-R to refresh your browser cache to use the latest javascript and CSS files.

Quick Start for CPAN Testers

There are three steps to start using CPAN Testers:

  • Installing test reporting tools
  • Creating a CT 2.0 profile
  • Enabling reporting in CPAN clients

Even if you don't plan to run automated "smoke" tests, but just want to send reports when you happen to install modules from CPAN, you must complete all three steps.

If you plan to do automated smoke testing, these steps will ensure that you can send reports to the CPAN Testers server and you will need to look at other articles on this wiki for information on configuring automated testing. See the "What Next" section at the bottom of this document for more.

Installing Test Reporting Tools

Each CPAN client use a different tool for sending reports.

CPAN.pm (the 'cpan' command) uses CPAN Reporter. CPANPLUS uses its own.

If you have not yet installed CPANPLUS or are a first-time tester or don't plan to run an automated smoke testing machine, start with CPAN::Reporter. Or, if you do plan to run an automated smoke testing machine, then we recommend you start with CPANPLUS.

Depending on which tool you choose, you will need to install or upgrade the following distributions to the versions listed below:

Using CPAN::Reporter

The task will attempt to install Crypt::SSLeay. If that fails, try IO::Socket::SSL instead.

Using CPANPLUS

Creating a Profile

If you were not already sent a CT 2.0 profile file as part of the beta test, then you need to create a new profile.

Using CPAN::Reporter

If you plan to use CPAN::Reporter, create your profile with the 'metabase-profile' tool.

$ metabase-profile

Answer the prompts and copy or move the resulting metabase_id.json file to a ".cpantesters" directory under your home directory. The JSON file can actually be placed anywhere, just change the "id_file" parameter of the "transport" key in the configuration file; see below for details.

$ mkdir ~/.cpantesters
$ cp metabase_id.json ~/.cpantesters/
$ chmod 400 ~/.cpantesters/metabase_id.json

If you want to send test reports from multiple accounts or computers, just copy the profile file to a similar directory on each one. You should use the same profile for all reports that you send.

You have to put the metabase_id.json file in a path that does not have space or other special characters in it. On Windows c:\metabase_id.json is a good choice.

Using CPANPLUS

If you installed Task::CPANPLUS::Metabase, it comes with a helper script that will prompt you for information, generate your profile file, save it to a directory, and configure CPANPLUS as well:

$ metabase_cpanp

Your profile will be saved to the ~/.metabase directory (or to %APPDATA%\metabase on Windows).

If you did not install Task::CPANPLUS::Metabase or if you want to create your profile without configuring CPANPLUS automatically, follow the instructions above for generating a profile with CPAN::Reporter. You can save the profile to any directory you want, but note the location so you can configure things later.

Configuring Test Reporting Tools

The configuration depends on which tools you are using. You will need to hand-edit certain configuration files. Eventually, we hope to automate the configuration process more completely.

Using CPAN::Reporter

If you have never used CPAN::Reporter before you have to configure/reconfigure CPAN to enable CPAN::Reporter usage (see the CPAN::Reporter documentation for the latest information).

$ cpan
cpan> o conf init test_report
cpan> o conf commit
cpan> force test CPAN::Reporter
cpan> q

Check that 'cpan' created a file called ~/.cpanreporter/config.ini containing at least the following lines (but with your real email address):

email_from = youremail@example.com
transport = Metabase uri https://metabase.cpantesters.org/api/v1/ id_file ~/.cpantesters/metabase_id.json

The "email_from" line is redundant but required. Eventually, CPAN::Reporter will no longer need it.

If both IO::Socket::SSL and Crypt::SSLeay fail to install, you can use HTTP instead of HTTPS. However, that is not recommended, so please try your best to install either IO::Socket::SSL or Crypt::SSLeay. In modern versions of LWP you will also need to install LWP::Protocol::https

Remember to update the config.ini to include the path to metabase_id.json If you followed the suggestion and on Windows you put the file in c:\ then here put

transport = Metabase uri https://metabase.cpantesters.org/api/v1/ id_file c:/metabase_id.json

transport = Metabase uri https://metabase.cpantesters.org/api/v1/ id_file c:/metabase_id.json

Using CPANPLUS

If you used the 'metabase_cpanp' script to generate your profile, then it already configured CPANPLUS for you and you're done.

If you did not use 'metabase_cpanp', then you need to make the following changes to your CPANPLUS configuration.

In "~/.cpanplus/lib/CPANPLUS/Config/User.pm" add the following lines:

cpantest_reporter_args => {
  transport => 'Metabase',
  transport_args  => [
    uri => "https://metabase.cpantesters.org/api/v1/",
    id_file => "~/.cpantesters/metabase_id.json"
  ],
}

Be sure to set the 'id_file' parameter to the location of your profile file.

Then, you need to enable CPAN Testers reporting from within CPANPLUS:

$ cpanp
CPAN Terminal> s conf cpantest 1
CPAN Terminal> s save

Try it out!

Using either CPAN (with CPAN::Reporter) or CPANPLUS, try testing a module on CPAN. You should see messages on screen after tests are run that show that the report has been sent.

After a while, your report will show up in the CT 2.0 log tail. (This tail file is refreshed every 5 minutes or so.) Eventually, your report will make it to the main CPAN Testers web site.

If you don't see your report in the log tail after 10 minutes, please email cpan-testers-discuss@perl.org or inquire in #cpantesters-discuss on irc.perl.org for assistance.

What Next?

If you followed the steps above and have successfully sent reports to the new CPAN Testers 2.0 server, you may wish to explore automated testing or other advanced configuration.

Automated Testing

Sending test reports for the modules you personally install, helps you directly by giving valuable information to the authors to help them improve quality and portability of the modules you currently use.

Taking the next step to automated testing helps many more people by testing many more modules on your system, including modules you are likely to install in the future.

If you plan to automate your testing, you will want to investigate either CPAN-Reporter-Smoker if you're using CPAN::Reporter, or CPANPLUS-YACSmoke if you're using CPANPLUS. See the SmokeTools page for more instructions for automated smoking.

Advanced configurations

If you are planning to send reports from several different machines or environments, or need to conduct tests offline, then you may wish to investigate using Metabase-Relayd or Bingos's blog.

Further Information

For more detailed setup instructions see CPANReporterSmokerLong