NAME

DESCRIPTION

SYNOPSIS

    package Test2::Harness::Runner::Resource::Foo;
    use strict;
    use warnings;

    use parent 'Test2::Harness::Runner::Resource';

    sub setup {
        my $class = shift; # NOT AN INSTANCE
        ...
    }

    sub available {
        my $self = shift;
        my ($task) = @_;

        # There are an infinite amount of integers, so we always return true
        return 1;
    }

    sub assign {
        my $self = shift;
        my ($task, $state) = @_;

        # Next ID, do not record the state change yet!
        my $id = 1 + ($self->{ID} //= 0);

        print "ASSIGN: $id = $task->{job_id}\n";

        # 'record' should get whatever we need to record the resource, whatever you
        # pass in will become the argument to the record() sub below. This may be a
        # scalar, a hash, an array, etc. It will be serialized to JSON before
        # record() sees it.
        $state->{record} = $id;

        # Pass the resource into the test, this can be done as envronment variables
        # and/or arguments to the test (@ARGV).
        $state->{env_vars}->{FOO_ID} = $id;
        push @{$state->{args}} => $id;

        # The return is ignored.
        return;
    }

    sub record {
        my $self = shift;
        my ($job_id, $record_arg_from_assign) = @_;

        # The ID from $state->{record}->{$pkg} in assign.
        my $id = $record_arg_from_assign;

        # Update our internal state to reflect the new ID.
        $self->{ID} = $id;

        # Add a mapping of what job ID gets what integer ID.
        $self->{ID_TO_JOB_ID}->{$id}     = $job_id;
        $self->{JOB_ID_TO_ID}->{$job_id} = $id;

        print "RECORD: $id = $job_id\n";

        # The return is ignored
    }

    sub tick {
        my $self = shift;

        # This is called by only 1 process at a time and gives you a way to do
        # extra stuff at a regular interval without other processes trying to
        # do the same work at the same time.
        # For example, if a database is left in a dirty state after it is
        # released, you can fire off a cleanup action here knowing no other
        # process will run it at the same time. You can also be sure no record
        # messages will be sent while this sub is running as the process it
        # runs in has a lock.

        ...
    }


    sub release {
        my $self = shift;
        my ($job_id) = @_;

        # Clear the internal mapping, the integer ID is now free. Theoretically it
        # can be reused, but this example is not that complex.
        my $id = delete $self->{JOB_ID_TO_ID}->{$job_id};

        # This is called for all tests that complete, even if they did not use
        # this resource, so we return if the job_id is not applicable.
        return unless defined $id;

        delete $self->{ID_TO_JOB_ID}->{$id};

        print "  FREE: $id = $job_id\n";

        # The return is ignored
    }

    sub cleanup {
        my $self = shift;

        print "CLEANUP!\n";
    }

    1;

The print statements generated will look like this when running 2 tests concurrently:

    yath test -R Foo -j2 t/testA.t t/testB.t
    [...]
    (INTERNAL)     ASSIGN: 1 = 4F7CF5F6-E43F-11EA-9199-24FCBF610F44
    (INTERNAL)     RECORD: 1 = 4F7CF5F6-E43F-11EA-9199-24FCBF610F44
    (INTERNAL)     ASSIGN: 2 = E19CD98C-E436-11EA-8469-8DF0BF610F44
    (INTERNAL)     RECORD: 2 = E19CD98C-E436-11EA-8469-8DF0BF610F44
    (INTERNAL)       FREE: 1 = 4F7CF5F6-E43F-11EA-9199-24FCBF610F44
    (INTERNAL)       FREE: 2 = E19CD98C-E436-11EA-8469-8DF0BF610F44
    (INTERNAL)     CLEANUP!
    [...]

Depending on the tests run the 'FREE' prints may be out of order.

WORKFLOW

METHODS

$class->setup($settings)

This will be called once before the runner forks or initialized per-process instances. If you have any "setup once" tasks to initialize resources before tests run this is a good place to do it.

This runs immedietly after plugin setup() methods are called.

NOTE: Do not rely on recording any global state here, the runner and per-process instances may not be forked from the process that calls setup().

$res = $class->new(settings => $settings);

A default new method, returns a blessed hashref with the settings key set to the Test2::Harness::Settings instance.

$val = $res->available(\%task)

DO NOT MODIFY ANY INTERNAL STATE IN THIS METHOD

DO NOT MODIFY THE TASK HASHREF

Returns a positive true value if the resource is available.

Returns false if the resource is not available, but will be in the future (IE in use by another test, but will be free when that test is done).

Returns a negative value if the resource is not available and never will be. This will cause any tests dependent on the resource to be skipped.

The only key in "\%task" hashref that most resources will care about is the 'file' key, which contains the test file to be run.

$res->assign(\%task, \%state)

DO NOT MODIFY THE TASK HASHREF

DO NOT MODIFY ANY INTERNAL STATE IN THIS METHOD

If the task does not need any resources you may simply return.

If resources are needed you should deduce what resources to assign.

You should put any data needed to update the internal state of your resource instance in the "$state->{record}" hash key. It WILL be serialized to JSON before being used as an argument to "record()".

    $state->{record} = $id;
    

If you do not set the 'record' key, or set it to undef, then the "record()" method will not be called.

If your tests need to know what resources to use, you may set environment variables and/or command line arguments to pass into the test (@ARGV).

    $state->{env_vars}->{FOO_ID} = $id;
    push @{$state->{args}} => $id;
    

The "\%state" hashref is used only by your instance, you are free to fully replace the 'env_vars' and 'args' keys. They will eventually be merged into a master state along with those of other resources, but this ref is exclusive to you in this method.

$inst->record($job_id, $record_arg_from_assign)

NOTE: THIS MAY BE CALLED IN MUTLIPLE PROCESSES CONCURRENTLY.

This will be called in all processes so that your instance can update any internal state.

The $job_id variable contains the id for the job to which the resource was assigned. You should use this to record any internal state. The $job_id will be passed to "release()" when the job completes and no longer needs the resource.

This is intended only for modifying internal state, you should not do anything in this sub that will explode if it is also done in another process at the same time with the same arguments. For example creating a database should not be done here, multiple processes will fight to do the create. The creation, if necessary should be done in "assign()" which will be called in only one process.

$inst->release($job_id)

NOTE: THIS MAY BE CALLED IN MUTLIPLE PROCESSES CONCURRENTLY.

This will be called for every test job that completes, even if it did not use this resource. If the job_id did not use the resource you may simply return, otherwise update the internal state to reflect that the resource is no longer in use.

This is intended only for modifying internal state, you should not do anything in this sub that will explode if it is also done in another process at the same time with the same arguments. For example deleting a database should not be done here, multiple processes will fight to do the delete. "assign()" is the only method that will be run in a single process, so if a database needs to be cleaned before it can be used you should clean it there. Any final cleanup should be done in "cleanup()" which will only be called by one process at the very end.

$inst->cleanup()

This will be called once by the parent runner process just before it exits. This is your chance to do any final cleanup tasks such as deleting databases that are no longer going to be used by tests as no more will be run.

SOURCE

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/