feat: improve openResources to allow dynamic waits when workbench is loaded (#1917)

Author: djelinek

docs/Home.md

@@ -38,14 +38,34 @@ Find documentation about the Page Object APIs: [[Page-Object-APIs]].
 
 ## Opening Files and Folders
 
-Opening files and folders is basic functionality of VS Code.
+Opening files and folders is a fundamental part of automating interactions in VS Code. Since version **4.2.0**, the recommended approach is to use the `openResources` method provided by the `VSBrowser` API.
 
-Since 4.2.0, the most convenient way to open files and folders is the `openResources` method in `VSBrowser`. Use it to open potentially multiple folders or files at the same time (method also waits for workbench to refresh). Files are opened in the editor, single folder will be opened directly in the explorer, multiple folders will be opened as a multi-workspace.
+### `openResources(...args: (string | (() => void | Promise<any>))[]): Promise<void>`
 
-It is recommended to use absolute paths, relative paths are based on process' cwd.
+This method allows you to open one or more files and folders, **and optionally wait for additional conditions** once the workbench is loaded. It automatically waits for the workbench to be ready after opening resources.
 
-```typescript
-await VSBrowser.instance.openResources(`${path/to/folder1}`, ${path/to/file1}, ${path/to/folder2})
+- **Single folder**: Opens the folder in the explorer.
+- **Multiple folders**: Opens a multi-root workspace.
+- **Files**: Opens each file in a new editor tab.
+- **Wait function** _(optional)_: Can be passed as the last argument (sync or async) and will be executed after the workbench is ready.
+
+> **Tip:** Use **absolute paths** to avoid issues. Relative paths are resolved based on the current working directory (`process.cwd()`).
+
+### Example
+
+```ts
+import * as path from "path";
+import { VSBrowser } from "vscode-extension-tester";
+
+await VSBrowser.instance.openResources(
+  path.resolve(__dirname, "workspace/folder1"),
+  path.resolve(__dirname, "workspace/file1.ts"),
+  path.resolve(__dirname, "workspace/folder2"),
+  async () => {
+    // Optional: Wait for your custom UI element or state
+    await new Promise((res) => setTimeout(res, 3000));
+  },
+);
 ```
 
 ### Using Dialogs

packages/extester/src/browser.ts

@@ -148,19 +148,43 @@ export class VSBrowser {
 	}
 
 	/**
-	 * Waits until parts of the workbench are loaded
+	 * Waits for the VS Code workbench UI to be fully loaded and optionally performs
+	 * an additional async or sync check after the workbench appears.
+	 *
+	 * This method waits for the presence of the `.monaco-workbench` element within the specified timeout.
+	 * If a WebDriver error occurs (e.g. flaky startup), it retries after a short delay.
+	 * Additionally, a follow-up function (`waitForFn`) can be passed to perform custom
+	 * readiness checks (e.g. for UI elements, extensions, or custom content).
+	 *
+	 * @param timeout - Maximum time in milliseconds to wait for the workbench to appear (default: 30,000 ms).
+	 * @param waitForFn - Optional function (sync or async) to be executed after the workbench is located.
+	 *
+	 * @throws If the workbench is not found in time and no recoverable WebDriver error occurred.
+	 *
+	 * @example
+	 * // Wait for the workbench with default timeout
+	 * await waitForWorkbench();
+	 *
+	 * @example
+	 * // Wait for the workbench and ensure a custom UI element is present
+	 * await waitForWorkbench(10000, async () => {
+	 *   await driver.wait(until.elementLocated(By.id('my-element')), 5000);
+	 * });
 	 */
-	async waitForWorkbench(timeout = 30000): Promise<void> {
+	async waitForWorkbench(timeout: number = 30_000, waitForFn?: () => void | Promise<any>): Promise<void> {
 		// Workaround/patch for https://github.com/redhat-developer/vscode-extension-tester/issues/466
 		try {
 			await this._driver.wait(until.elementLocated(By.className('monaco-workbench')), timeout, `Workbench was not loaded properly after ${timeout} ms.`);
 		} catch (err) {
 			if ((err as Error).name === 'WebDriverError') {
-				await new Promise((res) => setTimeout(res, 3000));
+				await new Promise((res) => setTimeout(res, 3_000));
 			} else {
 				throw err;
 			}
 		}
+		if (waitForFn) {
+			await waitForFn();
+		}
 	}
 
 	/**
@@ -199,19 +223,35 @@ export class VSBrowser {
 	}
 
 	/**
-	 * Open folder(s) or file(s) in the current instance of vscode.
+	 * Opens one or more resources in the editor and optionally performs a follow-up action.
+	 *
+	 * This method accepts a variable number of arguments. All string arguments are interpreted
+	 * as resource paths to be opened. Optionally, a single callback function (synchronous or asynchronous)
+	 * can be provided as the last argument. This callback will be invoked after all resources have been opened.
+	 *
+	 * @param args - A list of file paths to open followed optionally by a callback function.
+	 *               The callback can be either synchronous or asynchronous.
 	 *
-	 * @param paths path(s) of folder(s)/files(s) to open as varargs
-	 * @returns Promise resolving when all selected resources are opened and the workbench reloads
+	 * @example
+	 * // Open two files
+	 * await openResources('file1.ts', 'file2.ts');
+	 *
+	 * @example
+	 * // Open one file and then wait for a condition
+	 * await openResources('file1.ts', async () => {
+	 *   await waitForElementToLoad();
+	 * });
 	 */
-	async openResources(...paths: string[]): Promise<void> {
+	async openResources(...args: (string | (() => void | Promise<any>))[]): Promise<void> {
+		const paths = args.filter((arg) => typeof arg === 'string');
+		const waitForFn = args.find((arg) => typeof arg === 'function') as (() => void | Promise<any>) | undefined;
+
 		if (paths.length === 0) {
 			return;
 		}
 
 		const code = new CodeUtil(this.storagePath, this.releaseType, this.extensionsFolder);
 		code.open(...paths);
-		await new Promise((res) => setTimeout(res, 3000));
-		await this.waitForWorkbench();
+		await this.waitForWorkbench(undefined, waitForFn);
 	}
 }

packages/extester/src/suite/runner.ts

@@ -94,9 +94,6 @@ export class VSRunner {
 				await browser.start(binPath);
 				await browser.openResources(...resources);
 				await browser.waitForWorkbench();
-				await new Promise((res) => {
-					setTimeout(res, 3000);
-				});
 				console.log(`Browser ready in ${Date.now() - start} ms`);
 				console.log('Launching tests...');
 			});

packages/page-objects/src/components/sidebar/scm/NewScmView.ts

@@ -68,8 +68,7 @@ export class SingleScmProvider extends ScmProvider {
 		const buttons: TitleActionButton[] = [];
 
 		if (satisfies(ScmProvider.versionInfo.version, '>=1.93.0')) {
-			const header = await view.findElement(ScmView.locators.ScmView.sourceControlSection);
-			actions = await header.findElements(ScmProvider.locators.ScmView.action);
+			actions = await this.getProviderHeaderActions(view);
 			names = await Promise.all(actions.map(async (action) => await action.getAttribute(ScmProvider.locators.ScmView.actionLabel)));
 		} else {
 			const titlePart = view.getTitlePart();
@@ -84,6 +83,7 @@ export class SingleScmProvider extends ScmProvider {
 		const index = names.findIndex((item) => item === title);
 		if (index > -1) {
 			if (satisfies(ScmProvider.versionInfo.version, '>=1.93.0')) {
+				actions = await this.getProviderHeaderActions(view);
 				await actions[index].click();
 			} else {
 				await buttons[index].click();
@@ -93,6 +93,13 @@ export class SingleScmProvider extends ScmProvider {
 		return false;
 	}
 
+	private async getProviderHeaderActions(view: NewScmView): Promise<WebElement[]> {
+		const header = await view.findElement(ScmView.locators.ScmView.sourceControlSection);
+		await this.getDriver().actions().move({ origin: header }).perform();
+		await this.getDriver().sleep(1_000);
+		return await header.findElements(ScmProvider.locators.ScmView.action);
+	}
+
 	async openMoreActions(): Promise<ContextMenu> {
 		const view = this.enclosingItem as NewScmView;
 		return await new MoreAction(view).openContextMenu();

tests/test-project/src/test/xsideBar/scmView.test.ts

@@ -30,9 +30,7 @@ import { satisfies } from 'compare-versions';
 		await VSBrowser.instance.openResources(path.resolve('..', '..'));
 		await VSBrowser.instance.waitForWorkbench();
 		view = (await ((await new ActivityBar().getViewControl('Source Control')) as ViewControl).openView()) as ScmView;
-		await new Promise((res) => {
-			setTimeout(res, 2000);
-		});
+		await view.getDriver().sleep(5_000); // wait until scm changes are loaded
 	});
 
 	after(() => {
@@ -116,7 +114,7 @@ import { satisfies } from 'compare-versions';
 				expect(label).has.string('testfile');
 			});
 
-			it('getDescritption works', async () => {
+			it('getDescription works', async () => {
 				const desc = await change.getDescription();
 				expect(desc).has.string('');
 			});