hook_theme_suggestions_hook_alter() not working for Views

Question

I'm trying to create a custom template for a view page in Drupal 8.3.x. It's going in a custom theme, and needs to be a view-level template (so not page- or node-).

I've been fighting with it for a while and figured it might be an issue with the specific name, so I've made the code as sparse as possible - still no luck.

I have the following code in mytheme.theme:

function mytheme_theme_suggestions_views_view_alter(array &$suggestions, array $variables) {
  $suggestions[] = 'test_template';
}

And the following file structure:

- mytheme
  ~ templates
    * test-template.html.twig
  ~ mytheme.theme
  ~ mytheme.info.yml
  ~ ... etc.

I know that the theme_suggestions alter function is working properly; I have Twig debugging enabled, and when I pull up my site and look at the code, I can see the following: (note the "X" next to views-view.html.twig showing that as the currently used Twig file)

<!-- FILE NAME SUGGESTIONS:
   * test-template.html.twig
   x views-view.html.twig
-->

So it's adding the suggestion. And the template file is named correctly. I know it's not a directory issue, because I have other .html.twig files in that /templates/ folder that are working correctly.

Does anyone know why the file name suggestion is working, but the matching file isn't?

---

Edit: Kevin pointed out a possible duplicate ticket in the comment below. That's only half-related. It does solve the symptom in this particular example - I have been able to pull in one of the templates mentioned here, and it works for this case.

However, the title of the ticket and general issue still holds. I can't get the hook_theme_suggestions_hook_alter() to work with my custom theme_suggestion / template. While it turns out the view I used as my example could be solved another way, there are other instances where that won't be the case.

Answer 1

Found the solution. As it turns out, for some reason Drupal doesn't play nicely with custom theme suggestions starting with a word + single dash.

I updated my HOOK_theme_suggestions_HOOK_alter() function to include $suggestions[] = 'test__template'; (with 2 underscores between the words) and updated my template name to test--template.html.twig (with 2 dashes to match the 2 underscores), and everything works as expected.