class HelpTest

class HelpTest extends KernelTestBase {
  use BlockCreationTrait;
  use HttpKernelUiHelperTrait;
  use UserCreationTrait;
  
  /**
   * Modules to install.
   *
   * The help_test module implements hook_help() but does not provide a module
   * overview page. The help_page_test module has a page section plugin that
   * returns no links.
   *
   * @var array
   */
  protected static $modules = [
    'block',
    'block_content',
    'breakpoint',
    'editor',
    'filter',
    'help',
    'help_page_test',
    'help_test',
    'system',
    'user',
  ];
  
  /**
   * The admin user that will be created.
   *
   * @var \Drupal\user\Entity\User|false
   */
  protected $adminUser;
  
  /**
   * The anonymous user that will be created.
   *
   * @var \Drupal\user\Entity\User|false
   */
  protected $anyUser;
  
  /**
   * {@inheritdoc}
   */
  protected function setUp() : void {
    parent::setUp();
    $this->installEntitySchema('block');
    $this->installEntitySchema('block_content');
    $this->installEntitySchema('user');
    // Create users.
    $this->adminUser = $this->createUser([
      'access help pages',
      'view the administration theme',
      'administer permissions',
    ]);
    $this->anyUser = $this->createUser();
    $this->installConfig('system');
    $this->config('system.site')
      ->set('name', 'Drupal')
      ->save();
    $this->container
      ->get('theme_installer')
      ->install([
      'stark',
    ]);
    $this->config('system.theme')
      ->set('default', 'stark')
      ->save();
    $this->placeBlock('page_title_block');
    $this->placeBlock('help_block');
  }
  
  /**
   * Logs in users, tests help pages.
   */
  public function testHelp() : void {
    // Log in the root user to ensure as many admin links appear as possible on
    // the module overview pages.
    $this->setCurrentUser($this->createUser([
      'access help pages',
      'access administration pages',
    ]));
    $this->verifyHelp();
    // Log in the regular user.
    $this->setCurrentUser($this->anyUser);
    $this->verifyHelp(403);
    // Verify that introductory help text exists, goes for 100% module coverage.
    $this->setCurrentUser($this->adminUser);
    $this->drupalGet('admin/help');
    $this->assertSession()
      ->responseContains('For more information, refer to the help listed on this page or to the <a href="https://www.drupal.org/documentation">online documentation</a> and <a href="https://www.drupal.org/support">support</a> pages at <a href="https://www.drupal.org">drupal.org</a>.');
    // Verify that hook_help() section title and description appear.
    $this->assertSession()
      ->responseContains('<h2 id="hook-help">Module overviews</h2>');
    $this->assertSession()
      ->responseContains('<p>Module overviews are provided by modules. Overviews available for your installed modules:</p>');
    // Verify that an empty section is handled correctly.
    $this->assertSession()
      ->responseContains('<h2 id="empty-section">Empty section</h2>');
    $this->assertSession()
      ->responseContains('<p>This description should appear.</p>');
    $this->assertSession()
      ->pageTextContains('There is currently nothing in this section.');
    // Make sure links are properly added for modules implementing hook_help().
    foreach ($this->getModuleList() as $module => $name) {
      $this->assertSession()
        ->linkExists($name, 0, new FormattableMarkup('Link properly added to @name (admin/help/@module)', [
        '@module' => $module,
        '@name' => $name,
      ]));
    }
    // Ensure a module which does not provide a module overview page is handled
    // correctly.
    $module_name = \Drupal::service('extension.list.module')->getName('help_test');
    $this->clickLink($module_name);
    $this->assertSession()
      ->pageTextContains('No help is available for module ' . $module_name);
    // Verify that the order of topics is alphabetical by displayed module
    // name, by checking the order of some modules, including some that would
    // have a different order if it was done by machine name instead.
    $this->drupalGet('admin/help');
    $page_text = $this->getTextContent();
    $start = strpos($page_text, 'Module overviews');
    $pos = $start;
    $list = [
      'Block',
      'Block Content',
      'Breakpoint',
      'Text Editor',
    ];
    foreach ($list as $name) {
      $this->assertSession()
        ->linkExists($name);
      $new_pos = strpos($page_text, $name, $start);
      $this->assertGreaterThan($pos, $new_pos, "Order of {$name} is not correct on page");
      $pos = $new_pos;
    }
  }
  
  /**
   * Verifies the logged in user has access to the various help pages.
   *
   * @param int $response
   *   (optional) An HTTP response code. Defaults to 200.
   */
  protected function verifyHelp($response = 200) : void {
    $this->drupalGet('admin/index');
    $this->assertSession()
      ->statusCodeEquals($response);
    if ($response == 200) {
      $this->assertSession()
        ->pageTextContains('This page shows you all available administration tasks for each module.');
    }
    else {
      $this->assertSession()
        ->pageTextNotContains('This page shows you all available administration tasks for each module.');
    }
    $module_list = \Drupal::service('extension.list.module');
    foreach ($this->getModuleList() as $module => $name) {
      // View module help page.
      $this->drupalGet('admin/help/' . $module);
      $this->assertSession()
        ->statusCodeEquals($response);
      if ($response == 200) {
        $this->assertSession()
          ->titleEquals("{$name} | Drupal");
        $this->assertSession()
          ->elementTextEquals('css', 'h1', $name);
        $info = $module_list->getExtensionInfo($module);
        $admin_tasks = \Drupal::service('system.module_admin_links_helper')->getModuleAdminLinks($module);
        if ($module_permissions_link = \Drupal::service('user.module_permissions_link_helper')->getModulePermissionsLink($module, $info['name'])) {
          $admin_tasks["user.admin_permissions.{$module}"] = $module_permissions_link;
        }
        if (!empty($admin_tasks)) {
          $this->assertSession()
            ->pageTextContains($name . ' administration pages');
        }
        foreach ($admin_tasks as $task) {
          $this->assertSession()
            ->linkExists($task['title']);
          // Ensure there are no double escaped '&' or '<' characters.
          $this->assertSession()
            ->assertNoEscaped('&amp;');
          $this->assertSession()
            ->assertNoEscaped('&lt;');
          // Ensure there are no escaped '<' characters.
          $this->assertSession()
            ->assertNoEscaped('<');
        }
        // Ensure there are no double escaped '&' or '<' characters.
        $this->assertSession()
          ->assertNoEscaped('&amp;');
        $this->assertSession()
          ->assertNoEscaped('&lt;');
        // The help for CKEditor 5 intentionally has escaped '<' so leave this
        // iteration before the assertion below.
        if ($module === 'ckeditor5') {
          continue;
        }
        // Ensure there are no escaped '<' characters.
        $this->assertSession()
          ->assertNoEscaped('<');
      }
    }
  }
  
  /**
   * Gets the list of enabled modules that implement hook_help().
   *
   * @return array
   *   A list of enabled modules.
   */
  protected function getModuleList() : array {
    $modules = [];
    $module_data = $this->container
      ->get('extension.list.module')
      ->getList();
    \Drupal::moduleHandler()->invokeAllWith('help', function (callable $hook, string $module) use (&$modules, $module_data) : void {
      $modules[$module] = $module_data[$module]->info['name'];
    });
    return $modules;
  }

}