feat(reporters): print import duration breakdown (#9105)

Author: sheremet-va

docs/.vitepress/style/main.css

@@ -37,31 +37,37 @@ button:focus:not(:focus-visible) {
 html:not(.dark) .custom-block.tip code {
   color: var(--vitest-custom-block-tip-code-text) !important;
 }
+
 html:not(.dark) .custom-block.info code {
   color: var(--vitest-custom-block-info-code-text) !important;
 }
+
 .custom-block.tip a:hover,
-.vp-doc .custom-block.tip a:hover > code {
+.vp-doc .custom-block.tip a:hover>code {
   color: var(--vp-c-brand-1) !important;
   opacity: 1;
 }
+
 .custom-block.info a:hover,
-.vp-doc .custom-block.info a:hover > code {
+.vp-doc .custom-block.info a:hover>code {
   color: var(--vp-c-brand-1) !important;
   opacity: 1;
 }
+
 html:not(.dark) .custom-block.info a:hover,
-html:not(.dark) .vp-doc .custom-block.info a:hover > code {
+html:not(.dark) .vp-doc .custom-block.info a:hover>code {
   color: var(--vitest-custom-block-info-code-text) !important;
   opacity: 1;
 }
+
 .custom-block.warning a:hover,
-.vp-doc .custom-block.warning a:hover > code {
+.vp-doc .custom-block.warning a:hover>code {
   color: var(--vp-c-warning-1) !important;
   opacity: 1;
 }
+
 .custom-block.danger a:hover,
-.vp-doc .custom-block.danger a:hover > code {
+.vp-doc .custom-block.danger a:hover>code {
   color: var(--vp-c-danger-1) !important;
   opacity: 1;
 }
@@ -70,6 +76,7 @@ html:not(.dark) .vp-doc .custom-block.info a:hover > code {
 :not(.dark) .title-icon {
   opacity: 1 !important;
 }
+
 .dark .title-icon {
   opacity: 0.67 !important;
 }
@@ -81,6 +88,7 @@ html:not(.dark) .vp-doc .custom-block.info a:hover > code {
 .vp-doc a {
   text-decoration-style: dotted;
 }
+
 .custom-block a:focus,
 .custom-block a:active,
 .custom-block a:hover,
@@ -92,7 +100,8 @@ html:not(.dark) .vp-doc .custom-block.info a:hover > code {
   text-decoration: underline;
 }
 
-.vp-doc th, .vp-doc td {
+.vp-doc th,
+.vp-doc td {
   padding: 6px 10px;
   border: 1px solid #8882;
 }
@@ -113,14 +122,17 @@ img.resizable-img {
 .VPTeamMembersItem.medium .profile .data .affiliation {
   min-height: unset;
 }
+
 .VPTeamMembersItem.medium .profile .data .desc {
   min-height: unset;
 }
+
 /* fix height ~ 2 lines of text: 3 cards per row */
 @media (min-width: 648px) {
   .VPTeamMembersItem.medium .profile .data .affiliation {
     min-height: 4rem;
   }
+
   .VPTeamMembersItem.medium .profile .data .desc {
     min-height: 4rem;
   }
@@ -130,6 +142,7 @@ img.resizable-img {
 .VPTeamMembersItem.small .profile .data .affiliation {
   min-height: 3rem;
 }
+
 .VPTeamMembersItem.small .profile .data .desc {
   min-height: 3rem;
 }
@@ -139,33 +152,40 @@ img.resizable-img {
   .VPTeamMembersItem.small .profile .data .affiliation {
     min-height: 4rem;
   }
+
   .VPTeamMembersItem.small .profile .data .desc {
     min-height: 4rem;
   }
 }
+
 /* fix height ~ 3 lines of text: 3 cards per row */
 @media (min-width: 815px) and (max-width: 875px) {
   .VPTeamMembersItem.small .profile .data .affiliation {
     min-height: 4rem;
   }
+
   .VPTeamMembersItem.small .profile .data .desc {
     min-height: 4rem;
   }
 }
+
 /* fix height ~ 3 lines of text: 2 cards per row */
 @media (max-width: 612px) {
   .VPTeamMembersItem.small .profile .data .affiliation {
     min-height: 4rem;
   }
+
   .VPTeamMembersItem.small .profile .data .desc {
     min-height: 4rem;
   }
 }
+
 /* fix height: one card per row */
 @media (max-width: 568px) {
   .VPTeamMembersItem.small .profile .data .affiliation {
     min-height: unset;
   }
+
   .VPTeamMembersItem.small .profile .data .desc {
     min-height: unset;
   }
@@ -176,3 +196,30 @@ img.resizable-img {
   transition: background-color 0.5s;
   display: inline-block;
 }
+
+/* credit goes to https://dylanatsmith.com/wrote/styling-the-kbd-element */
+html:not(.dark) kbd {
+  --kbd-color-background: #f7f7f7;
+  --kbd-color-border: #cbcccd;
+  --kbd-color-text: #222325;
+}
+
+kbd {
+  --kbd-color-background: #898b90;
+  --kbd-color-border: #3d3e42;
+  --kbd-color-text: #222325;
+
+  background-color: var(--kbd-color-background);
+  color: var(--kbd-color-text);
+  border-radius: 0.25rem;
+  border: 1px solid var(--kbd-color-border);
+  box-shadow: 0 2px 0 1px var(--kbd-color-border);
+  font-family: var(--font-family-sans-serif);
+  font-size: 0.75em;
+  line-height: 1;
+  min-width: 0.75rem;
+  text-align: center;
+  padding: 2px 5px;
+  position: relative;
+  top: -1px;
+}

docs/api/advanced/plugin.md

@@ -142,7 +142,7 @@ Define a generator that will be applied before hashing the cache key.
 
 Use this to make sure Vitest generates correct hash. It is a good idea to define this function if your plugin can be registered with different options.
 
-This is called only if [`experimental.fsModuleCache`](/config/experimental#fsmodulecache) is defined.
+This is called only if [`experimental.fsModuleCache`](/config/experimental#experimental-fsmodulecache) is defined.
 
 ```ts
 interface PluginOptions {

docs/api/advanced/test-module.md

@@ -120,3 +120,7 @@ interface ImportDuration {
   totalTime: number
 }
 ```
+
+## viteEnvironment <Version type="experimental">4.0.15</Version> <Experimental /> {#viteenvironment}
+
+This is a Vite's [`DevEnvironment`](https://vite.dev/guide/api-environment) that transforms all files inside of the test module.

docs/api/advanced/vitest.md

@@ -564,7 +564,7 @@ function getSeed(): number | null
 
 Returns the seed, if tests are running in a random order.
 
-## experimental_parseSpecification <Version>4.0.0</Version> <Badge type="warning">experimental</Badge> {#parsespecification}
+## experimental_parseSpecification <Version type="experimental">4.0.0</Version> <Experimental /> {#parsespecification}
 
 ```ts
 function experimental_parseSpecification(
@@ -595,7 +595,7 @@ Vitest will only collect tests defined in the file. It will never follow imports
 Vitest collects all `it`, `test`, `suite` and `describe` definitions even if they were not imported from the `vitest` entry point.
 :::
 
-## experimental_parseSpecifications <Version>4.0.0</Version> <Badge type="warning">experimental</Badge> {#parsespecifications}
+## experimental_parseSpecifications <Version type="experimental">4.0.0</Version> <Experimental /> {#parsespecifications}
 
 ```ts
 function experimental_parseSpecifications(
@@ -608,10 +608,67 @@ function experimental_parseSpecifications(
 
 This method will [collect tests](#parsespecification) from an array of specifications. By default, Vitest will run only `os.availableParallelism()` number of specifications at a time to reduce the potential performance degradation. You can specify a different number in a second argument.
 
-## experimental_clearCache <Version type="experimental">4.0.11</Version> <Badge type="warning">experimental</Badge> {#clearcache}
+## experimental_clearCache <Version type="experimental">4.0.11</Version> <Experimental /> {#clearcache}
 
 ```ts
 function experimental_clearCache(): Promise<void>
 ```
 
 Deletes all Vitest caches, including [`experimental.fsModuleCache`](/config/experimental#experimental-fsmodulecache).
+
+## experimental_getSourceModuleDiagnostic <Version type="experimental">4.0.15</Version> <Experimental /> {#getsourcemodulediagnostic}
+
+```ts
+export function experimental_getSourceModuleDiagnostic(
+  moduleId: string,
+  testModule?: TestModule,
+): Promise<SourceModuleDiagnostic>
+```
+
+::: details Types
+```ts
+export interface ModuleDefinitionLocation {
+  line: number
+  column: number
+}
+
+export interface SourceModuleLocations {
+  modules: ModuleDefinitionDiagnostic[]
+  untracked: ModuleDefinitionDiagnostic[]
+}
+
+export interface ModuleDefinitionDiagnostic {
+  start: ModuleDefinitionLocation
+  end: ModuleDefinitionLocation
+  startIndex: number
+  endIndex: number
+  url: string
+  resolvedId: string
+}
+
+export interface ModuleDefinitionDurationsDiagnostic extends ModuleDefinitionDiagnostic {
+  selfTime: number
+  totalTime: number
+  external?: boolean
+}
+
+export interface UntrackedModuleDefinitionDiagnostic {
+  url: string
+  resolvedId: string
+  selfTime: number
+  totalTime: number
+  external?: boolean
+}
+
+export interface SourceModuleDiagnostic {
+  modules: ModuleDefinitionDurationsDiagnostic[]
+  untrackedModules: UntrackedModuleDefinitionDiagnostic[]
+}
+```
+:::
+
+Returns module's diagnostic. If [`testModule`](/api/advanced/test-module) is not provided, `selfTime` and `totalTime` will be aggregated across all tests that were running the last time. If the module was not transformed or executed, the diagnostic will be empty.
+
+::: warning
+At the moment, the [browser](/guide/browser/) modules are not supported.
+:::

docs/config/experimental.md

@@ -137,3 +137,21 @@ export default defineConfig({
 ::: warning
 It's important that Node can process `sdkPath` content because it is not transformed by Vitest. See [the guide](/guide/open-telemetry) on how to work with OpenTelemetry inside of Vitest.
 :::
+
+## experimental.printImportBreakdown <Version type="experimental">4.0.15</Version> {#experimental-printimportbreakdown}
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Show import duration breakdown after tests have finished running. This option only works with [`default`](/guide/reporters#default), [`verbose`](/guide/reporters#verbose), or [`tree`](/guide/reporters#tree) reporters.
+
+- Self: the time it took to import the module, excluding static imports;
+- Total: the time it took to import the module, including static imports. Note that this does not include `transform` time of the current module.
+
+<img alt="An example of import breakdown in the terminal" src="/reporter-import-breakdown.png" />
+
+Note that if the file path is too long, Vitest will truncate it at the start until it fits 45 character limit.
+
+::: info
+[Vitest UI](/guide/ui#import-breakdown) shows a breakdown of imports automatically if at least one file took longer than 500 milliseconds to load. You can manually set this option to `false` to disable this.
+:::

docs/guide/open-telemetry.md

@@ -8,7 +8,7 @@ If enabled, Vitest integration generates spans that are scoped to your test's wo
 OpenTelemetry initialization increases the startup time of every test unless Vitest runs without [isolation](/config/isolate). You can see it as the `vitest.runtime.traces` span inside `vitest.worker.start`.
 :::
 
-To start using OpenTelemetry in Vitest, specify an SDK module path via [`experimental.openTelemetry.sdkPath`](/config/experimental#opentelemetry) and set `experimental.openTelemetry.enabled` to `true`. Vitest will automatically instrument the whole process and each individual test worker.
+To start using OpenTelemetry in Vitest, specify an SDK module path via [`experimental.openTelemetry.sdkPath`](/config/experimental#experimental-opentelemetry) and set `experimental.openTelemetry.enabled` to `true`. Vitest will automatically instrument the whole process and each individual test worker.
 
 Make sure to export the SDK as a default export, so that Vitest can flush the network requests before the process is closed. Note that Vitest doesn't automatically call `start`.
 

docs/guide/ui.md

@@ -52,3 +52,92 @@ npx vite preview --outDir ./html
 
 You can configure output with [`outputFile`](/config/#outputfile) config option. You need to specify `.html` path there. For example, `./html/index.html` is the default value.
 :::
+
+## Module Graph
+
+Module Graph's tab displays the module graph of the selected test file.
+
+::: info
+All of the provided images use [Zammad](https://github.com/zammad/zammad) repository as an example.
+:::
+
+<img alt="The module graph view" img-light src="/ui/light-module-graph.png">
+<img alt="The module graph view" img-dark src="/ui/dark-module-graph.png">
+
+If there are more than 50 modules, the module graph displays only the first two levels of the graph to reduce the visual clutter. You can always click on "Show Full Graph" icon to preview the full graph.
+
+<center>
+  <img alt="The 'Show Full Graph' button located close to the legend" img-light src="/ui/light-ui-show-graph.png">
+  <img alt="The 'Show Full Graph' button located close to the legend" img-dark src="/ui/dark-ui-show-graph.png">
+</center>
+
+::: warning
+Note that if your graph is too big, it may take some time before the node positions are stabilized.
+:::
+
+You can always restore the entry module graph by clicking on "Reset". To expand the module graph, right-click or hold <kbd>Shift</kbd> while clicking the node that interests you. It will display all nodes related to the selected one.
+
+By default, Vitest doesn't show the modules from `node_modules`. Usually, these modules are externalized. You can enable them by deselecting "Hide node_modules".
+
+### Module Info
+
+By left-clicking on the module node, you open the Module Info view.
+
+<img alt="The module info view for an inlined module" img-light src="/ui/light-module-info.png">
+<img alt="The module info view for an inlined module" img-dark src="/ui/dark-module-info.png">
+
+This view is separated into two parts. The top part shows the full module ID and some diagnostics about the module. If [`experimental.fsModuleCache`](/config/experimental#experimental-fsmodulecache) is enabled, there will be a "cached" or "not cached" badge. On the right you can see time diagnostics:
+
+- Self Time: the time it took to import the module, excluding static imports.
+- Total Time: the time it took to import the module, including static imports. Note that this does not include `transform` time of the current module.
+- Transform: the time it took to transform the module.
+
+If you opened this view by clicking on an import, you will also see a "Back" button at the start that will take you to the previous module.
+
+The bottom part depends on the module type. If the module is external, you will only see the source code of that file. You will not be able to traverse the module graph any further, and you won't see how long it took to import static imports.
+
+<img alt="The module info view for an external module" img-light src="/ui/light-module-info-external.png">
+<img alt="The module info view for an external module" img-dark src="/ui/dark-module-info-external.png">
+
+If the module was inlined, you will see three more windows:
+
+- Source: unchanged source code of the module
+- Transformed: the transformed code that Vitest executes using Vite's [module runner](https://vite.dev/guide/api-environment-runtimes#modulerunner)
+- Source Map (v3): source map mappings
+
+All static imports in the "Source" window show a total time it took to evaluate them by the current module. If the import was already evaluated in the module graph, it will show `0ms` because it is cached by that point.
+
+If the module took longer than 500 milliseconds to load, the time will be displayed in red. If the module took longer than 100 milliseconds, the time will be displayed in orange.
+
+You can click on an import source to jump into that module and traverse the graph further (note `./support/assertions/index.ts` below).
+
+<img alt="The module info view for an internal module" img-light src="/ui/light-module-info-traverse.png">
+<img alt="The module info view for an internal module" img-dark src="/ui/dark-module-info-traverse.png">
+
+::: warning
+Note that type-only imports are not executed at runtime and do not display a total duration. They also cannot be opened.
+:::
+
+If another plugin injects a module import during transformation, those imports will be displayed at the start of the module in gray colour (for example, modules injected by `import.meta.glob`). They also show the total time and can be traversed further.
+
+<img alt="The module info view for an internal module" img-light src="/ui/light-module-info-shadow.png">
+<img alt="The module info view for an internal module" img-dark src="/ui/dark-module-info-shadow.png">
+
+::: tip
+If you are developing a custom integration on top of Vitest, you can use [`vitest.experimental_getSourceModuleDiagnostic`](/api/advanced/vitest#getsourcemodulediagnostic) to retrieve this information.
+:::
+
+### Import Breakdown
+
+The Module Graph tab also provides an Import Breakdown with a list of modules that take the longest time to load (top 10 by default, but you can press "Show more" to load 10 more), sorted by Total Time.
+
+<img alt="Import breakdown with a list of top 10 modules that take the longest time to load" img-light src="/ui/light-import-breakdown.png">
+<img alt="Import breakdown with a list of top 10 modules that take the longest time to load" img-dark src="/ui/dark-import-breakdown.png">
+
+You can click on the module to see the Module Info. If the module is external, it will have the yellow color (the same color in the module graph).
+
+The breakdown shows a list of modules with self time, total time, and a percentage relative to the time it took to load the whole test file.
+
+The "Show Import Breakdown" icon will have a red color if there is at least one file that took longer than 500 milliseconds to load, and it will be orange if there is at least one file that took longer than 100 milliseconds.
+
+By default, Vitest shows the breakdown automatically if there is at least one module that took longer than 500 milliseconds to load. You can control the behaviour by setting the [`experimental.printImportBreakdown`](/config/experimental#experimental-printimportbreakdown) option.