deploy: current vibn theia state

Made-with: Cursor

examples/playwright/docs/DEVELOPING.md

@@ -0,0 +1,57 @@
+# Building and developing Theia 🎭 Playwright
+
+## Building
+
+Run `npm install && npm run build` in the root directory of the repository to build the Theia application.
+
+In order to build Playwright library, the tests and install all dependencies (ex: chromium) run the build script:
+
+```bash
+cd examples/playwright
+npm run build
+```
+
+## Executing the tests
+
+### Prerequisites
+
+Before running your tests, the Theia application under test needs to be running.
+
+The Playwright configuration however is aware of that and starts the backend (`npm run theia:start`) on port 3000 if not already running.
+This is valid for executing tests with the VS Code Playwright extension or from your command line.
+
+You may also use the `Launch Browser Backend` launch configuration in VS Code.
+
+### Running the tests in VS Code via the Playwright extension
+
+For quick and easy execution of tests in VS Code, we recommend using the [VS Code Playwright extension (`ms-playwright.playwright`)](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
+
+Once you have installed the VS Code Playwright test extension, open the *Test* view and click the `Run Tests` button on the top toolbar or the `Run Test` button for a particular test.
+It uses the default configuration with chromium as test profile by default.
+
+To run the tests headful, simply enable the checkbox `Show browser` in the Playwright section of the *Test* view.
+
+### Running the tests headless via CLI
+
+To start the tests run `npm run ui-tests` in the folder `playwright`.
+This will start the tests in a headless state.
+
+To only run a single test file, the path of a test file can be set with `npm run ui-tests <path-to-file>` or `npm run ui-tests -g "<partial test file name>"`.
+See the [Playwright Test command line documentation](https://playwright.dev/docs/intro#command-line).
+
+### Running the tests headful via CLI
+
+If you want to observe the execution of the tests in a browser, use `npm run ui-tests-headful` for all tests or `npm run ui-tests-headful <path-to-file>` to only run a specific test.
+
+### Watch the tests
+
+Run `npm run watch` in the root of this package to rebuild the test code after each change.
+This ensures, that the executed tests are up-to-date also when running them with the [Playwright VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
+
+### Debugging the tests
+
+Please refer to the section [Debugging the tests via the VS Code Playwright extension](./GETTING_STARTED.md#debugging-the-tests-via-the-vs-code-playwright-extension).
+
+### UI Mode - Watch and Trace Mode
+
+Please refer to the section [UI Mode - Watch and Trace Mode](./GETTING_STARTED.md#ui-mode---watch-and-trace-mode).

examples/playwright/docs/EXTENSIBILITY.md

@@ -0,0 +1,103 @@
+# Extensibility
+
+Theia is an extensible tool platform for building custom tools with custom user interface elements, such as views, editors, commands, etc.
+Correspondingly, Theia 🎭 Playwright supports adding dedicated page objects for your custom user interface elements.
+Depending on the nature of your custom components, you can extend the generic base objects, such as for views or editors, or add your own from scratch.
+
+## Custom commands or menu items
+
+Commands and menu items are handled by their label, so no further customization of the page object framework is required.
+Simply interact with them via the menu or quick commands.
+
+```typescript
+const app = await TheiaAppLoader.load({ playwright, browser });
+const menuBar = app.menuBar;
+
+const yourMenu = await menuBar.openMenu('Your Menu');
+const yourItem = await mainMenu.menuItemByName('Your Item');
+
+expect(await yourItem?.hasSubmenu()).toBe(true);
+```
+
+## Custom Theia applications
+
+The main entry point of the page object model is `TheiaApp`.
+To add further capabilities to it, for instance a custom toolbar, extend the `TheiaApp` class and add an accessor for a custom toolbar page object.
+
+```typescript
+export class MyTheiaApp extends TheiaApp {
+  readonly toolbar = new MyToolbar(this);
+}
+
+export class MyToolbar extends TheiaPageObject {
+  selector = 'div#myToolbar';
+  async clickItem1(): Promise<void> {
+    await this.page.click(`${this.selector} .item1`);
+  }
+}
+
+const ws = new TheiaWorkspace([path.resolve(__dirname, '../../src/tests/resources/sample-files1']);
+const app = await TheiaAppLoader.load({ playwright, browser }, ws, MyTheiaApp);
+await app.toolbar.clickItem1();
+```
+
+## Custom views and status indicators
+
+Many custom Theia applications add dedicated views, editors, or status indicators.
+To support these custom user interface elements in the testing framework, you can add dedicated page objects for them.
+Typically, these dedicated page objects for your custom user interface elements are subclasses of the generic classes, `TheiaView`, `TheiaEditor`, etc.
+Consequently, they inherit the generic behavior of views or editors, such as activating or closing them, querying the title, check whether editors are dirty, etc.
+
+Let's take a custom view as an example. This custom view has a button that we want to be able to click.
+
+```typescript
+export class MyView extends TheiaView {
+  constructor(public app: TheiaApp) {
+    super(
+      {
+        tabSelector: '#shell-tab-my-view', // the id of the tab
+        viewSelector: '#my-view-container', // the id of the view container
+        viewName: 'My View', // the user visible view name
+      },
+      app
+    );
+  }
+
+  async clickMyButton(): Promise<void> {
+    await this.activate();
+    const viewElement = await this.viewElement();
+    const button = await viewElement?.waitForSelector('#idOfMyButton');
+    await button?.click();
+  }
+}
+```
+
+So first, we create a new class that inherits all generic view capabilities from `TheiaView`.
+We have to specify the selectors for the tab and for the view container element that we specify in the view implementation.
+Optionally we can specify a view name, which corresponds to the label in Theia's view menu.
+This information is enough to open, close, find and interact with the view.
+
+Additionally, we can add further custom methods for the specific actions and queries we want to use for our custom view.
+As an example, `MyView` above introduces a method that allows to click a button.
+
+To use this custom page object in a test, we pass our custom page object as a parameter when opening the view with `app.openView`.
+
+```typescript
+const app = await TheiaAppLoader.load({ playwright, browser });
+const myView = await app.openView(MyView);
+await myView.clickMyButton();
+```
+
+A similar approach is used for custom editors. The only difference is that we extend `TheiaEditor` instead and pass our custom page object as an argument to `app.openEditor`.
+As a reference for custom views and editors, please refer to the existing page objects, such as `TheiaPreferenceView`, `TheiaTextEditor`, etc.
+
+Custom status indicators are supported with the same mechanism. They are accessed via `TheiaApp.statusBar`.
+
+```typescript
+const app = await TheiaAppLoader.load({ playwright, browser });
+const problemIndicator = await app.statusBar.statusIndicator(
+  TheiaProblemIndicator
+);
+const numberOfProblems = await problemIndicator.numberOfProblems();
+expect(numberOfProblems).to.be(2);
+```

examples/playwright/docs/GETTING_STARTED.md

@@ -0,0 +1,184 @@
+# Getting Started
+
+The fastest way to getting started is to clone the [theia-playwright-template](https://github.com/eclipse-theia/theia-playwright-template) and build the theia-playwright-template.
+
+```bash
+git clone git@github.com:eclipse-theia/theia-playwright-template.git
+cd theia-playwright-template
+yarn
+```
+
+The most important files in the theia-playwright-template are:
+
+* Example test in `tests/theia-app.test.ts`
+* Example page object in `test/page-objects/theia-app.ts`
+* The base Playwright configuration file at `playwright.config.ts`
+* `package.json` with all required dependencies and scripts for running and debugging the tests
+
+Now, let's run the tests:
+
+1. Run your Theia application under test (not part of the theia-playwright-template)
+2. Run `yarn ui-tests` in the theia-playwright-template to run its tests in headless mode
+
+Please note that Theia 🎭 Playwright is built to be extended with custom page objects, such as the one in `test/page-objects/theia-app.ts` in the theia-playwright-template.
+We recommend adding further page objects for all custom views, editors, widgets, etc.
+Please refer to the [extension guide](EXTENSIBILITY.md) for more information.
+
+Moreover, this repository contains several tests based on Theia 🎭 Playwright in `examples/playwright/src/tests` that may serve as additional examples for writing tests.
+
+## Adding further tests
+
+Let's write another system test for the Theia text editor as an example:
+
+1. Initialize a prepared workspace containing a file `sampleFolder/sample.txt` and open the workspace with the Theia application under test
+2. Open the Theia text editor
+3. Replace the contents of line 1 with `change` and check the line contents and the dirty state, which now should indicate that the editor is dirty.
+4. Perform an undo twice and verify that the line contents should be what it was before the change. The dirty state should be clean again.
+5. Run redo twice and check that line 1 shows the text `change` again. Also, the dirty state should be changed again.
+6. Save the editor with the saved contents and check whether the editor state is clean after save. Close the editor.
+7. Reopen the same file and check whether the contents of line 1 shows still the changed contents.
+
+The test code could look as follows. We use the page objects `TheiaWorkspace` and `TheiaApp` to initialize the application with a prepared workspace.
+Using the `TheiaApp` instance, we open an editor of type `TheiaTextEditor`, which allows us to exercise actions, such as replacing line contents, undo, redo, etc.
+At any time, we can also get information from the text editor, such as obtaining dirty state and verify whether this information is what we expect.
+
+```typescript
+test('should undo and redo text changes and correctly update the dirty state', async ({ playwright, browser }) => {
+    // 1. set up workspace contents and open Theia app
+    const ws = new TheiaWorkspace([path.resolve(__dirname, 'resources/sample-files1']);
+    app = await TheiaAppLoader.load( { playwright, browser }, ws);
+
+    // 2. open Theia text editor
+    const sampleTextEditor = await app.openEditor(
+        'sample.txt',
+        TheiaTextEditor
+    );
+
+    // 3. make a change and verify contents and dirty
+    await sampleTextEditor.replaceLineWithLineNumber('change', 1);
+    expect(await sampleTextEditor.textContentOfLineByLineNumber(1)).toBe(
+        'change'
+    );
+    expect(await sampleTextEditor.isDirty()).toBe(true);
+
+    // 4. undo and verify contents and dirty state
+    await sampleTextEditor.undo(2);
+    expect(await sampleTextEditor.textContentOfLineByLineNumber(1)).toBe(
+        'this is just a sample file'
+    );
+    expect(await sampleTextEditor.isDirty()).toBe(false);
+
+    // 5. undo and verify contents and dirty state
+    await sampleTextEditor.redo(2);
+    expect(await sampleTextEditor.textContentOfLineByLineNumber(1)).toBe(
+        'change'
+    );
+    expect(await sampleTextEditor.isDirty()).toBe(true);
+
+    // 6. save verify dirty state
+    await sampleTextEditor.save();
+    expect(await sampleTextEditor.isDirty()).toBe(false);
+    await sampleTextEditor.close();
+
+    // 7. reopen editor and verify dirty state
+    const reopenedEditor = await app.openEditor('sample.txt', TheiaTextEditor);
+    expect(await reopenedEditor.textContentOfLineByLineNumber(1)).toBe(
+        'change'
+    );
+
+    await reopenedEditor.close();
+});
+```
+
+Below you can see this example test in action by stepping through the code with the VS Code debug tools.
+
+<div style='margin:0 auto;width:100%;'>
+
+![Theia](./images/debug-example.gif)
+
+</div>
+
+## Best practices
+
+The playwright tests/functions are all asynchronous so the `await` keyword should be used to wait for the result of a given function.
+This way there is no need to use timeouts or other functions to wait for a specific result.
+As long as await is used on any call, the tests should be in the intended state.
+
+There are two ways to query the page for elements using a selector.
+
+1. One is the `page.$(selector)` method, which returns null or the element, if it is available.
+2. The other method `page.waitForSelector(selector)`, like indicated by the name, waits until the selector becomes available. This ensures that the element could be loaded and therefore negates the
+   need for null checks afterwards.
+
+Avoid directly interacting with the document object model, such as HTML elements, or the Playwright `page` from tests directly.
+The interaction with the application should be encapsulated in the page objects.
+Otherwise, your tests will get bloated and more fragile to changes of the application.
+For more information, refer to the [page object pattern](https://martinfowler.com/bliki/PageObject.html).
+
+Avoid returning or exposing Playwright types from page objects.
+This keeps your tests independent of the underlying browser automation framework.
+
+## Executing tests
+
+## Building
+
+Run `yarn` in the root directory of the repository to build the Theia application.
+
+In order to build Playwright library, the tests and install all dependencies (ex: chromium) run the build script:
+
+```bash
+cd examples/playwright
+yarn build
+```
+
+### Starting the Theia Application under test
+
+Before running your tests, the Theia application under test needs to be running.
+This repository already provides an example Theia application, however, you might want to test your custom Theia-based application instead.
+
+The Playwright configuration however is aware of that and starts the backend (`yarn theia:start`) on port 3000 if not already running.
+This is valid for executing tests with the VS Code Playwright extension or from your command line.
+
+### Running the tests in VS Code via the Playwright extension
+
+For quick and easy execution of tests in VS Code, we recommend using the [VS Code Playwright extension (`ms-playwright.playwright`)](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
+
+Once you have installed the VS Code Playwright test extension, open the *Test* view and click the `Run Tests` button on the top toolbar or the `Run Test` button for a particular test.
+It uses the default configuration with chromium as test profile by default.
+
+To run the tests headful, simply enable the checkbox `Show browser` in the Playwright section of the *Test* view.
+
+### Running the tests headless via CLI
+
+To start the tests run `yarn ui-tests` in the folder `playwright`.
+This will start the tests in a headless state.
+
+To only run a single test file, the path of a test file can be set with `yarn ui-tests <path-to-file>` or `yarn ui-tests -g "<partial test file name>"`.
+See the [Playwright Test command line documentation](https://playwright.dev/docs/intro#command-line).
+
+### Running the tests headful via CLI
+
+If you want to observe the execution of the tests in a browser, use `yarn ui-tests-headful` for all tests or `yarn ui-tests-headful <path-to-file>` to only run a specific test.
+
+### Debugging the tests via the VS Code Playwright extension
+
+To debug Playwright tests, open the *Test* view in VS Code and click the `Debug Tests` button on the top toolbar or the `Debug Test` for a particular test.
+It uses the default configuration with chromium as test profile by default.
+
+For more information on debugging, please refer to the [Playwright documentation](https://playwright.dev/docs/debug).
+
+### UI Mode - Watch and Trace Mode
+
+For an advanced test development experience, Playwright provides the so-called *UI Mode*. To enable this, simply add the flag `--ui` to the CLI command.
+
+```bash
+yarn ui-tests --ui
+```
+
+For more information on the UI mode, please refer to the [Playwright announcement of the UI mode](https://playwright.dev/docs/release-notes#introducing-ui-mode-preview).
+
+## Advanced Topics
+
+There are many more features, configuration and command line options from Playwright that can be used.
+These range from grouping and annotating tests, further reporters, to visual comparisons, etc.
+For more information refer to the [Playwright documentation](https://playwright.dev/docs/intro).