API functions

The internal browser

The DrupalWebTestCase features an internal browser that can be used to navigate on your test site. Please read the basic documentation of the WebTestCase class for more information.

function $this->drupalGet($path, $options = array())

This function does a get request to a Drupal page.
The $path indicates a page that can be visited; $options contains additional data which may be passed to the url() function in order to determine the url to visit. The content will be loaded and saved into $this->_content (as well as returned), where it can be retrieved by using the function $this->drupalGetContent().

function $this->drupalPost($path, $edit, $submit, $reporting = TRUE)

This function does a post request on a Drupal page.
The $path indicates a page containing a form that will be filled with $edit data. Then the button indicated by $submit will be clicked (submit caption will be translated by this method).

It also does assertion that the requests were successful and form fields could be set.

Example:

<?php
$name = $this->randomName();
$mail = "$name@example.com";
$edit = array('name' => $name,
              'mail' => $mail);
$this->drupalPost('user/register', $edit, 'Create new account');
?>

Note: this function used to be called drupalPostRequest()

function $this->clickLink($label, $index = 0)

Follows a link on the current page by name. Will click the first link found with this link text by default, or a later one if an $index is given. The $label is automatically translated.
An assertion is done about the availability of the link and the URL it points to. Also gives some output including current and requested URL.

Example:

<?php
$this->clickLink(t('Log out'));
?>

function $this->drupalCreateUser($permissions = NULL)

This function creates a user and returns the user object with an additional value pass_raw containing the non-hashed password.
It also creates a role with the specified $permissions that is assigned to the returned user.
The $permissions are specified as an array of strings. If it is omitted or NULL, the default permissions for a registered user will be used:
'access comments, access content, post comments, post comments without approval'
An assertion for success is done as well as clean-up on the user and role tables.

function $this->drupalLogin($user = NULL)

This function logs a user into your site via the internal browser. You can just hand it a $user object (required is a pass_raw value).
If the argument is omitted this function will create a user and role with the standard permissions mentioned above.

After the user is logged in, you can now navigate with the internal browser.

Example:

<?php
// Prepare a user to do the stuff
$user = $this->drupalCreateUser(array('access content', 'create page content'));
$this->drupalLogin($user);

// Now do something with the users
$this->drupalGet('node/' . $node->nid));
?>

This method also does several assertions about the login process from the browsers perspective.

function $this->_drupalCreateRole($permissions = NULL)

This function is rarely useful. The $permissions parameter behaves exactly like in drupalCreateUser.
The return value is a role-id integer or FALSE on failure.
A success assertion is done, as well as decent clean-up of the role and permission tables.