Last updated January 10, 2013. Created by cwgordon7 on June 2, 2008.
Edited by bucefal91, TravisCarden, xjm, jhodgdon. Log in to edit this page.

Up to date documentation or additions may be found at the api.drupal.org reference site (not necessarily formatted for browsing).

Note: Whenever you pass a message into a SimpleTest assertion, do NOT translate the message using t(). (To format a string with variables, use format_string() instead.)

Method Description Example usage
<?php
$this
->assertTrue($result, $message = FALSE, $group = 'Other')
?>
Asserts that the variable $result resolves to TRUE.
<?php
$valid
= is_valid('foo');
$this->assertTrue($valid, 'foo is a valid variable.');
?>
<?php
$this
->assertFalse($result, $message = '%s', $group = 'Other')
?>
Asserts that the variable $result resolves to FALSE.
<?php
$valid
= is_valid('bar');
$this->assertFalse($valid, 'bar is not a valid variable.');
?>
<?php
$this
->assertNull($value, $message= '%s', $group= 'Other')
?>
Asserts that the variable $value resolves to NULL.
<?php
$result
= load_my_object(-1);
$this->assertNull($result, 'NULL is returned when trying to load an invalid object.');
?>
<?php
$this
->assertNotNull($value, $message= '%s', $group= 'Other')
?>
Asserts that the variable $value does NOT resolve to NULL.
<?php
$result
= load_my_object(1);
$this->assertNotNull($result, 'A non-null result was returned when trying to load a valid object.');
?>
<?php
$this
->assertEqual($first, $second, $message= '%s', $group= 'Other')
?>
Asserts that the variable $first is roughly equivalent (==) to $second.
<?php
menu_set_active_item
('node/3');
$arg = arg(1);
$this->assertEqual($arg, 3, 'arg(1) on page node/3 resolves to 3.');
?>
<?php
$this
->assertNotEqual($first, $second, $message= '%s', $group= 'Other')
?>
Asserts that the variable $first is not roughly equivalent (!=) to $second.
<?php
menu_set_active_item
('node/3');
$arg = arg(0);
$this->assertNotEqual($arg, 3, 'arg(0) on page node/3 does not resolve to 3.');
?>
<?php
$this
->assertIdentical($first, $second, $message= '%s', $group= 'Other')
?>
Asserts that the variable $first is absolutely identical (===) to $second.
<?php
$awesome
= get_awesome();
$this->assertIdentical($awesome, t('Drupal'), 'Drupal is awesome.');
?>
<?php
$this
->assertNotIdentical($first, $second, $message= '%s', $group= 'Other')
?>
Asserts that the variable $first is not absolutely identical (!==) to $second.
<?php
$awesome
= get_awesome();
$this->assertNotIdentical($awesome, t('Drupal\'s evil twin'), 'Drupal\'s evil twin is NOT awesome.');
?>

Checking page results

<?php
$this
->assertPattern($pattern, $message= '%s', $group= 'Other')
?>
Asserts that the raw html content of the current page matches the regular expression $pattern.
<?php
$this
->assertPattern('|[Dd]rupal|', 'Drupal/drupal is on current page.');
?>
<?php
$this
->assertNoPattern($pattern, $message= '%s', $group= 'Other')
?>
Asserts that the raw html content of the current page does not match the regular expression $pattern.
<?php
$this
->assertNoPattern('|[Ee]vil|', 'Evil/evil is not on current page.');
?>
<?php
$this
->assertRaw($raw, $message="%s", $group= 'Other')
?>
Asserts that the html $raw appears in the raw html content of the current page in the SimpleTest browser.
<?php
$this
->drupalGet('user/register');
$this->assertRaw('<a href="'. url('user/password') .'">', 'A link to "Request new password" is on the user register page.');
?>
<?php
$this
->assertNoRaw($raw, $message="%s", $group= 'Other')
?>
Asserts that the html $raw does NOT appear in the raw html content of the current page in the SimpleTest browser.
<?php
$this
->drupalGet('node/1');
$this->assertNoRaw('<a href="'. url('user/password') .'">', 'A link to  "Request new password" does not appear on the page node/1.');
?>
<?php
$this
->assertText($text, $message="%s", $group= 'Other')
?>
Asserts that the text in $text appears in the content of the current page in the SimpleTest browser (html-stripped).
<?php
$this
->drupalGet('user/register');
$this->assertText(t('Request new password'), 'The text "Request new password" appears on the user register page.');
?>
<?php
$this
->assertNoText($text, $message="%s", $group= 'Other')
?>
Asserts that the text in $text does NOT appear in the content of the current page in the SimpleTest browser (html-stripped).
<?php
$this
->drupalGet('node/1');
$this->assertNoText(t('Request new password'), 'The text "Request new password" does NOT appear on the page node/1.');
?>
<?php
$this
->assertTitle($title, $message, $group= 'Other')
?>
Asserts that the title given in $title is the title of the current page in the SimpleTest browser.
<?php
$this
->drupalGet('tracker');
$this->assertTitle(t('Recent posts'), 'The title on the tracker page is "Recent posts".');
?>
<?php
$this
->assertNoTitle($title, $message, $group= 'Other')
?>
Asserts that the title given in $title is NOT the title of the current page in the SimpleTest browser.
<?php
$this
->drupalGet('tracker');
$this->assertNotTitle(t('Wrong Title'), 'The title on the tracker page is not "Wrong Title".');
?>
<?php
$this
->assertUniqueText($text, $message='', $group= 'Other')
?>
Asserts that the text in $text appears exactly once in the content of the current page in the SimpleTest browser (html-stripped).
<?php
$this
->drupalGet('user/register');
$this->assertUniqueText(t('Request new password'), 'The text "Request new password" appears exactly once on the user register page.');
?>
<?php
$this
->assertNoUniqueText($text, $message='', $group= 'Other')
?>
Asserts that the text in $text appears more than once in the content of the current page in the SimpleTest browser (html-stripped).
<?php
$this
->drupalGet('user/register');
$this->assertNoUniqueText(t('password'), 'The text "password" appears more than once on the user register page.');
?>
<?php
$this
->assertLink($label, $index = 0, $message='', $group= 'Other')
?>
Asserts that a link with the specified $label (the text between the anchor tags) is in the page. If more than one link will match, you may use the $index to specify which to look for.
<?php
$this
->drupalGet('user/register');
$this->assertLink('Register', 0, 'The register link appears on the page');
?>
<?php
$this
->assertNoLink($label, $message='', $group= 'Other')
?>
Asserts that no link with the specified $label (the text between the anchor tags) is on the page.
<?php
$this
->drupalGet('user/register');
$this->assertNoLink('Delete', 'There is no Delete link on the page');
?>
<?php
$this
->assertLinkByHref($href, $index = 0, $message='', $group= 'Other')
?>
Asserts that a link with the given $href or partial HREF is on the page.
<?php
$this
->drupalGet('user/register');
$this->assertLinkByHref('node/1', 0, 'A link to node 1 appears on the page');
?>
<?php
$this
->assertNoLinkByHref($href, $message='', $group= 'Other')
?>
Asserts that no link with the specified $href or partial HREF is on the page.
<?php
$this
->drupalGet('user/register');
$this->assertNoLinkByHref('node/', 'There are no node/ links on the page');
?>
<?php
$this
->assertResponse($code, $message= '')
?>
Asserts that the http response code for the current page in the simpletest browser matches $code.
<?php
$this
->drupalGet('admin');
$this->assertResponse(403, 'Access is denied on the administration page.');
?>

Checking form elements

<?php
assertFieldById
($id, $value = '', $message = '')
?>
Assert that a field exists in the current page with the given id. If $value is not an empty string, also checks that the field contains that value.
<?php
$this
->assertFieldById('edit-path-alias', '', 'The edit-path-alias exists on the page');
$this->assertFieldById('edit-path-alias', 'home', 'The edit-path-alias field is set correctly');
?>
<?php
assertNoFieldById
($id, $value = '', $message = '')
?>
Assert that a field does not exists in the current page with the given id. If $value is not an empty string, also checks that the field does NOT contain that value.
<?php
$this
->assertNoFieldById('edit-path-alias-wrong', '', 'The edit-path-alias-wrong is not on the page');
$this->assertNoFieldById('edit-path-alias', 'wrong-name', 'The edit-path-alias field is incorrect');
?>
<?php
assertFieldByName
($name, $value = '', $message = '')
?>
Assert that a field exists in the current page with the given name and value.
<?php
$this
->assertFieldByName('path[alias]', "home", "The alias field is correctly set to 'home'");
?>
<?php
assertNoFieldByName
($name, $value = '', $message = '')
?>
Assert that a field does NOT exist in the current page with the given name and value.
<?php
$this
->assertNoFieldByName('path[alias]', "wrong-name", "The alias field is not set to 'wrong-name'");
?>
<?php
assertFieldChecked
($id, $message = '')
?>
Assert that the checkbox field with the given $id exists and is checked.
<?php
$this
->assertFieldChecked('send-me-spam', "The user has opted in to receive spam");
?>
<?php
assertNoFieldChecked
($id, $message = '')
?>
Assert that the checkbox field with the given $id exists but is NOT checked.
<?php
$this
->assertNoFieldChecked('send-me-spam', "The user has not checked the Spam checkbox.");
?>
<?php
assertOptionSelected
($id, $option, $message = '')
?>
Assert that a select option in the current page is checked.
<?php
$this
->assertOptionSelected('ice-cream-flavor', 2, "The user has selected flavor 2.");
?>
<?php
assertNoOptionSelected
($id, $option, $message = '')
?>
Assert that the specified select option in the current page is NOT checked.
<?php
$this
->assertNoOptionSelected('ice-cream-flavor', 7, "The user has not selected flavor 7.");
?>
<?php
assertFieldByXPath
($xpath, $value, $message, $group = 'Other')
?>
Assert that a field exists in the current page by the given XPath. draft, needs testing or better examples
<?php
$this
->assertFieldByXPath('/input[@type="checkbox" and position()=2]', TRUE, "The second checkbox is ticked");
$this->assertFieldByXPath('/input[@name="info[]" and @class="custom-class"]', TRUE, "There is an input field called 'info' with class 'custom-class' ");
?>
<?php
assertNoFieldByXPath
($xpath, $value, $message, $group = 'Other')
?>
Assert that a field does NOT exist in the current page by the given XPath. draft, needs testing or better examples
<?php
$this
->assertNoFieldByXPath('/input[@type="checkbox" and position()=2]', TRUE, "The second checkbox is not ticked");
$this->assertNoFieldByXPath('/input[@name="info[]" and @class="custom-class"]', TRUE, "There is an input field called 'info' with class 'custom-class' ");
?>
<?php
assertNoDuplicateIds
($message = '', $group = 'Other')
?>
Assert that each HTML ID on the page is used for just one element.
<?php
$this
->assertNoDuplicateIds('There are no duplicate IDs');
?>

Miscellaneous

<?php
pass
($message = '', $group = 'Other')
?>
Make an assertion that is always positive.
<?php
$this
->pass("This assertion will always pass");
?>
<?php
fail
($message = '', $group = 'Other')
?>
Make an assertion that is always negative.
<?php
$this
->fail("This assertion will always fail");
?>
<?php
error
($message = '', $group = 'Other')
?>
Make an assertion that always yields an error condition.
<?php
$this
->error("This will generate an error.");
?>
<?php
assertMail
($name, $value = '', $message = '')
?>
Assert that the most recently sent email message has a field $name (e.g. "subject", "body") with the given $value.
<?php
$this
->assertMail("subject", "My latest email", 'The last message subject was "My latest email"');
?>

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

assertOptionSelected() does not exist in 6.x-2.10

--
Franz | Propeople Inc.

Typo: "the the api.drupal.org reference site" should be "the api.drupal.org reference site"

--
Qasim Zeeshan
http://qasimzeeshan.com

Also, there are two occurrences of "If $value is not empty an empty string".

Another set of functions that don't exist in Drupal 6 is any of the Href functions. It would be good to update this table with which functions are available on 6 and which on 7.

The assertMail example shown won't work, as extra \n is added to both subject and body. That would be a nice fix to the documentation.

joachim reported that AssertField is missing too here: #649370: Generate simpletest assertion documentation automatically

Personally I would recommend looking at the api.drupal.org site to find up-to-date information:
http://api.drupal.org/api/drupal/modules--simpletest--drupal_web_test_ca...
http://api.drupal.org/api/drupal/modules--simpletest--drupal_web_test_ca...
http://api.drupal.org/api/drupal/modules--simpletest--drupal_web_test_ca...

I don't see the point in trying to maintain the same documentation here too, but if someone wants to try, be my guest...

The pages you link to on API really aren't usable for someone trying to figure out how to test a particular thing. They start with several screens worth of class hierarchy, and the the actual assertions are intermingled with other class methods that aren't relevant.

This page says not to use t() in an assertion, but Drupal 7 core tests are peppered with it... was that correct advice for D6 and has now changed?

I personally still avoid using t()

The use of t() for assert messages in tests was stripped out because of the amount of overhead calling t() would have on test bot and all of the translations that would show up for the core translation team that really did not need to be translated.

See #500866: [META] remove t() from assert message

Jon Heaton

Checking if a field is disabled can be done using xpath. Here's an example:

<?php
$disabled_field
= $this->xpath('//input[@id=:id and @disabled="disabled"]', array(':id' => 'edit-name'));
$this->assertTrue($disabled_field, t('The name cannot be changed.'));
?>

Baris Wanschers (@BarisW)
Drupal specialist

Hello,

When i used drupalGet() method in my web test, I get this : GET http://example/node/1 returned 404

Same thing when I used drupalPost() method.

Any idea ?

Thanks