NAME

Gtk2::Test - Utility methods for testing Gtk2-Perl

SYNOPSIS

BEGIN {
   use Gtk2::Test;
   @test_plan = (
       [$MAKE_TEST_BOX, 'Gtk2::Window'],
           ["new()", $EXPECT_ERROR, "=~ /Usage:/"],
           ["new('toplevel')"],
           ["new('topleel')", $EXPECT_ERROR,   "=~ /FATAL: invalid GtkWindowType value topleel/"],
           ["set_position('xcenter')", $EXPECT_ERROR],
           ["set_position('mouse')"],
           ["set_title()", $EXPECT_ERROR, "=~ /Usage:/"],
           ["set_title('Title')"],
           ["get_resizable",                   "== $TRUE"],
           ["set_resizable($FALSE)"],
           ["get_resizable",                   "== $FALSE"],
           [$GET_SET, 'resizable', $FALSE, $TRUE],
           ["realize"],

       [$USE, 'Gtk2::HBox'],
           ["new(1, 1)"],
           [$EVAL, "\$o->isa('Gtk2::HBox')"],
           [$EVAL, "!(\$o->isa('xGtk2::HBox'))"],
           [$EVAL, "\$xo->isa('Gtk2::HBox')", 
               $EXPECT_ERROR, '=~ /Global symbol "\$xo" requires explicit package name/'],
           [$EVAL, "\$w->{'xButton'}[0]->xisa('Gtk2::Button')", 
               $EXPECT_ERROR, '=~ /Can\'t call method "xisa" on an undefined value/'],
           [$C_EVAL, "\$w->{'Window'}[-1]->add(\$w->{'HBox'}[-1])"],

       [$USE, "Gtk2::Button"],
           ["new"],
           ["set_label('Test label')"],
           [$GET_SET, 'label', "'Test label'", "'Print handler args'"],
           ["signal_connect('button_press_event', 'print_handler_args', 'test data')"],

           [$ADD_TO_TEST_BOX],
   );
   plan tests => scalar @test_plan;
}

$DEBUG = $ARGV[0] || 0;

&do_tests;

DESCRIPTION

Gtk2::Test provides some utility methods that are used to test Gtk2-Perl directly or during 'make test'. There are several exported variables that can be used to work with - such as the current class, value returned by a method, error string and current object. The methods carry out the tests and report all actions requested.

The methods can be called directly or indirectly but the simplest way is to specify a test_plan and run it automatically. There is a script ./t/i_test.pl that will run the test with a Gtk2-main> call so that you can see the fruits of all your labours.

THE TEST PLAN

`@test_plan`

This is the real user interface. All the tests are defined in an array that is exported from Gtk2::Test.

The array holds all the tests in the order that they should be run.

Each test is defined as an anonymous array of up to 4 elements and there are several possible test specifications:

[$MAKE_TEST_BOX, 'Classname']

This will try to 'use Classname;' and build a basic window/vbox/hbox/button testing display to add your widget to. This is just a convenient way to avoid repetitious code. Use $ADD_TO_TEST_BOX to add any widgets to the top space in the HBox. This will not be constructed if the test is part of the Test::Harness run during a 'make test' _______________________________ | | | HBox for your widgets | |-------------------------------| | Print widgets | Quit | | button | button | |_______________|_______________|

BYPRODUCT - $class is set to 'Classname' and $w-{'Test'}{'Window'}>

[$USE, 'Classname']

This will try to 'use Classname;' and report any failures.

BYPRODUCT - $class is set to 'Classname'

['new()']

This will construct an object $o in the current $class with the args supplied (none in this case) The actual call will be $o = new Classname()

BYPRODUCT - $o is set to the object returned from the method call which is also pushed onto @{$w->{$class}} for later use eg. add(\$w->{'HBox'}[-1])

['method()']

This will call this method with the args supplied (none in this case) The actual call will be $o->method()

BYPRODUCT - $ret is set to the value returned from the method call

["method('arg1', 'arg2')", '== 1']

This will call this method with the args supplied and check that the returned value (stored in $ret) is numerically equal to 1 The actual call will be $o->method('arg1', 'arg2')

BYPRODUCT - $ret is set to the value returned from the method call

["method('arg1', 'arg2')", $EXPECT_ERROR, '=~ /error21/']

This will call this method with the args supplied and expect failure. It will check that the error string (stored in $err) contains the string 'error21' The actual call will be $o->method('arg1', 'arg2')

BYPRODUCT - $ret is set to the value returned from the method call

[$GET_SET, 'method', "'Expected'", "'New value'"]

This will call get_method() and check that it returns 'Expected'

Then it calls set_method('New value')

Finally calls get_method() again and checks that it returns 'New value'

The comparison depends on the first expected value - if it is digits the checks are ($ret == $expected) otherwise ($ret eq $expected)

[$EVAL, 'string to eval', "=~ /success/"]

Eval the supplied string and check that $expect is returned if specified. This is really just a simple interface to ok() that can be used in a test_plan. $OK is returned if the call succeeds (in a perl sense) else $FAIL.

BYPRODUCT - $ret is set to the value returned from the eval

[$C_EVAL, 'string to eval']

BYPRODUCT - $ret is set to the value returned from the eval

[$ADD_TO_TEST_BOX, $widget]

The widget specified or the last constructed is added to the test HBox in the test window.

BYPRODUCT - The widget has $widget-show()> called for it.

BYPRODUCT - In all cases $err is set to '' or the last error reported with some explanatory messages.

Checks

Normally, the returned value (stored in $ret) is compared as specified in the second arg. Any code supplied is eval()ed and failures passed back.

If you specify $EXPECT_ERROR as the second argument, the error (stored in $err) is compared as specified in the third arg. Any code supplied is eval()ed and failures passed back. If the error checks successfully $OK is returned otherwise $FAIL. In both cases, $err will hold explanatory messages and the original error.

METHODS

This is usually all you need to call to process your @test_plan

&do_tests()

Run all the tests in the test_plan

e.g. &do_tests;

There are several internal manual tests that you can use to extend your test scripts but do remember to add 1 to the 'plan tests' line in BEGIN for each manual test that you add.

&try_eval($method, $args, $expect, $check)

Eval the supplied string and check that $expect is returned if specified. This is really just a simple interface to ok() that can be used in a test_plan.

Returns either $OK or $FAIL (error details in $err)

BYPRODUCT - $ret will hold the value returned by the eval

e.g. ok(&try_eval('', '== 2'), $OK, $err);

&try_method($method, $args, $expect, $check)

Run the method in the current class with the supplied arg string and check that $expect is returned if specified.

Returns either $OK or $FAIL (error details in $err)

BYPRODUCT - $ret will hold the value returned by the method

e.g. ok(&try_method('get_border_width', '== 2'), $OK, $err);

e.g. ok(&try_method('get_border_width', $EXPECT_ERROR, '=~ /error21/'), $OK, $err);

&try_get_set($method, $old, $new)

Run the get_method() in the current class and check it equals $old Then run set_method($new) and finally run get_method again to check that $new is returned.

Returns either $OK or $FAIL

BYPRODUCT - $ret will hold the value returned by the last get_method

e.g. ok(&try_get_set('resizable', $TRUE, $FALSE), $OK, $err);

&try_use($class)

Tries to use $class;.

Returns either $OK or $FAIL

BYPRODUCT - $class will hold the class name

e.g. ok(&try_use('Classname'), $OK, $err);

&try_new($method, $args)

Tries to call $o = $class-$method($args);>.

Returns either $OK or $FAIL

BYPRODUCT - $o will be a ref to the constructed object which is also pushed onto @{$w->{$class'}} for use later eg. add(\$w->{'HBox'}[-1])

e.g. ok(&try_new('new_with_label', 'Label text'), $OK, $err);

e.g. ok(&try_method('new', $EXPECT_ERROR, '=~ /FATAL: invalid GtkWindowType value topleel/'), $OK, $err);

&test_string($class)

Returns a skeleton test script for specified widget

e.g. print(&test_string("Gtk2::Gdk::Pixmap"));

&log_fail($call, $err)

Logs an error for later analysis

e.g. print(&log_fail('new()', 'method unavailable');

&quit

Quits any Gtk2->main event loop. You can use it in any signal_connect calls in tests to quit the event loop.

e.g.

&print_handler_args($class)

A utility signal handler that will print all args passed from the widget. Use it in any signal_connect calls in tests to see what is passed. e.g.

&print_widget_tree($class)

A utility signal handler that will print all the widgets that have been constructed so far. Use it in any signal_connect calls in tests to see what is constructed. e.g.

VARIABLES

$o

This is the widget instance that was constructed and is used for all subsequent tests.

$w

A hash of arrays where all constructed widgets instances are stored for use later - ie $o->add($w->{'Button'}[-1]);

$err

The error string returned by the latest test.

$ret

The value that was returned by the latest method call

$DEBUG

Setting $DEBUG to a number > 0 will cause debugging messages to be printed

Level  Output
1      Method calls that will be tested
2      Failed check on expected value
3      new() calls
4      All checks made on expected value
5      A Data::Dumper print of $o on failure

CONSTANTS

$USE

This is a request to use() a class

$EVAL

This is a request to eval a string

$C_EVAL

This is a request to eval a C call (like Gtk2 methods)

$GET_SET

This is a request to get/set/get a widget property

$EXPECT_ERROR

We are expecting this call to fail and will apply the check to $err instead of $ret.

Values to use in @test_plan

These values can be used in the testplan to avoid escaping strings and to make sure that the values get through to the test evals

$NULL  Null string ('')
$ZERO  Zero (0)
$TRUE
$FALSE
$C_OK ''

Placeholder args

$NOARGS
$NOCHECK

$FAIL

Returned in the event of failure.

$OK

Returned if test succeeded

$PACKAGE $VERSION $AUTHOR $DATE

Details of the Gtk2::Test module

AUTHOR

Dermot Musgrove <dermot.musgrove@virgin.net>

COPYRIGHT

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

See http://www.perl.com/perl/misc/Artistic.html

To install Gtk2, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Gtk2

CPAN shell

perl -MCPAN -e shell
install Gtk2

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

THE TEST PLAN

@test_plan

Checks

METHODS

VARIABLES

CONSTANTS

SEE ALSO

AUTHOR

COPYRIGHT

Module Install Instructions

`@test_plan`