NAME

Krang::Test::Content - a package to simplify content handling in Krang tests.

SYNOPSIS

  use Krang::ClassLoader 'Test::Content';

  my $creator = pkg('Test::Content')->new();
  
  
  # create a Krang::Site object
  my $site = $creator->create_site(preview_url => 'preview.fluffydogs.com',
                                   publish_url => 'www.fluffydogs.com',
                                   preview_path => '/tmp/preview_dogs',
                                   publish_path => '/tmp/publish_dogs');
  
  my ($root) = pkg('Category')->find(site_id => $site->site_id);
  
  # create a Krang::Category object.
  my $poodle_cat = $creator->create_category(dir    => 'poodles',
                                             parent => $root->category_id,
                                             data   => 'Fluffy Poodles of the World');
  
  # create another Krang::Category object w/ $poodle_cat as parent.
  my $french_poodle_cat = $creator->create_category(dir    => 'french',
                                                    parent => $poodle_cat,
                                                    data   => 'French Poodles Uber Alles');
  
  # create a Krang::User user.
  my $user = $creator->create_user();
  
  # get the login username if you don't know it
  my $login = $user->login();
  # get the pw
  my $password = $user->password();
  
  # create a Krang::Media object.
  my $media = $creator->create_media(category => $poodle_cat);
  
  # create a Krang::Story object under various categories, with media object.
  my $story1 = $creator->create_story(category     => [$poodle_cat, $french_poodle_cat],
                                      linked_media => [$media]);
  
  # create Story object linking to media and previous story.
  my $story2 = $creator->create_story(category     => [$poodle_cat, $french_poodle_cat],
                                      linked_story => [$story1],
                                      linked_media => [$media]);
  
  # Where to find the published story on the filesystem
  my @paths = $creator->publish_paths(story => $story);
  
  # create a Krang::Contrib object
  my $contributor = $creator->create_contrib();
  
  # create a Krang::Template object for root element of story
  my $template = $creator->create_template(element => $story->element);
  
  # create a Krang::Template associated with a specific cat
  $template = $creator->create_template(element => $story->element, category => $poodle_cat);
  
  # get a Krang::Publisher object
  my $publisher = $creator->publisher();
  
  # create and deploy test templates
  my @templates = $creator->deploy_test_templates();
  
  # undeploy test templates
  $creator->undeploy_test_templates();
  
  
  # undeploy all live templates
  $ok = $creator->undeploy_live_templates();
  
  # restore previously live templates
  $ok = $creator->redeploy_live_templates();
  
  
  # get a random word (returns UTF-8 encoded words if Charset directive is set to utf-8)
  my $word = $creator->get_word();
  
  # get a random word exclusively composed of ascii letters a-z and A-Z
  my $ascii = $creator->get_word('ascii');
  
  # delete a previously created object
  $creator->delete_item(item => $story);
  
  # clean up after the mess you made.  Leave things where you found them.
  $creator->cleanup();

DESCRIPTION

Krang::Test::Content exists to simplify the process of writing tests for the more advanced subsystems of Krang. Most test suites depend on content existing in the system to test against, and have been rolling their own content-creating routines. This module exists to centralize a lot of that code in one place. Additionally, it provides cleanup functionality, deleting everything that has been created using it.

This module is designed to work with the Default and TestSet1 element sets - it may or may not work with other element sets.

NOTE - It should be clear that this module assumes that the following modules are all in working order: Krang::Site, Krang::Category, Krang::Story, Krang::Media, Krang::Contrib.

INTERFACE

METHODS

• $creator = Krang::Test::Content->new()
  
Instantiates a Krang::Test::Content object. No arguments are needed/supported at this time.

new() will croak with an error if the InstanceElementSet is not Default or TestSet1. At this time, those are the only element sets supported.

• $site = $creator->create_site()
  
Creates and returns a Krang::Site object. If unsuccessful, it will croak.

Arguments:

• preview_url
  
The url for the preview version of the site being created.
• publish_url
  
The url for the publish version of the site being created.
• preview_path
  
The filesystem path that correlates with the preview_url doc root.
• publish_path
  
The filesystem path that correlates with the publish_url doc root.

• $category = $creator->create_category()
  
Creates and returns a Krang::Category object for the directory specified, underneath the parent category described by parent. It will croak if unable to create the object.

Arguments:

• parent
  
The parent category for this category. This must be an integer corresponding to the ID of a valid Krang::Category object, or a Krang::Category object.

If parent is not set, it will default to the root category of the first Krang::Site object created by create_site.

• dir
  
String containing the directory to be created. Randomly generated by default.
• data
  
Content to put in the root element of the category. Randomly generated by default.

• $user = $creator->create_user()
  
Creates and returns a Krang::User object.

Accepts the standard arguments passed to Krang::User, or will function with no arguments whatsoever, in which case it will only create the username and password.

NOTE: If a username is specified, create_user will croak if user creation fails because that username is already taken. If no username is specified, create_user will try usernames until it finds one that does not exist.

NOTE2: If group_ids are not specified, create_user will create a user with admin-level access.

• $media = $creator->create_media()
  
Creates and returns a Krang::Media object underneath the category specified. It will croak if unable to create the object.

Arguments:

• category
  
A single Krang::Category object, to which the Media object will belong. If not specified, it will be assigned one randomly.
• title
  
Title for the image. Randomly generated by default.
• filename
  
Image filename. Randomly generated by default.
• caption
  
Image caption. Randomly generated by default.
• x_size
  
An integer specifying how wide the image will be. By default, the image will be between 50-350 pixels wide.
• y_size
  
An integer specifying how tall the image will be. By default, the image will be between 50-350 pixels tall.
• format
  
Must be one of (jpg, png, gif). Determines the format of the image. If not specified, it will randomly choose one of the three formats.

• $story = $creator->create_story()
  
Creates and returns a Krang::Story object, underneath the categories specified. It will croak if unable to create the object. The story will already be saved & checked-in.

By default, the story will be a single page, with a title, deck, header, and three paragraphs.

Arguments:

• class
  
The class of story (e.g. article, cover). This determines the root element of the story object being created.

If not specified, it will default to 'article', which may or may not work, depending on the element library being used.

• category
  
An array reference containing Krang::Category objects under which the story will appear.

If not specified, one will be assigned randomly.

• linked_stories
  
An array reference containing Krang::Story objects. Each Story object in the array will be linked to in the new story.
• linked_media
  
An array reference containing Krang::Media objects. Each Media object in the array will be linked to in the new story.
• pages
  
Determines how many pages will exist in the story. Each page will contain a header and 3 paragraphs. By Default, one page is created.
• paras_per_page
  
Determines how many paragraphs will be created on each page. Defaults to 3.
• title => 'Confessions of a Poodle Lover'
  
The title for the story being created. By default, a randomly-generated title will be used.
• deck => 'Why fluffy dogs make me happy'
  
The deck for the story being created. By default, a randomly-generated deck will be used.
• header => 'In the beginning'
  
The first header in the story. By default, a randomly-generated header will be used.

This header only applies to the first page. If more than one page is being created in this story, subsuquent pages will have randomly-generated headers.

• paragraph => [$p1, $p2, $p3, $p4]
  
The paragraph content for the paragraphs on the first page. One paragraph will be created for each element in the list reference passed in. By default, three randomly-generated paragraphs will be created.

This only applies to the first page of a story - additional pages will have three randomly-generated paragraphs each.

• @paths = $creator->publish_paths(story => $story)
  
Returns a list of filesystem paths where the story will be published.

Takes either story or media arguments.

• $contributor = $creator->create_contrib()
  
Creates and returns a Krang::Contrib object. All the parameters that can be used in creating a Krang::Contrib object can be passed in here, or will be randomly generated.

Arguments:

• prefix
  
• first
  
• middle
  
• last
  
• suffix
  
• email
  
• phone
  
• bio
  
• url
  
• $template = $creator->create_template()
  
Creates a valid HTML template and Krang::Template object based on a Krang::Element object. When called in scalar mode, returns the template. When called in array mode, returns the template and the text content.

The following arguments are taken:

• element
  
A Krang::Element element. Unless the content is also supplied, the template constructed will be based on the makeup of $element.
• element_name
  
The name of the element the template is being constructed for. If this argument is used, content must be supplied as well, as the template cannot be generated automatically in this case.
• content
  
The content of the template. If not set, the template will be built automatically, based on the makeup of the element and its children.
• category
  
Associates the template with the Krang::Category object $category. Otherwise the template will be associated with the root category for the first Krang::Site object created.
• flattened
  
This is an optional argument which defaults to 0: if set to 1, the template will be created in a flattened form (i.e. rather than each container appearing in the form of <tmpl_var container>, it will appear as: <tmpl_if container><tmp_loop element_loop><tmpl_var child_1>etc.</tmpl_loop></tmpl_if>
• predictable
  
This is an optional argument which defaults to 0: if set to 1, no random content will be included.

• $publisher = $creator->publisher()
  
Returns a Krang::Publisher object.
• @templates = $creator->deploy_test_templates()
  
Creates a set of Krang::Template templates based on the elements in TestSet1 (looking at Krang::ElementLibrary). These templates will be generated randomly, so you cannot run tests based on the content of the templates. These templates should be used when you need to publish Krang::Story objects generated above.

This method will check to see if undeploy_live_templates() has been run beforehand.

If not, it will run it first as a safety measure, so as to not clobber live templates, or to cause random errors.

Will croak if there are problems.

Returns a list of Krang::Template templates.

• $creator->undeploy_test_templates()
  
Removes the test templates placed out on the filesystem.
• @templates = $creator->undeploy_live_templates()
  
A preventative measure to make sure that live templates don't cause problems, or are otherwise clobbered by test templates.

Searches the template root for potentially problematic templates, and undeploys them.

• $creator->redeploy_live_templates()
  
Redeploys any live templates that were taken down previously.
• $word = get_word()
  
• $word = get_word('ascii')
  
This subroutine creates all the random text content for the module - each call returns a randomly-chosen word from the source - either t/dict/words.latin1 or <t/dict/words.ascii>.

Depending on the Charset directive in conf/krang.conf those words are utf-8 encoded or not.

• $creator->delete_item(item => $krang_object)
  
Attempts to delete the item created.

Any errors thrown by the item itself will not be trapped - they will be passed on to the caller.

If the delete is unsuccessful, it will leave a critical message in the log file and croak.

• $creator->cleanup()
  
Attempts to delete everything that has been created by the Krang::Test::Content object. A stack of everything created by the object is maintained internally, and that stack is used to determine the order in which content is destroyed (e.g. Last Hired, First Fired).

Will log a critical error message and croak if unsuccessful.

BUGS

Krang::Test::Content will only work against the ElementSet TestSet1. Any other Element Sets will cause unpredictable behavior.

TODO

Flesh out the various create_ methods to support more of the test code in Krang. Ideally, this module would also support bin/krang_floodfill, so that all test suites and dummy data are coming from the same source.

SEE ALSO

Krang::Category, Krang::Story, Krang::Media, Krang::Contrib