Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Test::ClassAPI(3)     User Contributed Perl Documentation    Test::ClassAPI(3)

       Test::ClassAPI -	Provides basic first-pass API testing for large	class

       For many	APIs with large	numbers	of classes, it can be very useful to
       be able to do a quick once-over to make sure that classes, methods, and
       inheritance is correct, before doing more comprehensive testing.	This
       module aims to provide such a capability.

   Using Test::ClassAPI
       Test::ClassAPI is used with a fairly standard looking test script, with
       the API description contained in	a __DATA__ section at the end of the


	 # Test	the API	for Foo::Bar
	 use strict;
	 use Test::More	'tests'	=> 123;	# Optional
	 use Test::ClassAPI;

	 # Load	the API	to test
	 use Foo::Bar;

	 # Execute the tests






       Looking at the test script, the code itself is fairly simple. We	first
       load Test::More and Test::ClassAPI. The loading and specification of a
       test plan is optional, Test::ClassAPI will provide a plan automatically
       if needed.

       This is followed	by a compulsory	__DATA__ section, containing the API
       description. This description is	in provided in the general form	of a
       Windows style .ini file and is structured as follows.

   Class Manifest
       At the beginning	of the file, in	the root section of the	config file,
       is a list of entries where the key represents a class name, and the
       value is	one of either 'class', 'abstract', or 'interface'.

       The 'class' entry indicates a fully fledged class. That is, the class
       is tested to ensure it has been loaded, and the existance of every
       method listed in	the section ( and its superclasses ) is	tested for.

       The 'abstract' entry indicates an abstract class, one which is part of
       our class tree, and needs to exist, but is never	instantiated directly,
       and thus	does not have to itself	implement all of the methods listed
       for it. Generally, many individual 'class' entries will inherit from an
       'abstract', and thus a method listed in the abstract's section will be
       tested for in all the subclasses	of it.

       The 'interface' entry indicates an external interface that is not part
       of our class tree, but is inherited from	by one or more of our classes,
       and thus	the methods listed in the interface's section are tested for
       in all the classes that inherit from it.	For example, if	a class
       inherits	from, and implements, the File::Handle interface, a
       "File::Handle=interface"	entry could be added, with the
       "[File::Handle]"	section	listing	all the	methods	in File::Handle	that
       our class tree actually cares about. No tests, for class	or method
       existance, are done on the interface itself.

   Class Sections
       Every class listed in the class manifest	MUST have an individual
       section,	indicated by "[Class::Name]" and containing a set of entries
       where the key is	the name of something to test, and the value is	the
       type of test for	it.

       The 'isa' test checks inheritance, to make sure that the	class the
       section is for is (by some path)	a sub-class of something else. This
       does not	have to	be an immediate	sub-class. Any class refered to
       (recursively) in	a 'isa'	test will have its 'method' test entries
       applied to the class as well.

       The 'method' test is a simple method existance test, using
       "UNIVERSAL::can"	to make	sure that the method exists in the class.

       The "Test::ClassAPI" has	a single method, "execute" which is used to
       start the testing process. It accepts a single option argument,
       'complete', which indicates to the testing process that the API listed
       should be considered a complete list of the entire API. This enables an
       additional test for each	class to ensure	that every public method in
       the class is detailed in	the API	description, and that nothing has been

       Bugs should be submitted	via the	CPAN bug tracker, located at


       For other issues, or commercial enhancement or support, contact the

       Adam Kennedy <>

       Copyright 2002 -	2009 Adam Kennedy.

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

       The full	text of	the license can	be found in the	LICENSE	file included
       with this module.

perl v5.24.1			  2009-07-13		     Test::ClassAPI(3)


Want to link to this manual page? Use this URL:

home | help