Our first task is to fire up the weather_info module as a block and assign it to the second sidebar region. Then we'll ask our virtual user to type in a location and have the module retrieve the information and display it on the screen.

The testing framework creates a virtual page and then acts on that page based on the input we give it in our test case. The best way to find out what we want this virtual page to do is to see how we interact with the real page. In order to build our test case, we need four pieces of information:

We know that there is a pull-down menu that allows us to set the region in which we want to place the weather information block. To refresh your memory, that pull-down is on the Structure Blocks page as shown in Figure 8-22.

Figure 8.22. The weather information block can be assigned to a region.

The first piece of information we need is right there in front of us. It's the button we use to submit the form back to the server, "Save blocks".

To get the second and third required pieces, we'll need to take a look at the HTML that was generated by Drupal. From the browser, you can "Show Source" and look for the <form> tag. Specifically, we are looking for the action attribute. This is shown in Figure 8-23.

Figure 8.23. The value of the action attribute is where we will be posting.

Next, we need to find the field to set. We can search the HTML source for what we know, "Weather block custom for each user". This is shown in Figure 8-24.

Figure 8.24. The HTML source will tell us what values to assign to which fields.

Notice the select element, <select> with the attribute name="blocks[weather_info_user_custom][region]". That's the pull-down box we want. And then we can see all of the options that populate the box. The one we want is <option value="sidebar_second">Sidebar second</option>.

Tip

Rather than viewing the HTML source as an entire page, you can use your browser's debugging mode. In Internet Explorer, pressing F12 brings up the Developer Tools. You can point to an element on the page and the tool will take you right to the source where you can interrogate the code.

Google Chrome has a similar feature, which is accessed with Ctrl-Shift-I, and there is an extension for Firefox, Firebug, that provides even more functionality for the developer.

Finally, we need to tell the testing engine how to know if the settings have been done correctly. Return to the browser, set the value of the pull-down to "Sidebar Second" and click the "Save blocks" button. You should see, at the top of the page, the familiar green banner shown in Figure 8-25.

Figure 8.25. The successful update happy banner

The fourth piece of information we need is the text on this banner. Now we have all the information we need to create a new test case. See Listing 8-12.

$edit = array (
  'blocks[weather_info_user_custom][region]' => 'sidebar_second',
  );

$this->drupalPost('admin/structure/block', $edit, 'Save blocks'),
$this->assertRaw(t('The block settings have been updated.'),
  t('Check that configuration is saved'));

Notice the value of the $edit array. This array is sent to the drupalPost() function as a command to set the values of certain form fields. This is where we set the value of 'blocks[weather_info_user_custom][region]', to 'sidebar_second'. This array can have as many members as you need in order to set the values of fields on the form.

The drupalPost() method needs to know the address to which we are posting and the contents of the form to post. The third parameter is the name of the button to press to submit the form.

Calling drupalPost() will cause the testing engine to build the page, set the variables, and submit the fields back to the server. By the time it gets to the next line, we will have assigned the block to the second sidebar region. But to make sure, we need to assert that the happy banner is found. This is done with the assertRaw() method.

Now let's save the test and run it. Don't forget to clean the environment in order to refresh the cache since we made changes to the code.

After running the tests, you should see the report with some new lines, as shown in Figure 8-26.

Figure 8.26. Report showing the successful block setting

The first "Verbose message" link shows the block configuration screen, and the second shows the after-post screen with the green success banner.

So far, we've been successful in creating an environment where we can perform our task. Our next test will be to load a page and then check to see if it contains information we are interested in. We will do this with the drupalGet() method. The task will be to check whether the system-wide variables are read, since this is what the weather block uses to display weather to an anonymous user or a user who has not yet set location, language, and unit preferences in her profile.

This test is straightforward and can be specified immediately after we have logged in our test user. The code is shown in Listing 8-13.

function testDisplayLocation() {
  variable_set('default_units', 'R'),
  variable_set('default_language', 'de'),
  variable_set('default_location', 'san francisco'),

  $this->drupalGet('node'),
  $this->assertRaw(t('San Francisco, CA'), t('Check that the block displayed'));
}

Notice that this function doesn't have any environment setup calls. The testing framework will automatically call the setUp() function before each of the test functions in our test suite.

The drupalGet and drupalPost methods are similar to the HTTP GET and POST methods. That is, while drupalPost() requires an array of form data that is sent to the server, the drupalGet() method just needs an address. Both will cause the Drupal engine to build a page, which we can interrogate using the same assertion methods that we used for drupalPost().

The test results for this function are shown in Figure 8-27.

Figure 8.27. Test results for a drupalGet method call

Now let's exercise the weather information block by asking it to get the weather report for a location that's specific for this particular user. The Weather information block provides this functionality by setting each user's location in the user profile we created in Chapter 6.

This task will require another form post, so the process will be similar to what we did when setting the block to a particular region. That is, we do the work manually on the deployed version of our environment, and learn what we need to teach the testing engine in order to perform the task automatically.

As with the previous case, we will need the same four pieces of information. By viewing the source of the page with the weather information block, we can see the code displayed in Figure 8-28.

Figure 8.28. HTML code produced by the weather information form

From this, we can get the three pieces of information we need to do a drupalPost—the location to be posted to (<form ... action="/"...>), the name of the form field where we'll enter the location (<input ... name="weather_location"...>), and the value of the submit button (<input type="submit" ... value="Search"...>). When we manually enter the information into our live site, we see that we get our fourth piece of required information—the location that has been retrieved from the weather service. The code to perform these tasks is shown in Listing 8-14.

function testUserLocationChange() {
  $edit = array (
    'weather_location' => 'manhattan',
    );
  $this->drupalPost('/', $edit, 'Search'),
  $this->assertRaw(t('New York, NY'), t('Check that the location was found'));
}

Notice that the location we entered is "manhattan", but that we will be looking for "New York, NY". This is a sure test that the weather service has been called and translated the informal name to the formal one.

Now, save this and rerun the tests. Don't forget to clean the test environment because we changed code.

The outcome will show a failure. You're probably wondering why it failed, and why I subjected you to this display. There's a good reason. Two, actually. First, it took me a while to figure out what was happening, so I wanted to share my pain with you. Second, lessons learned through pain tend to stick.

Figure 8-29 shows the error.

Figure 8.29. Error in setting the user location.

You'll see a clue if you expand the "Verbose message" link or look at the page shown in Figure 8-30.

Figure 8.30. Posted screen that is missing the weather information

Here we see the weather information block with the search button, but there is no weather for New York. To understand why this doesn't work, you need to recall the basics of the DrupalWebTestCase framework. Remember that we start with a completely blank slate. No users, no enabled modules (except the core defaults), and no blocks. In the setUp() method, we enabled the modules and created the user, and then established the block in the appropriate region.

But we didn't attach fields to the user entity and set the values. The Fields module is enabled by default, but we must also do all the work to establish and attach the three fields we created in Chapter 6, and then add values to those fields for our temporary user.

This requires making some calls to the Fields API. The calls are field_create_field() and field_create_instance(). Listing 8-15 shows the code for creating the three fields.

// *
// * Weather location field
// *
$field = array(
  'field_name' => 'field_weather_location',
  'type' => 'text',
  'translatable' => TRUE,
  );
$instance = array(
  'field_name' => 'field_weather_location',
  'entity_type' => 'user',
  'bundle' => 'user',
  'label' => 'Weather location',

'widget' => array(
      'type' => 'text_textfield',
      'weight' => '15',
      ),
    'description' => st('Enter a location on earth for which you would like '
      . 'to see weather information presented.'),
    );
field_create_field($field);
field_create_instance($instance);

// *
// * Weather language field
// *
$field = array(
  'field_name' => 'field_weather_language',
  'type' => 'list_text',
  'translatable' => TRUE,
  'settings' => array(
      'allowed_values' => "en|English
es|Spanish
de|German
tr|Turkish
fr|French
",
      'allowed_values_function' => '',
      ),
    );
$instance = array(
  'field_name' => 'field_weather_language',
  'entity_type' => 'user',
  'bundle' => 'user',
  'label' => 'Weather language',
  'widget' => array(
      'type' => 'options_select',
      'weight' => '16',
      ),
    'description' => st('Enter the language in which you would like to see '
      . 'weather information presented.'),
    'default_value' => array(
      array(
        'value' => 'en',
        ),
      ),
    );
field_create_field($field);
field_create_instance($instance);

// *
// * Weather units field
// *
$field = array(
  'field_name' => 'field_weather_unit',
  'type' => 'list_text',
  'translatable' => TRUE,
  'settings' => array(
      'allowed_values' => "F|Fahrenheit
C|Celsius
K|Kelvin
R|Rankine",
      'allowed_values_function' => '',
      ),
    );
$instance = array(
  'field_name' => 'field_weather_unit',
  'entity_type' => 'user',
  'bundle' => 'user',
  'label' => 'Weather units',
  'widget' => array(
      'type' => 'options_select',

'weight' => '17',
      ),
    'description' => st('Enter the measurement unit with which you would like '
      . 'to see weather information presented.'),
    'default_value' => array(
      array(
        'value' => 'F',
        ),
      ),
    );

// Create the field and instance.
field_create_field($field);
field_create_instance($instance);

Once we create the three fields, we need to set some values for the fields in the user profile and see if they take. This is shown in Listing 8-16.

$uid = $this->test_user->uid;

$edit = array (
  'field_weather_location[und][0][value]' => 'san francisco',
  'field_weather_language[und]' => 'en',
  'field_weather_unit[und]' => 'F',
  );

$this->drupalPost("user/{$uid}/edit/", $edit, 'Save'),
$this->assertRaw(t('The changes have been saved.'),
  t('Check that profile was updated'));

First, we get the identifier of the current user. This is the temporary user the test framework created for us. We'll need that in order to craft the URL later. Next, we create the array of fields that we'll be populating. A call to drupalPost() will create the page, passing the field data and pressing the submit button. And then we check for the happy text that the profile was updated. The result is shown in Figure 8-31.

Figure 8.31. Proof that our test worked

The next step is to see that the block on a normal page is reading the attached fields from the user profile. That's done with the code in Listing 8-17.

$this->drupalGet('node'),
$this->assertRaw(t('San Francisco, CA'),
  t('Check that the user location displayed'));

The drupalGet() function is called, passing 'node', which displays the front page. If the profile is read properly, the block will show with the proper city and our test will pass. The page, as recorded by the testing framework, shows that it worked. (See Figure 8-32.)

Figure 8.32. Test passed showing the appropriate weather

That wraps up the tests on the user side. The key to a successful web test harness is to set up the environment with everything you need to do the test. If you keep this simple rule in mind, your testing will go much better.

There's one more area that needs testing, and that's the code that sets up default values from the administrator's page. As you'll recall, the system administrator can set weather information values globally, which are used by anonymous users and registered users who have not yet created their own custom location. These default fields are entered in the form shown in Figure 8-33.

Figure 8.33. Administration screen for setting weather information defaults

We need to create a test case that exercises this screen so we can be confident that any changes to our code don't break this functionality.

To create the test, we will instantiate the DrupalWebTestCase class. This test doesn't use profiles so the setUp() method is a bit more streamlined, as shown in Listing 8-18.

class WeatherSettingsTest extends DrupalWebTestCase {

  public static function getInfo() {
    return array(
      'name' => 'Weather default tests',
      'description' => 'Tests default settings and weather display.',
      'group' => 'Weather info',
      );
  }

  public function setUp() {
    // Enable any modules required for the test
    parent::setUp(array('weather_info'));
    // Create and log in our privileged user.
    $this->privileged_user = $this->drupalCreateUser(array(
      'view weather info',
      'administer weather info',
      'administer site configuration',
      'access administration pages',
      ));
    $this->drupalLogin($this->privileged_user);
  }

The settings screen takes the values entered in the form variables and writes them as persistent Drupal variables. The first test is to set the defaults on the screen and then check to see if they made it successfully into Drupal variables. The code for this is in Listing 8-19.

function testWeatherDefaults () {
  $default_location = 'Boise';
  $default_units = 'F';
  $default_language = 'en';

  $edit['default_location'] = $default_location;
  $edit['default_units'] = $default_units;
  $edit['default_language'] = $default_language;

  $this->drupalPost('admin/config/weather_info/settings', $edit, t('Save configuration'));
  $this->assertRaw(t('The configuration options have been saved.'),
    t('Check that configuration is saved'));

  $this->assertEqual(variable_get('default_location'), $default_location,
    t('Default location variable'));
  $this->assertEqual(variable_get('current_location'), $default_location,
    t('Current location variable'));
  $this->assertEqual(variable_get('default_units'), $default_units,
    t('Default unit variable'));
  $this->assertEqual(variable_get('default_language'), $default_language,
    t('Default language variable'));
}

Three function variables are set with test values and the form fields are created as an array called $edit. Next, the drupalPost() method is called, posting the values back to the form using the submit button labeled "Save configuration". Finally, some assertions are done to check the four Drupal variables that the form sets. Figure 8-34 shows that it worked.

Figure 8.34. Test of default settings passed

Here we can see the happy text and the new defaults.

Ourlast test intentionally creates an error condition and then interrogates the page to see if the error was reported correctly. In this case, we will test the boundaries of the #maxlength attribute of the location field on the weather information settings page. In Chapter 6, we indicated that the maximum length of the data allowed in the field is 20 characters. The code in Listing 8-20 tests that limit.

function testMaxlengthFail () {
  // this should fail because the location is longer than 20 characters
  $default_location = 'San Francisco, California';
  $default_units = 'C';
  $default_language = 'es';

  $edit['default_location'] = $default_location;
  $edit['default_units'] = $default_units;
  $edit['default_language'] = $default_language;

  $this->drupalPost('admin/config/weather_info/settings', $edit,
    t('Save configuration'));
  $this->assertRaw(t('Default location cannot be longer than 20 characters'),
    t('Check length error'));
}

Putting this into our DrupalWebTestCase class produces the report shown in Figure 8-35.

Figure 8.35. Fail test failed

Something is wrong here. By checking on the saved screen behind the "Verbose message" link, we can get an idea of what went wrong, as Figure 8-36 shows.

Figure 8.36. Evidence of a problem

Notice that the text that should indicate a failure is showing success. I'll save you the debugging chautauqua, but I hinted at the culprit in Chapter 6 when we created this settings page. The offending code is shown in Listing 8-21.

$form['wx_settings']['default_location'] = array (
    '#type' => 'textfield',
    '#title' => t('Default location'),
    '#default_value' => variable_get('default_location', null),
    '#size' => 20,
    '#maxlengh' => 20,
    '#description' => t('Enter a location on earth to act as the default for the site.'),
    );

Notice that the attribute, #maxlength is misspelled. This is not recognized as an error by Drupal, which just ignores everything it doesn't recognize. But by not recognizing the attribute, the system default for #maxlength, 128, is used instead. So our 25-character test field was within the boundaries and did not raise an error. Correcting the spelling and rerunning the test gives us the results we sought. See Figures 8-37 and 8-38.

Figure 8.37. Test report showing successful failure

Figure 8.38. Successful failure