Writing SimpleTest assertions

Last updated on
26 July 2020

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

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"');
?>
For Drupal 8 follow trait AssertContentTrait

Help improve this page

Page status: No known problems

You can: