HelpTopicsSyntaxTest.php

<?php

declare (strict_types=1);
namespace Drupal\Tests\help\Kernel;

use Drupal\Component\FrontMatter\FrontMatter;
use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\Extension\ExtensionLifecycle;
use Drupal\Core\Template\TwigNodeTrans;
use Drupal\help\HelpTopicDiscovery;
use Drupal\KernelTests\KernelTestBase;
use PHPUnit\Framework\AssertionFailedError;
use PHPUnit\Framework\Attributes\Group;
use PHPUnit\Framework\Attributes\RunTestsInSeparateProcesses;
use PHPUnit\Framework\ExpectationFailedException;
use Symfony\Component\DependencyInjection\Definition;
use Twig\Environment;
use Twig\Extension\AbstractExtension;
use Twig\Node\Expression\AbstractExpression;
use Twig\Node\Node;
use Twig\Node\PrintNode;
use Twig\Node\SetNode;
use Twig\Node\TextNode;
use Twig\NodeVisitor\NodeVisitorInterface;

/**
 * Verifies that all core Help topics can be rendered and comply with standards.
 */
class HelpTopicsSyntaxTest extends KernelTestBase implements NodeVisitorInterface {
  
  /**
   * Delimiter placed around single translated chunks.
   */
  public const DELIMITER = 'Not Likely To Be Inside A Template';
  
  /**
   * {@inheritdoc}
   */
  protected static $modules = [
    'system',
    'user',
    'file',
    'language',
    'locale',
    'help',
  ];
  
  /**
   * The special processing choice for topic rendering.
   */
  protected ?string $manner;
  
  /**
   * The number of chunks that were processed.
   */
  protected int $maxChunk;
  
  /**
   * A specific chunk number to return.
   */
  protected int $returnChunk;
  
  /**
   * {@inheritdoc}
   */
  public function register(ContainerBuilder $container) : void {
    parent::register($container);
    // Add a twig extension that registers this test class as a node visitor.
    $extension = new class ($this) extends AbstractExtension {
      public function __construct(protected readonly NodeVisitorInterface $nodeVisitor) {
      }
      
      /**
       * {@inheritdoc}
       */
      public function getNodeVisitors() : array {
        return [
          $this->nodeVisitor,
        ];
      }

};
    $definition = new Definition(get_class($extension));
    $definition->addTag('twig.extension', [
      'priority' => 500,
    ]);
    $definition->addArgument($this);
    $container->setDefinition('help_test_twig.extension', $definition);
  }
  
  /**
   * Tests that all Core help topics can be rendered and have good syntax.
   */
  public function testHelpTopics() : void {
    $directories = $this->listDirectories('module');
    $directories += $this->listDirectories('theme');
    $directories += $this->listDirectories('profile');
    $directories['core'] = \Drupal::root() . '/core/help_topics';
    $directories['bad_help_topics'] = \Drupal::service('extension.list.module')->getPath('help_topics_test') . '/bad_help_topics/syntax/';
    // Filter out directories outside of core. If you want to run this test
    // on a contrib/custom module, remove the next line.
    $directories = array_filter($directories, function ($directory) {
      return str_starts_with($directory, 'core');
    });
    // Verify that a few key modules, themes, and profiles are listed, so that
    // we can be certain our directory list is complete and we will be testing
    // all existing help topics. If these lines in the test fail in the future,
    // it is probably because something we chose to list here is being removed.
    // Substitute another item of the same type that still exists, so that this
    // test can continue.
    $this->assertArrayHasKey('system', $directories, 'System module is being scanned');
    $this->assertArrayHasKey('help', $directories, 'Help module is being scanned');
    $this->assertArrayHasKey('claro', $directories, 'Claro theme is being scanned');
    $this->assertArrayHasKey('standard', $directories, 'Standard profile is being scanned');
    $definitions = (new HelpTopicDiscovery($directories))->getDefinitions();
    $this->assertGreaterThan(0, count($definitions), 'At least 1 topic was found');
    // Test each topic for compliance with standards, or for failing in the
    // right way.
    foreach (array_keys($definitions) as $id) {
      if (str_starts_with($id, 'bad_help_topics.')) {
        $this->verifyBadTopic($id, $definitions);
      }
      else {
        $this->verifyTopic($id, $definitions);
      }
    }
  }
  
  /**
   * Verifies rendering and standards compliance of one help topic.
   *
   * @param string $id
   *   ID of the topic to verify.
   * @param array $definitions
   *   Array of all topic definitions, keyed by ID.
   */
  protected function verifyTopic(string $id, array|\ArrayAccess $definitions) : void {
    $definition = $definitions[$id];
    $this->manner = NULL;
    // Verify that all the related topics exist. Also check to see if any of
    // them are top-level (we will need that in the next section).
    $has_top_level_related = FALSE;
    if (isset($definition['related'])) {
      foreach ($definition['related'] as $related_id) {
        $this->assertArrayHasKey($related_id, $definitions, 'Topic ' . $id . ' is only related to topics that exist: ' . $related_id);
        $has_top_level_related = $has_top_level_related || !empty($definitions[$related_id]['top_level']);
      }
    }
    // Verify this is either top-level or related to a top-level topic.
    $this->assertTrue(!empty($definition['top_level']) || $has_top_level_related, 'Topic ' . $id . ' is either top-level or related to at least one other top-level topic');
    // Verify that the label is not empty.
    $this->assertNotEmpty($definition['label'], 'Topic ' . $id . ' has a non-empty label');
    // Test the syntax and contents of the Twig file (without the front
    // matter, which is tested in other ways above). We need to render the
    // template several times with variations, so read it in once.
    $template = file_get_contents($definition[HelpTopicDiscovery::FILE_KEY]);
    $template_text = FrontMatter::create($template)->getContent();
    // Verify that the body is not empty and is valid HTML.
    $text = $this->renderHelpTopic($template_text, 'bare_body');
    $this->assertNotEmpty($text, 'Topic ' . $id . ' contains some text outside of front matter');
    $this->validateHtml($text, $id);
    $this->assertGreaterThanOrEqual(0, $this->maxChunk, 'Topic ' . $id . ' has at least one translated chunk');
    // Verify that each chunk of the translated text is locale-safe and
    // valid HTML.
    $chunk_num = 0;
    $number_checked = 0;
    while ($chunk_num <= $this->maxChunk) {
      $chunk_str = $id . ' section ' . $chunk_num;
      // Render the topic, asking for just one chunk, and extract the chunk.
      // Note that some chunks may not actually get rendered, if they are inside
      // set statements, because we skip rendering variable output.
      $this->returnChunk = $chunk_num;
      $text = $this->renderHelpTopic($template_text, 'translated_chunk');
      $matches = [];
      $matched = preg_match('|' . self::DELIMITER . '(.*)' . self::DELIMITER . '|', $text, $matches);
      if ($matched) {
        $number_checked++;
        $text = $matches[1];
        $this->assertNotEmpty($text, 'Topic ' . $chunk_str . ' contains text');
        // Verify the chunk is OK.
        $this->assertTrue(locale_string_is_safe($text), 'Topic ' . $chunk_str . ' translatable string is locale-safe');
        $this->validateHtml($text, $chunk_str);
      }
      $chunk_num++;
    }
    $this->assertGreaterThan(0, $number_checked, 'Tested at least one translated chunk in ' . $id);
    // Validate the HTML in the body with the translated text replaced by a
    // dummy string, to verify that HTML syntax is not partly in and partly out
    // of the translated text.
    $text = $this->renderHelpTopic($template_text, 'replace_translated');
    $this->validateHtml($text, $id);
    // Verify that if we remove all the translated text, whitespace, and
    // HTML tags, there is nothing left (that is, all text is translated).
    $text = preg_replace('|\\s+|', '', $this->renderHelpTopic($template_text, 'remove_translated'));
    $this->assertEmpty($text, 'Topic ' . $id . ' Twig file has all of its text translated');
    // Verify that the Twig url() function was not used.
    $this->assertStringNotContainsString('url(', $template, 'Topic ' . $id . ' appears to use the url() function. Replace with help_topic_link() or help_topic_route(). See https://drupal.org/node/3074421');
  }
  
  /**
   * Validates the HTML and header hierarchy for topic text.
   *
   * @param string $body
   *   Body text to validate.
   * @param string $id
   *   ID of help topic (for error messages).
   */
  protected function validateHtml(string $body, string $id) : void {
    $doc = new \DOMDocument();
    $doc->strictErrorChecking = TRUE;
    $doc->validateOnParse = FALSE;
    libxml_use_internal_errors(TRUE);
    libxml_clear_errors();
    if (!$doc->loadXML('<html><body>' . $body . '</body></html>')) {
      foreach (libxml_get_errors() as $error) {
        $this->fail('Topic ' . $id . ' fails HTML validation: ' . $error->message);
      }
    }
    // Check for headings hierarchy.
    $levels = [
      1,
      2,
      3,
      4,
      5,
      6,
    ];
    foreach ($levels as $level) {
      $num_headings[$level] = $doc->getElementsByTagName('h' . $level)->length;
      if ($level == 1) {
        $this->assertSame(0, $num_headings[1], 'Topic ' . $id . ' has no H1 tag');
        // Set num_headings to 1 for this level, so the rest of the hierarchy
        // can be tested using simpler code.
        $num_headings[1] = 1;
      }
      else {
        // We should either not have this heading, or if we do have one at this
        // level, we should also have the next-smaller level. That is, if we
        // have an h3, we should have also had an h2.
        $this->assertTrue($num_headings[$level - 1] > 0 || $num_headings[$level] == 0, 'Topic ' . $id . ' has the correct H2-H6 heading hierarchy');
      }
    }
  }
  
  /**
   * Verifies that a bad topic fails in the expected way.
   *
   * @param string $id
   *   ID of the topic to verify. It should start with "bad_help_topics.".
   * @param array $definitions
   *   Array of all topic definitions, keyed by ID.
   */
  protected function verifyBadTopic(string $id, array $definitions) : void {
    $bad_topic_type = substr($id, 16);
    // Topics should fail verifyTopic() in specific ways.
    $found_error = FALSE;
    try {
      $this->verifyTopic($id, $definitions);
    } catch (ExpectationFailedException|AssertionFailedError $e) {
      $found_error = TRUE;
      $message = $e->getMessage();
      switch ($bad_topic_type) {
        case 'related':
          $this->assertStringContainsString('only related to topics that exist', $message);
          break;

        case 'bad_html':
        case 'bad_html2':
        case 'bad_html3':
          $this->assertStringContainsString('Opening and ending tag mismatch', $message);
          break;

        case 'top_level':
          $this->assertStringContainsString('is either top-level or related to at least one other top-level topic', $message);
          break;

        case 'empty':
          $this->assertStringContainsString('contains some text outside of front matter', $message);
          break;

        case 'translated':
          $this->assertStringContainsString('Twig file has all of its text translated', $message);
          break;

        case 'locale':
          $this->assertStringContainsString('translatable string is locale-safe', $message);
          break;

        case 'h1':
          $this->assertStringContainsString('has no H1 tag', $message);
          break;

        case 'hierarchy':
          $this->assertStringContainsString('has the correct H2-H6 heading hierarchy', $message);
          break;

        case 'url_func_used':
          $this->assertStringContainsString('appears to use the url() function', $message);
          break;

        default:
          // This was an unexpected error.
          throw $e;
      }
    }
    if (!$found_error) {
      $this->fail('Bad help topic ' . $bad_topic_type . ' did not fail as expected');
    }
  }
  
  /**
   * Lists the extension help topic directories of a certain type.
   *
   * @param string $type
   *   The type of extension to list: module, theme, or profile.
   *
   * @return string[]
   *   An array of all of the help topic directories for this type of
   *   extension, keyed by extension short name.
   */
  protected function listDirectories($type) {
    $directories = [];
    // Find the extensions of this type, even if they are not installed, but
    // excluding test ones.
    $lister = \Drupal::service('extension.list.' . $type);
    foreach ($lister->getAllAvailableInfo() as $name => $info) {
      // Skip obsolete and deprecated modules.
      if ($info[ExtensionLifecycle::LIFECYCLE_IDENTIFIER] === ExtensionLifecycle::OBSOLETE || $info[ExtensionLifecycle::LIFECYCLE_IDENTIFIER] === ExtensionLifecycle::DEPRECATED) {
        continue;
      }
      $path = $lister->getPath($name);
      // You can tell test modules because they are in package 'Testing', but
      // test themes are only known by being found in test directories. So...
      // exclude things in test directories.
      if (!str_contains($path, '/tests') && !str_contains($path, '/testing')) {
        $directories[$name] = $path . '/help_topics';
      }
    }
    return $directories;
  }
  
  /**
   * Renders a help topic in a special manner.
   *
   * @param string $content
   *   Template text, without the front matter.
   * @param string $manner
   *   The special processing choice for topic rendering.
   *
   * @return string
   *   The rendered topic.
   */
  protected function renderHelpTopic(string $content, string $manner) : string {
    // Set up the special variables for rendering.
    $this->manner = $manner;
    $this->maxChunk = -1;
    // Add a random comment to the end, to thwart caching, and render. We need
    // the HelpTestTwigNodeVisitor class to hit it each time we render.
    $build = [
      '#type' => 'inline_template',
      '#template' => $content . "\n{# " . rand() . " #}",
    ];
    return (string) \Drupal::service('renderer')->renderInIsolation($build);
  }
  
  /**
   * {@inheritdoc}
   */
  public function enterNode(Node $node, Environment $env) : Node {
    return $node;
  }
  
  /**
   * {@inheritdoc}
   */
  public function leaveNode(Node $node, Environment $env) : ?Node {
    if (!$this->manner) {
      return $node;
    }
    // For all special processing, we want to remove variables, set statements,
    // and assorted Twig expression calls (if, do, etc.).
    if ($node instanceof SetNode || $node instanceof PrintNode || $node instanceof AbstractExpression) {
      return NULL;
    }
    if ($node instanceof TwigNodeTrans) {
      // Count the number of translated chunks.
      $this->maxChunk++;
      if ($this->manner == 'remove_translated') {
        // Remove all translated text.
        return NULL;
      }
      elseif ($this->manner == 'replace_translated') {
        // Replace with a dummy string.
        $node = new TextNode('dummy', 0);
      }
      elseif ($this->manner == 'translated_chunk') {
        // Return the text only if it's the next chunk we're supposed to return.
        // Add a wrapper, because non-translated nodes will still be returned.
        if ($this->maxChunk == $this->returnChunk) {
          return new TextNode(static::DELIMITER . $this->extractText($node) . static::DELIMITER, 0);
        }
        else {
          return NULL;
        }
      }
    }
    if ($this->manner == 'remove_translated' && $node instanceof TextNode) {
      // For this processing, we also want to remove all HTML tags and
      // whitespace from TextNodes.
      $text = $node->getAttribute('data');
      $text = strip_tags($text);
      $text = preg_replace('|\\s+|', '', $text);
      return new TextNode($text, 0);
    }
    return $node;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getPriority() : int {
    return -100;
  }
  
  /**
   * Extracts the text from a translated text object.
   *
   * @param \Drupal\Core\Template\TwigNodeTrans $node
   *   Translated text node.
   *
   * @return string
   *   Text in the node.
   */
  protected function extractText(TwigNodeTrans $node) : string {
    // Extract the singular/body and optional plural text from the
    // TwigNodeTrans object.
    $bodies = $node->getNode('body');
    if (!count($bodies)) {
      $bodies = [
        $bodies,
      ];
    }
    if ($node->hasNode('plural')) {
      $plural = $node->getNode('plural');
      if (!count($plural)) {
        $bodies[] = $plural;
      }
      else {
        foreach ($plural as $item) {
          $bodies[] = $item;
        }
      }
    }
    // Extract the text from each component of the singular/plural strings.
    $text = '';
    foreach ($bodies as $body) {
      if ($body->hasAttribute('data')) {
        $text .= $body->getAttribute('data');
      }
    }
    return trim($text);
  }

}