Enhance output config support (#1119)

* fix auto-focus issue; adding more diagnosis messages; clean up dead files

* prepare for release 6.2.2

* make conflict warning message non-modal and more consistent with the rest of the doc

* updated release note

Author: connectdotz

README.md

@@ -26,7 +26,7 @@ You can see the full [features](#features) and learn more details in the [How-To
 Happy testing!
 
 ## Releases 
-- **Current** ([v6.2.1](https://github.com/jest-community/vscode-jest/releases/tag/v6.2.1)): [release note](release-notes/release-note-v6.md#v621)
+- **Current** ([v6.2.2](https://github.com/jest-community/vscode-jest/releases/tag/v6.2.2)): [release note](release-notes/release-note-v6.md#v622)
 - **Previous** ([v5.2.3](https://github.com/jest-community/vscode-jest/releases/tag/v5.2.3)): [release note](release-notes/release-note-v5.x.md#v523)
 
 
@@ -348,7 +348,7 @@ for example:
 
 #### outputConfig
 
-The `outputConfig` controls the Jest output experience by specifying when and where to create, display, and clear the output content. It supports 2 output panels: `TEST RESULTS` and `TERMINAL`. The `TEST RESULTS` panel displays test results in the order they were run, while the `TERMINAL` panel organizes outputs by workspace folder. `TERMINAL` panel also contains the non-test run outputs, such as [quick-fix link](#quick-fix-chooser), extension auto-config info and tips. 
+The `outputConfig` controls the Jest output experience by specifying when and where to create, display, and clear the output content. It supports 2 output panels: `TEST RESULTS` and `TERMINAL`. The `TEST RESULTS` panel displays test results in the order they were run, while the `TERMINAL` panel organizes outputs by workspace folder. `TERMINAL` panel also contains the non-test run outputs, such as [quick-fix link](#quick-fix-chooser), extension auto-config info, and tips. 
 
 **Type Definitions**
 ```ts
@@ -387,8 +387,8 @@ This setting can be one of the predefined types or a custom object.
     4. "none": Do not clear any panel. (default)
     (_**Note**: As of the current version, the testing framework does not support the clearing of the "TEST RESULTS" panel without side effects. The closest available command also clears all test item statuses, which may not be desirable. We are aware of this limitation and will raise the issue with the VS Code team._)
 
-**Handling Conflicts with "TEST RESULTS" panel**
 <a id="outputconfig-conflict"></a>
+**Handling Conflicts with "TEST RESULTS" panel**
 
 _The Problem_
 
@@ -404,14 +404,25 @@ _Further Customization_
 
 However, if you prefer "TEST RESULTS" and "TERMINAL" panels to behave differently and don't mind managing 2 settings yourself, you could play with different combinations. 
 
-For instance, if `"testing.openTesting"` is set to `"openOnTestFailure"`, and you want your terminal panel to still reveal when any tests run, your setting would look like this: `"jest.outputConfig": {revealWithFocus: "test-results"}` 
+For instance, if `"testing.openTesting"` is set to `"openOnTestFailure"`, and you want your terminal panel to still reveal when any tests run, your setting would look like this: `"jest.outputConfig": {revealWithFocus: "terminal"}`.  
+
+_Validation and Diagnosis_
+
+The extension features output config diagnosis information in the jest terminal, as well as the built-in conflict detection and quick fixes to assist with the transition.
+
+<a id="outputconfig-issues"></a>
+**Common Issues**
 
-_Built-in Validation_
+Upon upgrading to v6.2, some users, frequently with auto run modes (e.g., 'watch', 'on-save'), might experience frequent "TEST RESULTS" panel automatically grabbing focus whenever files are saved or tests are run.
 
-The extension also features built-in conflict detection and quick fixes to assist.
+This is due to the extension generates a default `jest.outputConfig`, if none is existing in your settings, to match the existing `testing.openTesting` setting, which defaults to `"openOnTestStart"`. If this is not your desired output experience, you can easily disable `testing.openTesting` in your settings.json: 
+```json
+"testing.openTesting": "neverOpen"
+```
+Then use the `jest.outputConfig` to find-tune the output experience you prefer.
 
 **Examples**
-- Choose a passive output experience that is identical to the previous version.
+- Choose a passive output experience that is identical to the previous version: no automatic focus switch, no automatic clear.
   ```json
   "testing.openTesting": "neverOpen",
   "jest.outputConfig": "neutral"
@@ -421,20 +432,17 @@ The extension also features built-in conflict detection and quick fixes to assis
   "testing.openTesting": "neverOpen",
   "jest.outputConfig": "terminal-based"
   ```
-- Choose a test-results-based experience and switch focus to it when test fails.
+- Choose a test-results-based experience and switch focus to it when test run starts.
   ```json
   "testing.openTesting": "neverOpen",
-  "jest.outputConfig": {
-    "revealOn": "error",
-    "revealWithFocus": "test-results",
-  }
+  "jest.outputConfig": "test-results-based"
   ```
-   alternatively:
+- Choose a test-results-based experience and switch focus to it when test fails.
   ```json
-  "testing.openTesting": "openOnTestFailure",
+  "testing.openTesting": "neverOpen",
   "jest.outputConfig": {
     "revealOn": "error",
-    "revealWithFocus": "test-results"
+    "revealWithFocus": "test-results",
   }
   ```
 - Clear the terminal output on each run but do not automatically switch focus to any panel.
@@ -556,10 +564,11 @@ While the concepts of performance and automation are generally clear, "completen
 2. If you modify the source or test code, potential failures in other tests may remain hidden until they are explicitly run.
 3. Tests bearing dynamic names, like those using test.each with variables or template literals, won't be translated. As a result, they must be executed through higher-level constructs, such as describe blocks with static names or entire test suites.
 
-
-<a id="runmode-migration"></a>
-**Migration Guide**
-Starting from v6.1.0, if no runMode is defined in settings.json, the extension will automatically generate one using legacy settings (`autoRun`, `showCoverageOnLoad`). To migrate, simply use the `"Jest: Save Current RunMode"` command from the command palette to update the setting, then remove the deprecated settings.
+> [!NOTE] 
+> <a id="runmode-migration"></a>
+> **Migration Guide**
+> 
+> Starting from v6.1.0, if no runMode is defined in settings.json, the extension will automatically generate one using legacy settings (`autoRun`, `showCoverageOnLoad`). To migrate, simply use the `"Jest: Save Current RunMode"` command from the command palette to update the setting, then remove the deprecated settings.
 
 ---
 

package.json

@@ -2,7 +2,7 @@
   "name": "vscode-jest",
   "displayName": "Jest",
   "description": "Use Facebook's Jest With Pleasure.",
-  "version": "6.2.1",
+  "version": "6.2.2",
   "publisher": "Orta",
   "engines": {
     "vscode": "^1.68.1"
@@ -406,6 +406,10 @@
         "command": "io.orta.jest.save-output-config",
         "title": "Jest: Save Current Output Config"
       },
+      {
+        "command": "io.orta.jest.disable-auto-focus",
+        "title": "Jest: Disable Auto Focus Test Output"
+      },
       {
         "command": "io.orta.jest.run-all-tests",
         "title": "Jest: Run All Tests"

release-notes/release-note-v6.md

@@ -3,13 +3,15 @@
 Release Notes <!-- omit in toc --> 
 ---
 
-- [v6.2.1](#v621)
+- [v6.2.2](#v622)
   - [CHANGELOG](#changelog)
+- [v6.2.1](#v621)
+  - [CHANGELOG](#changelog-1)
 - [v6.2.0](#v620)
   - [New Features Summary](#new-features-summary)
   - [Bug Fixes and Technical Debt Reduction](#bug-fixes-and-technical-debt-reduction)
   - [Breaking Changes](#breaking-changes)
-  - [CHANGELOG](#changelog-1)
+  - [CHANGELOG](#changelog-2)
 - [v6.1 (pre-release)](#v61-pre-release)
   - [Main Features](#main-features)
     - [1. Enhanced Test Execution Control with "runMode"](#1-enhanced-test-execution-control-with-runmode)
@@ -29,10 +31,37 @@ Release Notes <!-- omit in toc -->
     - [3. Control extension activation within each folder](#3-control-extension-activation-within-each-folder)
     - [4. Auto clear output upon test run](#4-auto-clear-output-upon-test-run)
   - [Fixes](#fixes)
-  - [CHANGELOG](#changelog-2)
+  - [CHANGELOG](#changelog-3)
 
 ---
 
+## v6.2.2
+This release is a patch release with the following changes:
+
+**Enhancement**  
+
+- Improved output config validation logic and showed warning if detected upon starting up. ([#1119](https://github.com/jest-community/vscode-jest/pull/1119) - @connectdotz)
+
+- Added more diagnosis and fix-it instructions in the jest terminal: ([#1119](https://github.com/jest-community/vscode-jest/pull/1119) - @connectdotz)
+
+  - Display critical settings such as "jest.runMode", "jest.outputConfig" and "testing.openTesting" settings
+  - Provide warning messages for common output issues, such as aggressive auto-focus for auto run modes, when detected. Provides quick fix instructions to address them. 
+
+
+**Bug Fixes**
+- Fixed an outputConfig initialization bug that did not honor "testing.openTesting": "openOnTestFailure" setting correctly. ([#1119](https://github.com/jest-community/vscode-jest/pull/1119) - @connectdotz)
+ 
+**New Command**
+- Added a new command `"Jest: Disable Auto Focus Test Output"` to easily disable TEST RESULTS panel auto focus. It will set the output to the "neutral" mode, i.e., no auto focusing. ([#1119](https://github.com/jest-community/vscode-jest/pull/1119) - @connectdotz)
+
+  
+**Documentation**
+- Minor docs updates for the migration guides. ([#1116](https://github.com/jest-community/vscode-jest/pull/1116) - @pmcelhaney)
+- Minor update for the output config info in README and release notes. ([#1119](https://github.com/jest-community/vscode-jest/pull/1119) - @connectdotz)
+
+### CHANGELOG
+- [v6.2.2](https://github.com/jest-community/vscode-jest/releases/tag/v6.2.2)
+
 ## v6.2.1
 This release is a patch release with the following bug fix:
 
@@ -161,7 +190,25 @@ Here are a few scenarios and how to configure them:
   "jest.outputConfig": "neutral"
 }
 
-// Auto-focus on "TEST RESULTS" when errors occur, ideal for on-demand testing
+// or semi-minimal interaction, suitable for watch/on-save modes prefer to see output if there is errors
+{
+  "testing.openTesting": "neverOpen",
+  "jest.outputConfig": {
+    "revealOn": "error",
+    "revealWithFocus": "test-results"
+  }
+}
+
+// Auto-focus on "TEST RESULTS" when run starts, ideal for on-demand testing
+{
+  "testing.openTesting": "neverOpen",
+  "jest.outputConfig": {
+    "revealOn": "run",
+    "revealWithFocus": "test-results"
+  }
+}
+
+// or Auto-focus on "TEST RESULTS" when errors occurred, for on-demand testing prefer to only show output with errors 
 {
   "testing.openTesting": "neverOpen",
   "jest.outputConfig": {

src/JestExt/core.ts

@@ -19,7 +19,7 @@ import { CoverageMapData } from 'istanbul-lib-coverage';
 import { Logging } from '../logging';
 import { createProcessSession, ProcessSession } from './process-session';
 import { JestExtContext, JestSessionEvents, JestExtSessionContext, JestRunEvent } from './types';
-import { extensionName, SupportedLanguageIds } from '../appGlobals';
+import { extensionName, OUTPUT_CONFIG_HELP_URL, SupportedLanguageIds } from '../appGlobals';
 import { createJestExtContext, getExtensionResourceSettings, prefixWorkspace } from './helper';
 import { PluginResourceSettings } from '../Settings';
 import { WizardTaskId } from '../setup-wizard';
@@ -38,6 +38,8 @@ interface JestCommandSettings {
   jestCommandLine: string;
 }
 
+const AUTO_FOCUS_WARNING = `The TEST RESULTS panel has auto-focus enabled, which may cause frequent focus shifts during the current run mode. If this becomes a problem, you can disable the auto-focus using the command "Jest: Disable Auto Focus Test Output". Alternatively, click on the action link below. For more details, see ${OUTPUT_CONFIG_HELP_URL}`;
+
 /** extract lines starts and end with [] */
 export class JestExt {
   coverageMapProvider: CoverageMapProvider;
@@ -139,8 +141,12 @@ export class JestExt {
     if (pluginSettings.enable === false) {
       throw new Error(`Jest is disabled for workspace ${workspaceFolder.name}`);
     }
+    const { outputConfig, openTesting } = outputManager.outputConfigs();
     this.output.write(
-      `RunMode: ${JSON.stringify(pluginSettings.runMode.config, undefined, 4)}`,
+      'Critical Settings:\r\n' +
+        `jest.runMode: ${JSON.stringify(pluginSettings.runMode.config, undefined, 4)}\r\n` +
+        `jest.outputConfig: ${JSON.stringify(outputConfig, undefined, 4)}\r\n` +
+        `testing.openTesting: ${JSON.stringify(openTesting, undefined, 4)}\r\n`,
       'info'
     );
     return pluginSettings;
@@ -309,6 +315,7 @@ export class JestExt {
 
       // update visible editors that belong to this folder
       this.updateVisibleTextEditors();
+      this.warnAutoRunAutoFocus();
     } catch (e) {
       this.outputActionMessages(
         `Failed to start jest session: ${e}`,
@@ -341,6 +348,24 @@ export class JestExt {
     }
   }
 
+  // check if output config has conflict, especially for auto-run modes
+  private async warnAutoRunAutoFocus(): Promise<void> {
+    if (
+      this.extContext.settings.runMode.config.deferred ||
+      this.extContext.settings.runMode.config.type === 'on-demand' ||
+      outputManager.isAutoFocus() === false
+    ) {
+      return;
+    }
+    const cmdLink = executableTerminalLinkProvider.executableLink(
+      this.extContext.workspace.name,
+      `${extensionName}.disable-auto-focus`
+    );
+
+    this.output.write(AUTO_FOCUS_WARNING, 'warn');
+    this.output.write(`Disable Auto Focus: \u2192 ${cmdLink}\r\n`, 'info');
+  }
+
   private updateTestFileEditor(editor: vscode.TextEditor): void {
     if (!this.isTestFileEditor(editor)) {
       return;

src/appGlobals.ts

@@ -7,3 +7,8 @@ export const SupportedLanguageIds = [
   'typescriptreact',
   'vue',
 ];
+
+export const REPO_BASE_URL = 'https://github.com/jest-community/vscode-jest';
+export const TROUBLESHOOTING_URL = `${REPO_BASE_URL}#troubleshooting`;
+export const LONG_RUN_TROUBLESHOOTING_URL = `${REPO_BASE_URL}#what-to-do-with-long-running-tests-warning`;
+export const OUTPUT_CONFIG_HELP_URL = `${REPO_BASE_URL}#outputconfig`;

src/extension-manager.ts

@@ -17,6 +17,7 @@ import { enabledWorkspaceFolders } from './workspace-manager';
 import { VirtualFolderBasedCache } from './virtual-workspace-folder';
 import { updateSetting } from './Settings';
 import { showQuickFix } from './quick-fix';
+import { outputManager } from './output-manager';
 
 export type GetJestExtByURI = (uri: vscode.Uri) => JestExt[];
 
@@ -518,6 +519,7 @@ export class ExtensionManager {
 
   activate(): void {
     this.showReleaseMessage();
+    outputManager.validate();
 
     if (vscode.window.activeTextEditor?.document.uri) {
       this.onExtensionByUri(vscode.window.activeTextEditor?.document.uri, (ext) => {
@@ -529,7 +531,7 @@ export class ExtensionManager {
 
 const ReleaseNoteBase = 'https://github.com/jest-community/vscode-jest/blob/master/release-notes';
 const ReleaseNotes: Record<string, string> = {
-  '6.2.1': `${ReleaseNoteBase}/release-note-v6.md#v621`,
+  '6.2.2': `${ReleaseNoteBase}/release-note-v6.md#v622`,
   '6.2.0': `${ReleaseNoteBase}/release-note-v6.md#v620`,
   '6.1.0': `${ReleaseNoteBase}/release-note-v6.md#v610-pre-release`,
   '6.0.0': `${ReleaseNoteBase}/release-note-v6.md#v600-pre-release`,