parser: Add KTAP parser for handling kernel selftests

This patch introduces a dedicated parser for Linux kernel selftests using
the KTAP (Kernel Test Anything Protocol) format.

While KTAP is based on the TAP (Test Anything Protocol) standard, it includes
significant extensions tailored for kernel testing. This parser builds on
TAP::Parser to handle common TAP elements while providing additional logic
to interpret KTAP-specific constructs such as grouped subtests and prefixed
comment lines.

For more details on KTAP, see: https://docs.kernel.org/dev-tools/ktap.html

Example output of the ktap test run:

  TAP version 13
  1..13
  # overriding timeout to 300
  # selftests: cgroup: test_core
  # ok 1 test_cgcore_internal_process_constraint
  # ok 2 test_cgcore_top_down_constraint_enable
  # ok 3 test_cgcore_top_down_constraint_disable
  # ok 4 test_cgcore_no_internal_process_constraint_on_threads
  # ok 5 test_cgcore_parent_becomes_threaded
  # ok 6 test_cgcore_invalid_domain
  # ok 7 test_cgcore_populated
  # ok 8 test_cgcore_proc_migration
  # ok 9 test_cgcore_thread_migration
  # ok 10 test_cgcore_destroy
  # ok 11 test_cgcore_lesser_euid_open
  # ok 12 test_cgcore_lesser_ns_open
  ok 1 selftests: cgroup: test_core

There are group of tests with nested subtests. Each group starts as
follow:

  # selftests: cgroup: test_cpu

After that individual tests are listed with results ok | not ok:

  # ok 1 test_cgcore_internal_process_constraint

however such subtests are prepended with # which - from the TAP
specification standpoint - are just comments. Moreover KTAP allows
for more comments like:

  # overriding timeout to 300

Each group of tests ends with:

  ok 2 selftests: cgroup: test_cpu

or

  not ok 10 selftests: cgroup: test_zswap # exit=1

The KTAP parser uses TAP::Parser to re-use all generic TAP functions
however extends those to handle KTAP specifics. The KTAP parser correctly
identifies these groups and subtests, associates results appropriately,
and exports them in a structured format compatible with OpenQA.

Author: schlad

lib/OpenQA/Parser/Format/KTAP.pm

@@ -0,0 +1,213 @@
+# Copyright 2025 SUSE LLC
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+package OpenQA::Parser::Format::KTAP;
+use Mojo::Base 'OpenQA::Parser::Format::Base';
+
+# Translates KTAP kernel selftests format -> OpenQA internal representation
+use Carp qw(croak confess);
+use OpenQA::Parser::Result::OpenQA;
+use TAP::Parser;
+
+has [qw(test steps)];
+
+sub _is_tap {
+    my ($raw) = @_;
+    my $tap = TAP::Parser->new({ tap => $raw });
+    confess 'KTAP parse error: ' . $tap->parse_errors if $tap->parse_errors;
+
+    while (my $result = $tap->next) {
+        return $result->version if $result->type eq 'version';
+    }
+
+    return undef;
+}
+
+sub _testgroup_init {
+    my ($self, $line, $test_ref, $steps_ref, $m_ref) = @_;
+
+    if ($$steps_ref && $self->test) {
+        $$steps_ref->{name} = $self->test->{name};
+        $$steps_ref->{test} = $self->test;
+        $self->generated_tests_results->add(OpenQA::Parser::Result::OpenQA->new($$steps_ref));
+    }
+
+    my ($group_name) = $line =~ /^#\s*selftests:\s+(.*)/;
+    my $sanitized_group_name = "selftests: $group_name";
+    $sanitized_group_name =~ s/[\/.]/_/g;
+
+    $$test_ref = {
+        flags    => {},
+        category => 'KTAP',
+        name     => $sanitized_group_name,
+    };
+
+    $self->test(OpenQA::Parser::Result->new($$test_ref));
+    $self->_add_test($self->test);
+
+    $$steps_ref = OpenQA::Parser::Result->new({
+        details => [],
+        dents   => 0,
+        result  => 'passed'
+    });
+
+    $$m_ref = 0;
+}
+
+sub _parse_subtest {
+    my ($self, $result, $test_ref, $steps_ref, $m_ref) = @_;
+    return unless $$steps_ref && $self->test;
+
+    my $line = $result->as_string;
+    return unless $line =~ /^#\s*(ok|not ok)\s+\d+\s+(.+)/;
+
+    my ($status, $subtest_name) = ($1, $2);
+    my $filename = "KTAP-@{[$$test_ref->{name}]}-$$m_ref.txt";
+
+    push @{ $$steps_ref->{details} }, {
+        text   => $filename,
+        title  => $subtest_name,
+        result => $status eq 'ok' ? 'ok' : 'fail',
+    };
+
+    $$steps_ref->{result} = 'fail' if $status ne 'ok';
+
+    $self->_add_output({file => $filename, content => $line});
+    $$m_ref++;
+}
+
+sub _testgroup_finalize {
+    my ($self, $steps_ref, $result) = @_;
+    return unless $$steps_ref && $self->test;
+
+    my $line = $result ? $result->as_string : '';
+    my $group_failed = 0; #it is possible the subtests do not report 'not ok' but only the group
+
+    if ($line =~ /^not ok\b/i) {
+        $$steps_ref->{result} = 'fail';
+        $group_failed = 1;
+    }
+    elsif ($line =~ /#\s*SKIP\b/i) {
+        $$steps_ref->{result} = 'skip';
+    }
+
+    $$steps_ref->{name}  = $self->test->{name};
+    $$steps_ref->{test}  = $self->test;
+
+    $self->generated_tests_results->add(OpenQA::Parser::Result::OpenQA->new($$steps_ref));
+
+    #clear the group
+    $self->test(undef);
+    #clewr the subtests
+    $$steps_ref = undef;
+}
+
+sub parse {
+    my ($self, $KTAP) = @_;
+    confess 'No KTAP given/loaded' unless $KTAP;
+
+    _is_tap($KTAP);
+
+    my $parser = TAP::Parser->new({ tap => $KTAP });
+    my ($test, $steps, $m) = ({}, undef, 0);
+
+    while (my $result = $parser->next) {
+
+        next if $result->type eq 'version' || $result->type eq 'plan';
+
+        if ($result->type eq 'comment' && $result->as_string =~ /^#\s*selftests:\s+(.*)/) {
+            $self->_testgroup_init($result->as_string, \$test, \$steps, \$m);
+            next;
+        }
+
+        if ($result->type eq 'comment' && $result->as_string =~ /^#\s*(ok|not ok)\s+\d+\s+(.+)/) {
+            $self->_parse_subtest($result, \$test, \$steps, \$m);
+            next;
+        }
+
+        if ($result->type eq 'test' && $result->description =~ /^selftests: /) {
+            $self->_testgroup_finalize(\$steps, $result);
+            next;
+        }
+    }
+
+    if ($steps && $self->test) {
+        $steps->{name} = $self->test->{name};
+        $steps->{test} = $self->test;
+        $self->generated_tests_results->add(OpenQA::Parser::Result::OpenQA->new($steps));
+    }
+}
+
+=head1 NAME
+
+OpenQA::Parser::Format::KTAP - KTAP file parser
+
+=head1 SYNOPSIS
+
+    use OpenQA::Parser::Format::KTAP;
+
+    my $parser = OpenQA::Parser::Format::KTAP->new()->load('test.tap');
+
+    # Alternative interface
+    use OpenQA::Parser qw(parser p);
+
+    my $parser = p( KTAP => 'test.tap' );
+
+    my $result_collection = $parser->results();
+    my $test_collection   = $parser->tests();
+    my $output_collection = $parser->output();
+
+    my $arrayref = $result_collection->to_array;
+
+    $parser->results->remove(0);
+
+    my $passed_results = $parser->results->search( result => qr/ok/ );
+    my $size = $passed_results->size;
+
+=head1 DESCRIPTION
+
+B<OpenQA::Parser::Format::KTAP> parses Linux kernel selftests written in KTAP (Kernel Test Anything Protocol),
+which extends TAP with structured subtests and test groups.
+The parser is making use of the C<tests()>, C<results()> and C<output()> collections.
+
+This parser extracts:
+- Test groups (`selftests: ...`)
+- Subtest results (`# ok ...`, `# not ok ...`)
+- Final group summary lines (`ok N selftests: ...`)
+
+It populates internal result structures that can later be queried using standard OpenQA::Parser accessors.
+
+=head1 ATTRIBUTES
+
+Inherits from L<OpenQA::Parser::Format::Base>. Additional attributes include:
+
+=head2 test
+
+An instance of L<OpenQA::Parser::Result> representing the current test group being parsed.
+
+=head2 steps
+
+A temporary result object accumulating the individual subtest results for the current test group.
+
+=head1 METHODS
+
+=head2 _is_tap($raw)
+
+Internal helper that checks whether the given content is valid TAP/KTAP and extracts version if found.
+Throws an exception on invalid TAP.
+
+=head2 _testgroup_init($line, $test_ref, $steps_ref, $m_ref)
+
+Initializes a new test group when a C<# selftests: groupname> comment is encountered.
+
+=head2 _parse_subtest($result, $test_ref, $steps_ref, $m_ref)
+
+Parses a subtest line of the form C<# ok 1 testname> and appends the result to the current steps.
+
+=head2 _testgroup_finalize($steps_ref)
+
+Finalizes the current test group and stores the accumulated results.
+
+=cut
+
+1;