/ 
Test-CPAN-Health-0.1.0
/ Test::CPAN::Health::Check::CPANTesters

NAME

Test::CPAN::Health::Check::CPANTesters - Check CPAN Testers pass/fail ratio

SYNOPSIS

use Test::CPAN::Health::Check::CPANTesters;

my $check  = Test::CPAN::Health::Check::CPANTesters->new;
my $result = $check->run($dist);

DESCRIPTION

Fetches test statistics for the distribution's latest CPAN release via the MetaCPAN release search API (which embeds aggregated CPAN Testers data).

Score = int(pass / (pass + fail) * 100). na and unknown results are not counted in the denominator so that untested platforms do not artificially lower the score.

A fail status from this check triggers a hard cap on the overall Report score at 75 (applied by Test::CPAN::Health::Report).

LIMITATIONS

  • The check can only run against a distribution that has been released to CPAN and indexed by MetaCPAN. Unreleased local distributions will be skipped.

  • CPAN Testers data in MetaCPAN may lag a few days behind the live CPAN Testers database.

  • Only pass and fail grades are used; na (platform not applicable) and unknown (incomplete reports) are excluded from the denominator.

run

PURPOSE

Fetch the CPAN Testers statistics for the latest release of this distribution and compute a pass-rate score.

API SPECIFICATION

INPUT

dist     Test::CPAN::Health::Distribution  required
context  Hashref                           optional

OUTPUT

Test::CPAN::Health::Result with check_id 'cpan_testers'.

MESSAGES

Code  | Severity | Message                                    | Resolution
------+----------+--------------------------------------------+-----------
CT001 | SKIP     | Network checks disabled                    | Remove --no-network
CT002 | SKIP     | Distribution name not available            | Add META.yml
CT003 | SKIP     | Distribution not found on MetaCPAN         | Release to CPAN first
CT004 | SKIP     | No CPAN Testers data available yet         | Wait for smoke reports
CT005 | ERROR    | MetaCPAN API error: ...                    | Transient; retry
CT006 | PASS     | CPAN Testers: N pass, M fail (P%)          |
CT007 | WARN     | CPAN Testers: N pass, M fail (P%)          | Investigate failures
CT008 | FAIL     | CPAN Testers: N pass, M fail (P%)          | Fix failing platforms

FORMAL SPECIFICATION

-- Z schema (placeholder) --
CPANTestersOp
pass   : N
fail   : N
score  : 0..100
-------------------------------------------------------
no_network          => status = skip
dist_name = undef   => status = skip
not on MetaCPAN     => status = skip
pass + fail = 0     => status = skip (no data)
score >= 80         => status = pass
score >= 60         => status = warn
score < 60          => status = fail  (Report hard-caps at 75)

SIDE EFFECTS

Makes one HTTPS POST request to fastapi.metacpan.org.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::CPANTesters->new->run($dist);
printf "Pass rate: %d%%\n", $result->score;

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENSE AND COPYRIGHT

Copyright (C) 2025-2026 Nigel Horne.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.