- Patch #353618 by sun: drupalLogin does not update passed-in user object -- improved documentation.

1 files changed, 22 insertions, 2 deletions

diff --git a/modules/simpletest/drupal_web_test_case.php b/modules/simpletest/drupal_web_test_case.php
index a453caa7c..f1cb12774 100644
--- a/modules/simpletest/drupal_web_test_case.php
+++ b/modules/simpletest/drupal_web_test_case.php
@@ -736,11 +736,31 @@ class DrupalWebTestCase {
   }
 
   /**
-   * Logs in a user with the internal browser. If a user is already logged in,
-   * then the current user is logged out before logging in the specified user.
+   * Log in a user with the internal browser.
+   *
+   * If a user is already logged in, then the current user is logged out before
+   * logging in the specified user.
+   *
+   * Please note that neither the global $user nor the passed in user object is
+   * populated with data of the logged in user. If you need full access to the
+   * user object after logging in, it must be updated manually. If you also need
+   * access to the plain-text password of the user (set by drupalCreateUser()),
+   * e.g. to login the same user again, then it must be re-assigned manually.
+   * For example:
+   * @code
+   *   // Create a user.
+   *   $account = $this->drupalCreateUser(array());
+   *   $this->drupalLogin($account);
+   *   // Load real user object.
+   *   $pass_raw = $account->pass_raw;
+   *   $account = user_load($account->uid);
+   *   $account->pass_raw = $pass_raw;
+   * @endcode
    *
    * @param $user
    *   User object representing the user to login.
+   *
+   * @see drupalCreateUser()
    */
   protected function drupalLogin(stdClass $user) {
     if ($this->isLoggedIn) {