diff -u b/core/lib/Drupal/Core/Utility/Token.php b/core/lib/Drupal/Core/Utility/Token.php
--- b/core/lib/Drupal/Core/Utility/Token.php
+++ b/core/lib/Drupal/Core/Utility/Token.php
@@ -129,6 +129,16 @@
   /**
    * Replaces all tokens in a given string with appropriate values.
    *
+   * Tokens can also define cacheable metadata related to themselves which can
+   * therefor be applied e.g to a render array.
+   * @code
+   *  $cacheability_metadata = new CacheableMetadata();
+   *  // Token::replace takes $cacheability_metadata as an reference so that it
+   *  // can be applied for the render array.
+   *  $build['#markup'] = $token->replace('Tokens: [node:nid] [current-user:uid]', ['node' => $node], [], $cacheability_metadata);
+   *  $cacheability_metadata->applyTo($build);
+   * @endcode
+   *
    * @param string $text
    *   A string potentially containing replaceable tokens.
    * @param array $data
@@ -159,7 +169,7 @@
    * @param \Drupal\Core\Cache\CacheableMetadata $cacheability_metadata
    *   The cacheablity metadata.
    * @return string Text with tokens replaced.
-   * Text with tokens replaced.
+   *   Text with tokens replaced.
    */
   public function replace($text, array $data = array(), array $options = array(), CacheableMetadata &$cacheability_metadata = NULL) {
     $text_tokens = $this->scan($text);
diff -u b/core/lib/Drupal/Core/Utility/token.api.php b/core/lib/Drupal/Core/Utility/token.api.php
--- b/core/lib/Drupal/Core/Utility/token.api.php
+++ b/core/lib/Drupal/Core/Utility/token.api.php
@@ -41,11 +41,11 @@
  * @param $options
  *   (optional) An associative array of options for token replacement; see
  *   \Drupal\Core\Utility\Token::replace() for possible values.
- * @param \Drupal\Core\Cache\CacheableMetadata $cacheablity_metadata
- *   The cache metadata. By default Drupal pulls of the metadata from the passed
- *   $data objects, but for global tokens the module developer needs to take
- *   into account cacheable metadata from related objects, like the system.site
- *   config object, for the site-name token.
+ * @param \Drupal\Core\Cache\CacheableMetadata $cacheability_metadata
+ *   The cache metadata. By default Drupal pulls off the metadata from the
+ *   passed $data objects, but for global tokens the module developer needs to
+ *   take into account cacheable metadata from related objects, like the
+ *   system.site config object, for the site-name token.
  *
  * @return
  *   An associative array of replacement values, keyed by the raw [type:token]
@@ -54,7 +54,7 @@
  * @see hook_token_info()
  * @see hook_tokens_alter()
  */
-function hook_tokens($type, $tokens, array $data, array $options, \Drupal\Core\Cache\CacheableMetadata &$cacheablity_metadata) {
+function hook_tokens($type, $tokens, array $data, array $options, \Drupal\Core\Cache\CacheableMetadata &$cacheability_metadata) {
   $token_service = \Drupal::token();
 
   $url_options = array('absolute' => TRUE);
@@ -92,7 +92,7 @@
         case 'author':
           $account = $node->getOwner() ? $node->getOwner() : User::load(0);
           $replacements[$original] = $sanitize ? SafeMarkup::checkPlain($account->label()) : $account->label();
-          $cacheablity_metadata = $cacheablity_metadata->merge(\Drupal\Core\Cache\CacheableMetadata::createFromObject($account));
+          $cacheability_metadata = $cacheability_metadata->merge(\Drupal\Core\Cache\CacheableMetadata::createFromObject($account));
           break;
 
         case 'created':
@@ -126,13 +126,13 @@
  *   - 'tokens'
  *   - 'data'
  *   - 'options'
- * @param \Drupal\Core\Cache\CacheableMetadata $cacheablity_metadata
+ * @param \Drupal\Core\Cache\CacheableMetadata $cacheability_metadata
  *   The cache metadata. In case you alter an existing token based upon
- *   cacheablity metadata, you need to take that here into account.
+ *   cacheability metadata, you need to take that into account.
  *
  * @see hook_tokens()
  */
-function hook_tokens_alter(array &$replacements, array $context, \Drupal\Core\Cache\CacheableMetadata &$cacheablity_metadata) {
+function hook_tokens_alter(array &$replacements, array $context, \Drupal\Core\Cache\CacheableMetadata &$cacheability_metadata) {
   $options = $context['options'];
 
   if (isset($options['langcode'])) {
diff -u b/core/modules/comment/src/Tests/CommentTokenReplaceTest.php b/core/modules/comment/src/Tests/CommentTokenReplaceTest.php
--- b/core/modules/comment/src/Tests/CommentTokenReplaceTest.php
+++ b/core/modules/comment/src/Tests/CommentTokenReplaceTest.php
@@ -92,7 +92,6 @@
     $cache_metadata = clone $base_cache_metadata;
     $metadata_tests['[comment:changed:since]'] = $cache_metadata->setCacheMaxAge(0);
     $cache_metadata = clone $base_cache_metadata;
-    debug($cache_metadata->addCacheTags(['comment:2'])->getCacheTags());
     $metadata_tests['[comment:parent:cid]'] = $cache_metadata->addCacheTags(['comment:1']);
     $metadata_tests['[comment:parent:title]'] = $cache_metadata;
     $cache_metadata = clone $base_cache_metadata;
diff -u b/core/modules/node/src/Tests/NodeTokenReplaceTest.php b/core/modules/node/src/Tests/NodeTokenReplaceTest.php
--- b/core/modules/node/src/Tests/NodeTokenReplaceTest.php
+++ b/core/modules/node/src/Tests/NodeTokenReplaceTest.php
@@ -17,7 +17,7 @@
  *
  * @group node
  */
-class NodeTokenReplaceTest extends TokenReplaceUnitTestBase {
+class 2523NodeTokenReplaceTest extends TokenReplaceUnitTestBase {
 
   /**
    * Modules to enable.
diff -u b/core/modules/system/src/Tests/System/TokenReplaceWebTest.php b/core/modules/system/src/Tests/System/TokenReplaceWebTest.php
--- b/core/modules/system/src/Tests/System/TokenReplaceWebTest.php
+++ b/core/modules/system/src/Tests/System/TokenReplaceWebTest.php
@@ -25,7 +25,7 @@
   public static $modules = ['token_test', 'filter', 'node'];
 
   /**
-   * Tests a token replacement on an actula website.
+   * Tests a token replacement on an actual website.
    */
   public function testTokens() {
     $node = $this->drupalCreateNode();
diff -u b/core/modules/system/tests/modules/token_test/token_test.info.yml b/core/modules/system/tests/modules/token_test/token_test.info.yml
--- b/core/modules/system/tests/modules/token_test/token_test.info.yml
+++ b/core/modules/system/tests/modules/token_test/token_test.info.yml
@@ -3,0 +4,3 @@
+dependencies:
+ - user
+ - node
diff -u b/core/modules/user/src/Tests/UserTokenReplaceTest.php b/core/modules/user/src/Tests/UserTokenReplaceTest.php
--- b/core/modules/user/src/Tests/UserTokenReplaceTest.php
+++ b/core/modules/user/src/Tests/UserTokenReplaceTest.php
@@ -9,7 +9,6 @@
 
 use Drupal\Component\Utility\SafeMarkup;
 use Drupal\Core\Cache\CacheableMetadata;
-use Drupal\Core\Datetime\Entity\DateFormat;
 use Drupal\language\Entity\ConfigurableLanguage;
 use Drupal\simpletest\WebTestBase;
 use Drupal\user\Entity\User;