[AST] Test RecursiveASTVisitor's current traversal of templates.

[sammccall]

Summary

There are several logical inconsistencies and traps in the current traversal.

This doesn't fix any of them, but

• describes the general expectations of how templates should be traversed
• (mostly) exhaustively records current behavior as a baseline for changes
• lists the apparent bugs in current behavior

See https://github.com/clangd/clangd/issues/1034 for an example of reasonable
code that falls into one of the traps, and some discussion.

[hokein]

clang/unittests/Tooling/RecursiveASTVisitorTests/Templates.cpp

13

I think this is a very useful documentation about the RAV API, instead of staying in the test file, I would suggest moving it to the RAV.h file.

19

Conceptually, an instantiations create a specific {Class, Var}TemplateSpecializationDecl, functionDecl.

template <class T> void foo(T) { }
template void foo<char>(); // Line 2

For the statement on line 2 (called explicit instantiation definition I think)

• there is no corresponding node in the clang AST, this is a missing feature in clang
• it creates a FunctionDecl, that is void foo(char) { },

does the "declaration part" in the comment refer to the declaration part of the explicit instantiation definition (I think so), or the declaration part of the FunctionDecl void foo(char) {}? The same question to the definition, my understanding from the comment is the function body of the void foo(char) {}, which is {}.

We describe the expected behavior, but there are some bugs or unimplemented features in clang, which creates discrepancies. I think this is confusing and hard to follow, not sure how to do here (encoding a bunch of FIXMEs here is not good, not mentioning them at all is not good neither, can we mention only critical ones?)

[sammccall]

clang/unittests/Tooling/RecursiveASTVisitorTests/Templates.cpp

13

Good idea. I suppose it belongs on shouldVisitTemplateInstantiations().

19

Conceptually, an instantiations create a specific {Class, Var}TemplateSpecializationDecl, functionDecl.

template <class T> void foo(T) { }
template void foo<char>(); // Line 2

For the statement on line 2 (called explicit instantiation definition I think)

• there is no corresponding node in the clang AST, this is a missing feature in clang
• it creates a FunctionDecl, that is void foo(char) { },

This is a plausible explanation (for functions and variables, but not classes). I don't think it's the best model - I'd prefer to say that the instantiated decl *corresponds* to the explicit instantiation definition.

In this example there are three decls: the template, the templated decl, and the instantiation.
For functions these are {FunctionTemplateDecl, FunctionDecl, FunctionDecl}.
For variables these are {VarTemplateDecl, VarDecl, VarTemplateSpecializationDecl}
For classes these are {ClassTemplateDecl, CXXRecordDecl, ClassTemplateSpecializationDecl}.
(Sometimes in -dump-ast they appear multiple times, but there are only 3 distinct pointers).

There are inconsistencies here:

• function specializations don't have a distinct node type. I'm not sure this is terribly significant. (I suspect it's related to the fact they can't be partially specialized).
• class specializations have locations that point to the explicit instantiation where possible (primary location, template parameter locations etc), and the template body otherwise. Variable and function specializations point at the template always.
• in -dump-ast output it's inconsistent whether specializations are shown at the top level, under the template, or both. But I don't think there's any significant meaning behind this.

The second inconsistency (locations) is the closest to answering the question "do they correspond"?
Possible answers:

• specializations should correspond to the explicit instantiations, so function + var are deficient in not reporting the locations
• specializations should not correspond, and class specializations are buggy in reporting explicit instantiation locations
• class specializations should correspond to the explicit instantiations, but others not (this seems silly)

I think #1 is the most plausible here, especially given that the specializations do know (getTemplateSpecializationKind()) if they were produced from an explicit instantiation.

does the "declaration part" in the comment refer to the declaration part of the explicit instantiation definition (I think so), or the declaration part of the FunctionDecl void foo(char) {}? The same question to the definition, my understanding from the comment is the function body of the void foo(char) {}, which is {}.

This comment is talking about attributing AST nodes to source code, so it's talking about the FunctionDecl. By "declaration part" I mean the FunctionTypeLoc etc. I'll clarify this.

We describe the expected behavior, but there are some bugs or unimplemented features in clang, which creates discrepancies. I think this is confusing and hard to follow, not sure how to do here (encoding a bunch of FIXMEs here is not good, not mentioning them at all is not good neither, can we mention only critical ones?)

I think we should say "there are some bugs, see FIXMEs below".
The concepts are complicated and I think trying to mix them in with the implementation limitations will make a mess.

[sammccall]

Move the description of shouldVisitTemplateInstantiations() to RAV.

[nridge]

will leave approval to hokein, but LGTM

clang/include/clang/AST/RecursiveASTVisitor.h

172

nit: stray "of"

clang/unittests/Tooling/RecursiveASTVisitorTests/Templates.cpp

283

Is this a FIXME (body is traversed is an instantiation declaration)?

[sammccall]

Thought about this some more, and talked to @hokein offline.

I want to make sure there's consensus on "desired behavior" before documenting it, to avoid too much confusion.
https://discourse.llvm.org/t/template-representation-in-ast-and-rav-with-explicit-instantiations/60606

clang/unittests/Tooling/RecursiveASTVisitorTests/Templates.cpp

283

Possibly - it seems like a body shouldn't even exist, right? But maybe the instantiation is performed anyway if the definition is visible, I don't really know the semantics.

If it does exist, traversing it seems wrong: this is almost certainly a double-traversal of the body if there's also an instantiation definition for the same decl.

I'll look into it...

clang/include/clang/AST/RecursiveASTVisitor.h

 /// expressions, or other AST nodes where the visitor should customize
 /// behavior.  Most users only need to override Visit*.  Advanced
 /// users may override Traverse* and WalkUpFrom* to implement custom
 /// traversal strategies.  Returning false from one of these overridden
 /// functions will abort the entire traversal.
 ///
 /// By default, this visitor tries to visit every part of the explicit
 /// source code exactly once.  The default policy towards templates
-/// is to descend into the 'pattern' class or function body, not any
-/// explicit or implicit instantiations.  Explicit specializations
-/// are still visited, and the patterns of partial specializations
-/// are visited separately.  This behavior can be changed by
-/// overriding shouldVisitTemplateInstantiations() in the derived class
-/// to return true, in which case all known implicit and explicit
-/// instantiations will be visited at the same time as the pattern
-/// from which they were produced.
+/// is to descend into code that was written: typically the 'pattern'
+/// class or function body, but not to traverse instantiations.
+/// This can be changed by overriding shouldVisitTemplateInstantiations().
 ///
 /// By default, this visitor preorder traverses the AST. If postorder traversal
 /// is needed, the \c shouldTraversePostOrder method needs to be overridden
 /// to return \c true.
 template <typename Derived> class RecursiveASTVisitor {
 public:
   /// A queue used for performing data recursion over statements.
   /// Parameters involving this type are used to implement data
   /// recursion over Stmts and Exprs within this class, and should
   /// typically not be explicitly specified by derived classes.
   /// The bool bit indicates whether the statement has been traversed or not.
   typedef SmallVectorImpl<llvm::PointerIntPair<Stmt *, 1, bool>>
     DataRecursionQueue;
 
   /// Return a reference to the derived class.
   Derived &getDerived() { return *static_cast<Derived *>(this); }
 
-  /// Return whether this visitor should recurse into
-  /// template instantiations.
+  /// Return whether we should traverse of AST nodes that were created by
+  /// template instantiation, rather than by written code.
+  ///
+  /// When this is false (default), only written code is traversed:
+  /// - Primary template bodies are traversed: they are written code.
+  /// - User-defined specializations (partial or complete) are traversed too.
+  /// - Implicit instantiations are *not* traversed.
+  /// - Explicit instantiations should be partially traversed:
+  ///   * The node itself (e.g. VarTemplateSpecializationDecl) is visited
+  ///   * The written "head" (e.g. template args, function params) is traversed.
+  ///   * The instantiated "body" (e.g. var initializer, class body) is not.
+  ///
+  /// When this is true, primary template bodies, user-defined specializations,
+  /// and both implicit and explicit instantiations are fully travesred.
+  ///
+  /// FIXME: this is the intent, but there are inconsistencies.
+  /// See unittests/Tooling/RecursiveASTVisitorTests/Templates.cpp
   bool shouldVisitTemplateInstantiations() const { return false; }
 
   /// Return whether this visitor should recurse into the types of
   /// TypeLocs.
   bool shouldWalkTypesOfTypeLocs() const { return true; }
 
   /// Return whether this visitor should recurse into implicit
   /// code, e.g., implicit constructors and destructors.

clang/unittests/Tooling/CMakeLists.txt

add_clang_unittest(ToolingTests
   RecursiveASTVisitorTests/IntegerLiteral.cpp
   RecursiveASTVisitorTests/LambdaDefaultCapture.cpp
   RecursiveASTVisitorTests/LambdaExpr.cpp
   RecursiveASTVisitorTests/LambdaTemplateParams.cpp
   RecursiveASTVisitorTests/MemberPointerTypeLoc.cpp
   RecursiveASTVisitorTests/NestedNameSpecifiers.cpp
   RecursiveASTVisitorTests/ParenExpr.cpp
   RecursiveASTVisitorTests/TemplateArgumentLocTraverser.cpp
+  RecursiveASTVisitorTests/Templates.cpp
   RecursiveASTVisitorTests/TraversalScope.cpp
   RecursiveASTVisitorTestDeclVisitor.cpp
   RecursiveASTVisitorTestPostOrderVisitor.cpp
   RecursiveASTVisitorTestTypeLocVisitor.cpp
   RefactoringActionRulesTest.cpp
   RefactoringCallbacksTest.cpp
   RefactoringTest.cpp
   ReplacementsYamlTest.cpp

clang/unittests/Tooling/RecursiveASTVisitorTests/Templates.cpp

+//===- Templates.cpp ------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// This tests exactly which template-related declarations are traversed by
+// RecursiveASTVisitor in the default mode (written code only) and
+// shouldVisitTemplateInstantiations() mode.
+//
+// Because RecursiveASTVisitor should also be able to traverse arbitrary
+// subtrees, the nodes representing explicit instantiations should be partially
+// traversed when passed to TraverseDecl(). This is also tested.
+// (The historical behavior for functions with shouldVisitTI() off was:
+// explicit function instantiations were not visited at all, but if explicitly
+// passed to TraverseDecl() then the whole body was traversed).
+//
+//===----------------------------------------------------------------------===//
+
+#include "TestVisitor.h"
+#include "clang/Basic/Specifiers.h"
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+
+using namespace clang;
+
+namespace {
+
+// This RecursiveASTVisitor logs the traversal of template-related declarations,
+// as well as a few leaf nodes (so we can tell whether bodies are traversed).
+class TemplateVisitor : public TestVisitor<TemplateVisitor> {
+  using Base = TestVisitor;
+
+public:
+  bool Instantiations = false;
+  std::function<Decl *(ASTContext &)> ChooseTraversalRoot =
+      [](ASTContext &Ctx) { return Ctx.getTranslationUnitDecl(); };
+
+  bool shouldVisitTemplateInstantiations() { return Instantiations; }
+  bool shouldVisitImplicitCode() { return false; }
+
+  bool TraverseAST(ASTContext &Ctx) {
+    return TraverseDecl(ChooseTraversalRoot(Ctx));
+  }
+
+#define LOG_VISIT(NodeTy)                                                      \
+  bool Visit##NodeTy(NodeTy *N) {                                              \
+    addLog("Visit" #NodeTy);                                                   \
+    addNodeDetail(N);                                                          \
+    return Base::Visit##NodeTy(N);                                             \
+  }
+#define LOG_TRAVERSE(NodeTy)                                                   \
+  LOG_VISIT(NodeTy)                                                            \
+  bool Traverse##NodeTy(NodeTy *N) {                                           \
+    addLog("Traverse" #NodeTy);                                                \
+    ++Indent;                                                                  \
+    bool Ret = Base::Traverse##NodeTy(N);                                      \
+    --Indent;                                                                  \
+    return Ret;                                                                \
+  }
+  LOG_TRAVERSE(FunctionTemplateDecl)
+  LOG_TRAVERSE(ClassTemplateDecl)
+  LOG_TRAVERSE(VarTemplateDecl)
+  LOG_TRAVERSE(FunctionDecl)
+  LOG_TRAVERSE(CXXRecordDecl)
+  LOG_TRAVERSE(VarDecl)
+  LOG_TRAVERSE(ClassTemplateSpecializationDecl)
+  LOG_TRAVERSE(ClassTemplatePartialSpecializationDecl)
+  LOG_TRAVERSE(VarTemplateSpecializationDecl)
+  LOG_TRAVERSE(VarTemplatePartialSpecializationDecl)
+  LOG_VISIT(CompoundStmt)
+  LOG_VISIT(FieldDecl)
+  LOG_VISIT(BinaryOperator)
+#undef LOG_TRAVERSE
+#undef LOG_VISIT
+
+  std::string takeLog() {
+    std::string Result = llvm::join(Log, "\n");
+    Log.clear();
+    return Result;
+  }
+
+private:
+  template <typename T> void addNodeDetail(T) {}
+  void addNodeDetail(FunctionDecl *D) {
+    addDetail(D->getNameAsString());
+    if (D->getDescribedFunctionTemplate())
+      addDetail("Generic");
+    addDetail(D->getTemplateSpecializationKind());
+  }
+  void addNodeDetail(CXXRecordDecl *D) {
+    addDetail(D->getNameAsString());
+    if (D->getDescribedClassTemplate())
+      addDetail("Generic");
+    addDetail(D->getTemplateSpecializationKind());
+  }
+  void addNodeDetail(VarDecl *D) {
+    addDetail(D->getNameAsString());
+    if (D->getDescribedVarTemplate())
+      addDetail("Generic");
+    addDetail(D->getTemplateSpecializationKind());
+  }
+
+  void addDetail(TemplateSpecializationKind TSK) {
+    switch (TSK) {
+    case TSK_Undeclared:
+      break;
+    case TSK_ImplicitInstantiation:
+      addDetail("ImplicitInstantiation");
+      break;
+    case TSK_ExplicitSpecialization:
+      addDetail("ExplicitSpecialization");
+      break;
+    case TSK_ExplicitInstantiationDeclaration:
+      addDetail("ExplicitInstantiationDeclaration");
+      break;
+    case TSK_ExplicitInstantiationDefinition:
+      addDetail("ExplicitInstantiationDefinition");
+      break;
+    }
+  }
+
+  void addLog(llvm::StringRef Message) {
+    Log.emplace_back(2 * Indent, ' ');
+    Log.back().append(Message.begin(), Message.end());
+  }
+  void addDetail(llvm::StringRef Detail) {
+    Log.back().push_back(' ');
+    Log.back().append(Detail.begin(), Detail.end());
+  }
+  unsigned Indent = 0;
+  std::vector<std::string> Log;
+};
+
+void checkLog(llvm::StringRef Description, TemplateVisitor &Visitor,
+              llvm::StringRef Code, llvm::StringRef Expected) {
+  SCOPED_TRACE(Code);
+  EXPECT_TRUE(Visitor.runOver(Code, TemplateVisitor::Lang_CXX14));
+  EXPECT_EQ(Expected.trim(), Visitor.takeLog()) << Description;
+}
+
+TEST(RecursiveASTVisitor, VisitsFunctionTemplates) {
+  TemplateVisitor Visitor;
+  const llvm::StringRef Code = R"cpp(
+    // Primary template. Should be traversed.
+    template <int> int foo() { return 0; }
+    // Explicit specialization. Should be traversed.
+    template <> int foo<1>() { return 1; }
+    // Implicit instantiation. Should be traversed if instantiations are on.
+    int x = foo<2>();
+    // Explicit instantiation declaration. Head should be traversed (no body).
+    extern template int foo<3>();
+    // Explicit instantiation. Head traversed, body only with instantiations on.
+    template int foo<4>();
+  )cpp";
+
+  // FIXME: explicit instantiation decl/definition are missing.
+  checkLog("Default mode, without instantiations", Visitor, Code, R"(
+TraverseFunctionTemplateDecl
+  VisitFunctionTemplateDecl
+  TraverseFunctionDecl
+    VisitFunctionDecl foo Generic
+    VisitCompoundStmt
+TraverseFunctionDecl
+  VisitFunctionDecl foo ExplicitSpecialization
+  VisitCompoundStmt
+TraverseVarDecl
+  VisitVarDecl x
+)");
+
+  Visitor.Instantiations = true;
+  checkLog("With instantiations", Visitor, Code, R"(
+TraverseFunctionTemplateDecl
+  VisitFunctionTemplateDecl
+  TraverseFunctionDecl
+    VisitFunctionDecl foo Generic
+    VisitCompoundStmt
+  TraverseFunctionDecl
+    VisitFunctionDecl foo ImplicitInstantiation
+    VisitCompoundStmt
+  TraverseFunctionDecl
+    VisitFunctionDecl foo ExplicitInstantiationDeclaration
+  TraverseFunctionDecl
+    VisitFunctionDecl foo ExplicitInstantiationDefinition
+    VisitCompoundStmt
+TraverseFunctionDecl
+  VisitFunctionDecl foo ExplicitSpecialization
+  VisitCompoundStmt
+TraverseVarDecl
+  VisitVarDecl x
+)");
+
+  Visitor.Instantiations = false;
+  Visitor.ChooseTraversalRoot = [](ASTContext &Ctx) -> Decl * {
+    for (auto *D : Ctx.getTranslationUnitDecl()->decls()) {
+      if (auto *FTD = llvm::dyn_cast<FunctionTemplateDecl>(D)) {
+        for (auto *Spec : FTD->specializations())
+          if (Spec->getTemplateSpecializationKind() ==
+              clang::TSK_ExplicitInstantiationDefinition)
+            return Spec;
+      }
+    }
+    ADD_FAILURE() << "Could not find an explicit instantiation!";
+    return Ctx.getTranslationUnitDecl();
+  };
+  // FIXME: we should not visit the body, as instantiation traversals are off.
+  checkLog("Explicitly traversing an explicit instantiation", Visitor, Code, R"(
+TraverseFunctionDecl
+  VisitFunctionDecl foo ExplicitInstantiationDefinition
+  VisitCompoundStmt
+)");
+}
+
+TEST(RecursiveASTVisitor, VisitsClassTemplates) {
+  TemplateVisitor Visitor;
+  const llvm::StringRef Code = R"cpp(
+    // Primary template. Should be traversed.
+    template <class> class foo { int a; };
+    // Explicit specialization. Should be traversed.
+    template <> class foo<int> { int b; };
+    // Partial specialization. Should be traversed.
+    template <class T> class foo<T*> { int c; };
+    // Implicit instantiation. Should be traversed if instantiations are on.
+    foo<char> x;
+    // Explicit instantiation declaration. Head should be traversed (no body).
+    extern template class foo<short>;
+    // Explicit instantiation. Head traversed, body only with instantiations on.
+    template class foo<double>;
+  )cpp";
+
+  checkLog("Default mode, without instantiations", Visitor, Code, R"(
+TraverseClassTemplateDecl
+  VisitClassTemplateDecl
+  TraverseCXXRecordDecl
+    VisitCXXRecordDecl foo Generic
+    VisitFieldDecl
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitSpecialization
+  VisitClassTemplateSpecializationDecl
+  VisitFieldDecl
+TraverseClassTemplatePartialSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitSpecialization
+  VisitClassTemplateSpecializationDecl
+  VisitClassTemplatePartialSpecializationDecl
+  VisitFieldDecl
+TraverseVarDecl
+  VisitVarDecl x
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitInstantiationDeclaration
+  VisitClassTemplateSpecializationDecl
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitInstantiationDefinition
+  VisitClassTemplateSpecializationDecl
+)");
+
+  Visitor.Instantiations = true;
+  checkLog("With instantiations", Visitor, Code, R"(
+TraverseClassTemplateDecl
+  VisitClassTemplateDecl
+  TraverseCXXRecordDecl
+    VisitCXXRecordDecl foo Generic
+    VisitFieldDecl
+  TraverseClassTemplateSpecializationDecl
+    VisitCXXRecordDecl foo ImplicitInstantiation
+    VisitClassTemplateSpecializationDecl
+    VisitFieldDecl
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitSpecialization
+  VisitClassTemplateSpecializationDecl
+  VisitFieldDecl
+TraverseClassTemplatePartialSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitSpecialization
+  VisitClassTemplateSpecializationDecl
+  VisitClassTemplatePartialSpecializationDecl
+  VisitFieldDecl
+TraverseVarDecl
+  VisitVarDecl x
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitInstantiationDeclaration
+  VisitClassTemplateSpecializationDecl
+  VisitFieldDecl
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitInstantiationDefinition
+  VisitClassTemplateSpecializationDecl
+  VisitFieldDecl
+)");
+
+  Visitor.Instantiations = false;
+  Visitor.ChooseTraversalRoot = [](ASTContext &Ctx) -> Decl * {
+    for (auto *D : Ctx.getTranslationUnitDecl()->decls()) {
+      if (auto *Spec = llvm::dyn_cast<ClassTemplateSpecializationDecl>(D)) {
+        if (Spec->getTemplateSpecializationKind() ==
+            clang::TSK_ExplicitInstantiationDefinition)
+          return Spec;
+      }
+    }
+    ADD_FAILURE() << "Could not find an explicit instantiation!";
+    return Ctx.getTranslationUnitDecl();
+  };
+  checkLog("Explicitly traversing an explicit instantiation", Visitor, Code, R"(
+TraverseClassTemplateSpecializationDecl
+  VisitCXXRecordDecl foo ExplicitInstantiationDefinition
+  VisitClassTemplateSpecializationDecl
+)");
+}
+
+TEST(RecursiveASTVisitor, VisitsVarTemplates) {
+  TemplateVisitor Visitor;
+  const llvm::StringRef Code = R"cpp(
+    // Primary template. Should be traversed.
+    template <class T> float foo = 1 + 1;
+    // Explicit specialization. Should be traversed.
+    template <> float foo<int> = 2 + 2;
+    // Partial specialization. Should be traversed.
+    template <class T> float foo<T*> = 3 + 3;
+    // Implicit instantiation. Should be traversed if instantiations are on.
+    float x = foo<char>;
+    // Explicit instantiation declaration. Head should be traversed (no body).
+    extern template float foo<short>;
+    // Explicit instantiation. Head traversed, body only with instantiations on.
+    template float foo<double>;
+  )cpp";
+
+  // FIXME: explicit specialization's initializer should be traversed.
+  // FIXME: implicit instantiation should not be traversed.
+  checkLog("Default mode, without instantiations", Visitor, Code, R"(
+TraverseVarTemplateDecl
+  VisitVarTemplateDecl
+  TraverseVarDecl
+    VisitVarDecl foo Generic
+    VisitBinaryOperator
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitSpecialization
+  VisitVarTemplateSpecializationDecl
+TraverseVarTemplatePartialSpecializationDecl
+  VisitVarDecl foo ExplicitSpecialization
+  VisitVarTemplateSpecializationDecl
+  VisitVarTemplatePartialSpecializationDecl
+  VisitBinaryOperator
+TraverseVarDecl
+  VisitVarDecl x
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ImplicitInstantiation
+  VisitVarTemplateSpecializationDecl
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitInstantiationDeclaration
+  VisitVarTemplateSpecializationDecl
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitInstantiationDefinition
+  VisitVarTemplateSpecializationDecl
+)");
+
+  Visitor.Instantiations = true;
+  // FIXME: implicit instantiation is traversed twice.
+  // FIXME: implicit instantiation's initializer should be traversed.
+  // FIXME: explicit specialization's initializer should be traversed.
+  // FIXME: explicit instantiation's initializer should be traversed.
+  checkLog("With instantiations", Visitor, Code, R"(
+TraverseVarTemplateDecl
+  VisitVarTemplateDecl
+  TraverseVarDecl
+    VisitVarDecl foo Generic
+    VisitBinaryOperator
+  TraverseVarTemplateSpecializationDecl
+    VisitVarDecl foo ImplicitInstantiation
+    VisitVarTemplateSpecializationDecl
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitSpecialization
+  VisitVarTemplateSpecializationDecl
+TraverseVarTemplatePartialSpecializationDecl
+  VisitVarDecl foo ExplicitSpecialization
+  VisitVarTemplateSpecializationDecl
+  VisitVarTemplatePartialSpecializationDecl
+  VisitBinaryOperator
+TraverseVarDecl
+  VisitVarDecl x
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ImplicitInstantiation
+  VisitVarTemplateSpecializationDecl
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitInstantiationDeclaration
+  VisitVarTemplateSpecializationDecl
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitInstantiationDefinition
+  VisitVarTemplateSpecializationDecl
+)");
+
+  Visitor.Instantiations = false;
+  Visitor.ChooseTraversalRoot = [](ASTContext &Ctx) -> Decl * {
+    for (auto *D : Ctx.getTranslationUnitDecl()->decls()) {
+      if (auto *Spec = llvm::dyn_cast<VarTemplateSpecializationDecl>(D)) {
+        if (Spec->getTemplateSpecializationKind() ==
+            clang::TSK_ExplicitInstantiationDefinition)
+          return Spec;
+      }
+    }
+    ADD_FAILURE() << "Could not find an explicit instantiation!";
+    return Ctx.getTranslationUnitDecl();
+  };
+  checkLog("Explicitly traversing an explicit instantiation", Visitor, Code, R"(
+TraverseVarTemplateSpecializationDecl
+  VisitVarDecl foo ExplicitInstantiationDefinition
+  VisitVarTemplateSpecializationDecl
+)");
+}
+
+} // end anonymous namespace

clang/unittests/Tooling/TestVisitor.h

protected:
   }
 
   class FindConsumer : public ASTConsumer {
   public:
     FindConsumer(TestVisitor *Visitor) : Visitor(Visitor) {}
 
     void HandleTranslationUnit(clang::ASTContext &Context) override {
       Visitor->Context = &Context;
-      Visitor->TraverseDecl(Context.getTranslationUnitDecl());
+      Visitor->getDerived().TraverseAST(Context);
     }
 
   private:
     TestVisitor *Visitor;
   };
 
   class TestAction : public ASTFrontendAction {
   public: