From 008a0914831063b6c8aa5f94e5ccdc5c4aaa33f3 Mon Sep 17 00:00:00 2001 From: Jannik Stehle Date: Wed, 16 Apr 2025 14:27:06 +0200 Subject: [PATCH 1/2] docs(dev): overhaul web dev docs Gives the Web dev docs a much needed overhaul, fixes dead links and formats all md files in a consistent way. --- docs/dev/web/development/conventions.md | 37 +- docs/dev/web/development/repo-structure.md | 35 +- docs/dev/web/development/tooling.md | 33 +- docs/dev/web/embed-mode.md | 18 +- .../extension-types/action-extensions.md | 8 +- .../app-menu-item-extensions.md | 4 +- .../custom-component-extensions.md | 4 +- .../extension-types/folder-view-extensions.md | 6 +- .../left-sidebar-menu-item-extensions.md | 8 +- .../right-sidebar-panel-extensions.md | 16 +- .../extension-types/search-extensions.md | 34 +- docs/dev/web/extension-system/index.md | 21 +- .../extension-system/viewer-editor-apps.md | 8 +- docs/dev/web/getting-started.md | 108 +++--- docs/dev/web/testing/e2e-testing-standards.md | 327 +----------------- docs/dev/web/testing/running-tests.md | 25 +- 16 files changed, 193 insertions(+), 499 deletions(-) diff --git a/docs/dev/web/development/conventions.md b/docs/dev/web/development/conventions.md index 962f853f..05d9731f 100644 --- a/docs/dev/web/development/conventions.md +++ b/docs/dev/web/development/conventions.md @@ -1,11 +1,9 @@ --- title: 'Conventions' -sidebar_position: 1 +sidebar_position: 3 id: conventions --- - - This is a collection of tips and conventions to follow when working on the [OpenCloud Web frontend](https://github.com/opencloud-eu/web). Since it is a living document, please open a PR if you find something missing. @@ -15,14 +13,12 @@ Everyone is invited to contribute. Simply fork the [codebase](https://github.com check the [issues](https://github.com/opencloud-eu/web/issues?q=is%3Aopen%20is%3Aissue%20label%3AType%3AGood-First-Issue) for a suitable one and open a pull request! -### Linting and Tests +### Formal checks -To make sure your pull request can be efficiently reviewed and won't need a lot of changes down the road, please run the linter and -the unit tests via `pnpm lint --fix` and `pnpm test:unit` locally. Our [CI](https://drone.opencloud.eu/opencloud/web) will run on +To make sure your pull request can be efficiently reviewed and won't need a lot of changes down the road, please run all formal checks (linter, formatter, type checks and unit tests) via `pnpm check:all` locally. Our [CI](https://ci.opencloud.eu/repos/6) will run on pull requests and report back any problems after that. For a further introduction on how we handle testing, please head to the [testing docs](./../testing/running-tests.md). - ## Code Conventions ### Early Returns @@ -31,20 +27,29 @@ We're trying to stick with early returns in our code to make it more performant ### Translations -Use the `v-text` directive in combination with `$gettext` (or a variation of it) inside HTML tags (instead of -a `` or similar) in order to make reasoning about the DOM tree easier. +Use `$gettext` (or a variation of it) inside HTML tags (instead of a `` or similar) in order to translate strings. ### TypeScript -We're using TypeScript, which allows us to catch bugs at transpile time. Clean types make sure our IDEs can support us -in reasoning about our (ever growing, complex) codebase. +We're using TypeScript which allows us to catch bugs at transpile time. Clean types make sure our IDEs can support us in reasoning about our ever-growing, complex codebase. + +### Composition API and script setup + +We prefer using Vue's Composition API in combination with [script setup](https://vuejs.org/api/sfc-script-setup) over the traditional options API. This integrates nicely with TypeScript and allows us to use composables and reactive APIs more effectively. + +That being said, due to the fact that we are still in the process of migrating our codebase, you might find some files using the options API or even composition API without script setup. We are working on this and will eventually migrate all files. + +### Composables + +We make heavy use of composables to encapsulate reusable logic. This allows us to share code between components and keep our components clean and focused on their specific tasks. + +### Split large components + +If a component is getting too big, consider splitting it into smaller components. This will make it easier to read and maintain. A good rule of thumb is to keep components under 300 lines of code. -### Vue 3 and Composition API +### Services -We've migrated from Vue 2 to Vue 3 late in 2022 and since then have been investing continuous efforts to move away from the Vue options API -in favor of the Vue composition API. The `web-pkg` helper package provides quite some composables which will help you in -app & extension development, so we encourage you to make use of the Vue composition API as well, even outside of the -OpenCloud Web repository. +We try to avoid services when possible and rather use composables instead. If writing a service is necessary, it should be instantiated once via the `web-runtime` package and then made available via a `useYourService` composable. ### Dependencies diff --git a/docs/dev/web/development/repo-structure.md b/docs/dev/web/development/repo-structure.md index 5becb0d8..a8369fb1 100644 --- a/docs/dev/web/development/repo-structure.md +++ b/docs/dev/web/development/repo-structure.md @@ -4,8 +4,6 @@ sidebar_position: 2 id: repo-structure --- - - ## Repository Structure From a developer's perspective, the most important parts of the [OpenCloud Web repo](https://github.com/opencloud-eu/web) are the following files and folders: @@ -26,10 +24,7 @@ Having these packages side by side within the `/packages` folder of the repo is ### tests Folder -We're using [Playwright](https://playwright.dev) for UI testing. The UI tests are located in `/tests/e2e`. - -You're more than welcome to make a pull request and adjust this section of the docs accordingly. :-) -You can read more about testing in our [testing section](./../testing/running-tests.md) +We're using [Playwright](https://playwright.dev) for UI testing. The UI tests are located in `/tests/e2e`. You can read more about testing in our [testing docs](./../testing/running-tests.md). ### package.json File @@ -41,7 +36,7 @@ Each package in `/packages` can and most likely will contain another `package.js We're working with [Vite](https://vitejs.dev) as a local development server and build tool. `vite.config.ts` is the main configuration file for that. You can read more about the usage in our [tooling section](./../development/tooling.md). -## (Published) Packages +## Packages Each package in the `/packages` folder can - not exclusively, but most commonly - consist of @@ -61,18 +56,16 @@ Namely those packages are - `/packages/eslint-config` - `/packages/extension-sdk` - `/packages/prettier-config` -- `/packages/tsconfig/` +- `/packages/tsconfig` ### OpenCloud Design System The OpenCloud Design System (`/packages/design-system`) is a collection of components, design tokens and styles which ensure a unique and consistent look and feel and branding throughout the OpenCloud Web ecosystem. We hope that you use it, too, so that your very own apps and extensions will blend in with all the others. Documentation and code examples can be found in -the [design system documentation](https://opencloud.design). +the [design system documentation](https://docs.opencloud.eu/design-system/). -The OpenCloud Design System is a standalone project, but to make development easier we have the code in our mono repo. -We're planning to publish it on npmjs.com as [@opencloud-eu/design-system](https://www.npmjs.com/package/@opencloud-eu/design-system) -as soon as possible. Since it's bundled with OpenCloud Web, you should not bundle it with your app or extension. +The OpenCloud Design System is a standalone project that gets published on npmjs.com as [@opencloud-eu/design-system](https://www.npmjs.com/package/@opencloud-eu/design-system). Since it's bundled with OpenCloud Web, you should not bundle it with your app or extension. However, you can add is as a dev dependency for better IDE support. ### web-client @@ -102,7 +95,15 @@ have more questions about this package, please write an issue in our [issue trac ### Standalone Core Apps -Both `web-app-admin-settings` and `web-app-files` are standalone apps which are bundled with the default OpenCloud Web release artifact. +The repo also includes some standalone apps which are bundled with the default OpenCloud Web release artifact. + +- `web-app-activities` +- `web-app-admin-settings` +- `web-app-app-store` +- `web-app-files` +- `web-app-ocm` +- `web-app-search` +- `web-app-webfinger` ### Viewer and Editor Apps @@ -110,14 +111,14 @@ Apps which fall into the categories `viewer` or `editor` can be opened from the within the `files` app. We currently bundle the following apps with the default OpenCloud Web release artifact: - `web-app-epub-reader` a simple reader for `.epub` files -- `web-app-external` an iframe integration of all the apps coming from the [app provider](https://docs.opencloud.eu/services/app-provider/) - (e.g. OnlyOffice, Collabora Online and others) +- `web-app-external` an iframe integration of all the apps coming from the app provider + (e.g. Collabora Online, OnlyOffice and others) - `web-app-pdf-viewer` a viewer for `.pdf` files, which relies on native PDF rendering support from the browser - `web-app-preview` a viewer for various media files (audio / video / image formats) - `web-app-text-editor` a simple editor for `.txt`, `.md` and other plain text files -If you're interested in writing your own viewer or editor app for certain file types, please get in touch with us for more info. +If you're interested in writing your own viewer or editor app for certain file types, please have a look at the [extension system docs](./../extension-system). ### Testing -Additional unit testing code lives in `test-helpers`. +Basic setup and helpers for unit testing lives in `web-test-helpers`. This package gets published on npmjs.com as [@opencloud-eu/web-test-helpers](https://www.npmjs.com/package/@opencloud-eu/web-test-helpers) to ensure its functionality can be used anywhere inside the OpenCloud Web ecosystem. diff --git a/docs/dev/web/development/tooling.md b/docs/dev/web/development/tooling.md index 54a1d6b2..2262b05a 100644 --- a/docs/dev/web/development/tooling.md +++ b/docs/dev/web/development/tooling.md @@ -1,11 +1,9 @@ --- title: 'Tooling' -sidebar_position: 3 +sidebar_position: 1 id: tooling --- - - ## Packaging Web is using [pnpm](https://pnpm.io/) as package manager and [vite](https://vitejs.dev/) as build tool. The latter is built on top of [rollup](https://rollupjs.org/) and brings some additional features such as instant hot-reloading. @@ -14,12 +12,27 @@ Web is using [pnpm](https://pnpm.io/) as package manager and [vite](https://vite ### Prerequisites +Please make sure you have the following tools installed on your system: + - docker - docker-compose (if not already included in your docker installation) -- pnpm - node +- pnpm (we recommend the installation via `corepack` which is included in newer node versions) +:::note If you’re not using Docker Desktop, you might have to modify your `/etc/hosts` and add `127.0.0.1 host.docker.internal` to make `host.docker.internal` links work. +::: + +:::note +This setup currently doesn't work on Windows out of the box. + +
+ Workaround + + One of our contributors has opened a PR to a dependency that prevents us from successfully bundling the frontend. + Feel free to check out [their changes](https://github.com/egoist/rollup-plugin-postcss/pull/384) and build them locally if you absolutely want to work on Windows. +
+::: ### Installing Dependencies @@ -27,16 +40,20 @@ After cloning the source code, install the dependencies via `pnpm install`. ### Starting the Server -You can start the server by running `docker-compose up opencloud`. - -Note that the container needs a short while to start because it is waiting for `tika` to be initialized. This is the case as soon as the `tika-service` container has stopped running. +You can start the OpenCloud server by running `docker-compose up opencloud -d`. If you want to run the full stack, you can run `docker-compose up -d` instead. This will also start the wopi service and an instance of Collabora. ### Building and Accessing Web -After the docker containers are running (and `tika` is being initialized), run `pnpm build:w` to build Web. This also includes hot-reloading after changes you make, although it will take a while to rebuild the project. See down below for some details on how to enable instant hot-reloading. +After starting the docker containers, you can build Web by running `pnpm build:w`. This command compiles the project and includes support for hot-reloading, allowing you to see changes as you make them. However, note that the rebuild process may take some time. + +For a faster development experience, consider enabling instant hot-reloading. Details on how to set this up are provided below. Now you can access Web via https://host.docker.internal:9200. ### Using Instant Hot-Reload via Vite To work with instant hot-reloading, you can also build Web by running `pnpm vite`. The port to access Web is slightly different then: https://host.docker.internal:9201. Also note that the initial page load may take a bit longer than usual. This is normal and to be expected. + +:::note +Make sure that you ran `pnpm build` once before starting the server with `pnpm vite`. Also, you need to accept the self-signed certificate in your browser for https://host.docker.internal:9200 _and_ https://host.docker.internal:9201. +::: diff --git a/docs/dev/web/embed-mode.md b/docs/dev/web/embed-mode.md index d75c6f38..d9a1bf37 100644 --- a/docs/dev/web/embed-mode.md +++ b/docs/dev/web/embed-mode.md @@ -3,9 +3,7 @@ title: 'Embed Mode' sidebar_position: 4 --- - - -The OpenCloud Web can be consumed by another application in a stripped down version called "Embed mode". This mode is supposed to be used in the context of selecting or sharing resources. If you're looking for even more minimalistic approach, you can take a look at the [File picker](https://docs.opencloud.eu/integration/file_picker/). +The OpenCloud Web can be consumed by another application in a stripped down version called "Embed mode". This mode is supposed to be used in the context of selecting or sharing resources. ## Getting started @@ -27,11 +25,11 @@ By default, the `postMessage` method does not specify the `targetOrigin` paramet To maintain uniformity and ease of handling, each event encapsulates the same structure within its payload: `{ name: string, data: any }`. -| Name | Data | Description | -| -------------------------- | ---------- | ------------------------------------------------------------------------------------- | -| **opencloud-embed:select** | Resource[] | Gets emitted when user selects resources or location via the select action | -| **opencloud-embed:share** | string[] | Gets emitted when user selects resources and shares them via the "Share links" action | -| **opencloud-embed:cancel** | null | Gets emitted when user attempts to close the embedded instance via "Cancel" action | +| Name | Data | Description | +| -------------------------- | ------------ | ------------------------------------------------------------------------------------- | +| **opencloud-embed:select** | `Resource[]` | Gets emitted when user selects resources or location via the select action | +| **opencloud-embed:share** | `string[]` | Gets emitted when user selects resources and shares them via the "Share links" action | +| **opencloud-embed:cancel** | `null` | Gets emitted when user attempts to close the embedded instance via "Cancel" action | ### Example @@ -61,7 +59,9 @@ In special scenarios you also want the user to set a file name, this can be achi ### Example ```html - + + const { searchResult } = defineProps<{ searchResult: SearchResultValue }>() + const resource = computed(() => searchResult.data) + ``` The extension can then be registered in any app like so: diff --git a/docs/dev/web/extension-system/index.md b/docs/dev/web/extension-system/index.md index f3682052..e8a4bcc8 100644 --- a/docs/dev/web/extension-system/index.md +++ b/docs/dev/web/extension-system/index.md @@ -2,8 +2,6 @@ title: 'Extension system' --- - - ## Concepts and Building Blocks OpenCloud Web can be extended through various entry points with custom **apps** and **extensions**. @@ -29,10 +27,9 @@ Feel free to contribute or just be inspired for your own apps or extensions. ### Apps -To get started, define a `src/index.ts`. Below is the most basic example of its content: +Apps define a `src/index.ts` file which act as an entrypoint. Below is the most basic example of its content: ```typescript -// Install '@opencloud-eu/web-pkg' as a devDependency first (only relevant for types and autocompletion, dependency is already provided by OpenCloud Web at runtime). import { AppWrapperRoute, ApplicationFileExtension, @@ -67,7 +64,7 @@ export default defineWebApplication({ appInfo: { name: $gettext('Your application name'), id: appId, - icon: 'aliens', // See https://opencloud.design/#/Design%20Tokens/IconList for available options + icon: 'aliens', // See https://remixicon.com/ for available options }, extensions, navItems, @@ -83,11 +80,13 @@ By defining an application via `defineWebApplication` you can provide the follow - `navItems` - the statically defined navigation items for the left sidebar. Only gets rendered when more than 1 navigation item exists at runtime. Additional dynamic navigation items can be registered via the extension registry. - `routes` - the routes to the different views of your application. May be referenced within the `navItems`. Authentication requirements can be defined per item. -- `extensions` - the extensions to be registered in the extension registry. For more details see the `Extensions` section below. +- `extensions` - the extensions to be registered in the extension registry. For more details see the [Extensions](#extensions) section below. + +#### Creating a new app -If you want to learn how to implement an app for viewing and editing specific file types, please consult the [relevant documentation](./viewer-editor-apps.md) for detailed instructions and guidance. +Please check out the [web-app-skeleton repository](https://github.com/opencloud-eu/web-app-skeleton) for a boilerplate application to get started with your own application. In addition to that, if you want to learn how to implement an app for viewing and editing specific file types, please consult the [relevant documentation](./viewer-editor-apps.md) for detailed instructions and guidance. -To learn how to integrate an app into OpenCloud Web, please refer to the "Web Apps" section of the Web service docs ("Services" > "Web"). +To learn how to integrate an app into OpenCloud Web, please refer to the [Web Application admin docs](./../../../admin/configuration/web-applications). ### Extensions @@ -161,9 +160,15 @@ To allow users to configure extensions, extension points can define user prefere Whenever an extension point declares to accept user preferences, it will get listed with a dropdown on the Preferences page (reachable via top right user menu). The user can then select one out of all the extensions which have been registered for this extension point. +#### Creating a new extension + +Please check out the [web-app-skeleton repository](https://github.com/opencloud-eu/web-app-skeleton) for a boilerplate application that also includes an extension. In addition to that, the [extension types docs](./extension-types) provide instructions and examples on how to implement the different extension types. + ### Helpful packages We currently offer the following packages that can be integrated into your app, providing useful utilities and types. +- `extension-sdk` - This package provides a default vite config that can be used when developing applications and extensions for the OpenCloud Web ecosystem. For details, please refer to the package's [README.md](https://github.com/opencloud-eu/web/blob/main/packages/extension-sdk/README.md). - `web-client` - This package serves as an abstraction layer between the server APIs and an app or extension. It converts raw API data into objects with helpful types and utilities. For details, please refer to the package's [README.md](https://github.com/opencloud-eu/web/blob/main/packages/web-client/README.md). - `web-pkg` - This package provides utilities, most importantly a variety of components and composables, that can be useful when developing apps and extensions. For details, please refer to the package's [README.md](https://github.com/opencloud-eu/web/blob/main/packages/web-pkg/README.md). +- `web-test-helpers` - This package provides utilities for writing unit tests. For details, please refer to the package's [README.md](https://github.com/opencloud-eu/web/blob/main/packages/web-test-helpers/README.md). diff --git a/docs/dev/web/extension-system/viewer-editor-apps.md b/docs/dev/web/extension-system/viewer-editor-apps.md index a8d55bed..759308e3 100644 --- a/docs/dev/web/extension-system/viewer-editor-apps.md +++ b/docs/dev/web/extension-system/viewer-editor-apps.md @@ -3,8 +3,6 @@ title: 'Viewer and editor apps' sidebar_position: 1 --- - - ## Viewer and editor apps OpenCloud Web allows developers to implement apps for viewing and editing specific file types. For instance, the built-in preview app serves as the default application for opening media files like images, videos, or audio. @@ -24,7 +22,11 @@ To learn more about apps in general, please refer to the [Web app docs](./index. Inside the `src` folder you will need an `index.ts` file that sets up the app so it can be registered by the Web runtime. It follows the basic structure as described in [the apps section](./index.md), so it may look like this: ```typescript -import { AppWrapperRoute, defineWebApplication, AppMenuItemExtension } from '@opencloud-eu/web-pkg' +import { + AppWrapperRoute, + defineWebApplication, + AppMenuItemExtension +} from '@opencloud-eu/web-pkg' import translations from '../l10n/translations.json' import { useGettext } from 'vue3-gettext' import { computed } from 'vue' diff --git a/docs/dev/web/getting-started.md b/docs/dev/web/getting-started.md index d2cd55c6..f3c5437b 100644 --- a/docs/dev/web/getting-started.md +++ b/docs/dev/web/getting-started.md @@ -3,52 +3,32 @@ title: 'Getting Started' sidebar_position: 1 --- +## Source Code -## Installation - -### Docker - -Make sure to have Docker, Docker-Compose, Node.js and pnpm installed. - -:::note -This setup currently doesn't work on Windows out of the box. - -
- Workaround - - One of our contributors has opened a PR to a dependency that prevents us from successfully bundling the frontend. - Feel free to check out [their changes](https://github.com/egoist/rollup-plugin-postcss/pull/384) and build them locally if you absolutely want to work on Windows. -
-::: +The source code is hosted at [https://github.com/opencloud-eu/web](https://github.com/opencloud-eu/web). -After cloning the [source code](https://github.com/opencloud-eu/web), install the dependencies via `pnpm install` and bundle the frontend code by running `pnpm build:w`. +## Installation -Then, you can start the server by running `docker-compose up opencloud` and access it via [https://host.docker.internal:9200](https://host.docker.internal:9200). If you're not using Docker Desktop, you might have to modify your `/etc/hosts` and add `127.0.0.1 host.docker.internal` to make the `host.docker.internal` links work. +To install and setup the Web client on your local machine, please refer to the [development setup docs](./development/tooling.md#development-setup). -The bundled frontend code automatically gets mounted into the Docker containers, recompiles on changes and you can log in using the demo user (admin/admin) and take a look around! +## Configuration -For more details on how to set up Web for development, please see [tooling](./development/tooling.md). +Web can be configured using a configuration file in `json` format. Sample configuration files are available in the [config folder](https://github.com/opencloud-eu/web/tree/main/config) of the OpenCloud Web Git repository. Below is a detailed overview of all available configuration options. -## Source Code +### `server` -The source code is hosted at [https://github.com/opencloud-eu/web](https://github.com/opencloud-eu/web). +Specifies the server URL, e.g. `https://host.docker.internal:9200`. -## Configuration +### `theme` -There are sample config files provided in the [config folder](https://github.com/opencloud-eu/web/tree/main/config) of the OpenCloud Web git repository. See below for some configuration details. +Specifies the URL for the theme to be loaded, e.g. `https://host.docker.internal:9200/themes/opencloud/theme.json`. -- `customTranslations` You can specify one or multiple files to overwrite existing translations. For example set this option to `[{url: "https://localhost:9200/customTranslations.json"}]`. +### `options` -#### Options +General options that control the behavior of the Web client. Expects an object with the following possible options: - `options.accountEditLink` This accepts an object with the following optional fields to have a link on the account page: - - `options.accountEditLink.href` Set a different target URL for the edit link. Make sure to prepend it with `http(s)://`. -- `options.disableFeedbackLink` Set this option to `true` to disable the feedback link in the topbar. Keeping it enabled (value `false` or absence of the option) - allows OpenCloud to get feedback from your user base through a dedicated survey website. -- `options.feedbackLink` This accepts an object with the following optional fields to customize the feedback link in the topbar: - - `options.feedbackLink.href` Set a different target URL for the feedback link. Make sure to prepend it with `http(s)://`. Defaults to `https://opencloud.eu/web-design-feedback`. - - `options.feedbackLink.ariaLabel` Since the link only has an icon, you can set an e.g. screen reader accessible label. Defaults to `OpenCloud feedback survey`. - - `options.feedbackLink.description` Provide any description you want to see as tooltip and as accessible description. Defaults to `Provide your feedback: We'd like to improve the web design and would be happy to hear your feedback. Thank you! Your OpenCloud team.` + - `options.accountEditLink.href` Set a different target URL for the edit link. Make sure to prepend it with `http(s)://`. - `options.sharingRecipientsPerPage` Sets the amount of users shown as recipients in the dropdown when sharing resources. Default amount is 200. - `options.runningOnEos` Set this option to `true` if running on an [EOS storage backend](https://eos-web.web.cern.ch/eos-web/) to enable its specific features. Defaults to `false`. - `options.cernFeatures` Enabling this will activate CERN-specific features. Defaults to `false`. @@ -61,20 +41,62 @@ There are sample config files provided in the [config folder](https://github.com - `options.logoutUrl` Adds a link to the user's profile page to point him to an external page, where he can manage his session and devices. This is helpful when an external IdP is used. This option is disabled by default. - `options.userListRequiresFilter` Defines whether one or more filters must be set in order to list users in the Web admin settings. Set this option to 'true' if running in an environment with a lot of users and listing all users could slow down performance. Defaults to `false`. - `options.concurrentRequests` This accepts an object with the following optional fields to customize the maximum number of concurrent requests in code paths where we limit concurrent requests - - `resourceBatchActions` Concurrent number of file/folder/space batch actions like e.g. accepting shares. Defaults to 4. - - `sse` Concurrent number of SSE event handlers. Defaults to 4. - - `shares` Accepts an object regarding the following sharing related options: - - `create` Concurrent number of share invites. Defaults to 4. - - `list` Concurrent number of individually loaded shares. Defaults to 2. + - `resourceBatchActions` Concurrent number of file/folder/space batch actions like e.g. accepting shares. Defaults to 4. + - `sse` Concurrent number of SSE event handlers. Defaults to 4. + - `shares` Accepts an object regarding the following sharing related options: + - `create` Concurrent number of share invites. Defaults to 4. + - `list` Concurrent number of individually loaded shares. Defaults to 2. -#### Scripts and Styles +### `apps` -Web supports adding additional CSS and JavaScript files to further customize the user experience and adapt it to your specific needs. Please consider opening a feature request if you feel like your customization could be a benefit to the upstream project, and keep an eye open for future major releases of `web` since this API may change. +Controls the Web apps to be loaded. This is not for adding external apps, but for specifying which of the internal apps that are shipped with Web should be loaded. Expects a list of strings, e.g.: -- `styles` expects an array of objects that specify a `href` attribute, pointing to the path/URL of your stylesheet, like `[{ "href": "css/custom.css" }]`. -- `scripts` expects an array of objects that specify a `src` attribute, pointing to the path/URL of your script, and an optional `async` attribute (defaults to false), like `[{ "src": "js/custom.js", "async": true }]`. +```json +[ + "files", + "text-editor", + "pdf-viewer", + "search", + "external", + "admin-settings", + "epub-reader", + "app-store", + "preview" +] +``` + +### `openIdConnect` + +Options for the connection to the oIDC provider. Expects an object with the following possible options: + +- `openIdConnect.authority` URL of the OIDC/OAuth2 provider. +- `openIdConnect.metadata_url` URL of the OIDC configuration. +- `openIdConnect.client_id` The client id registered with the OIDC/OAuth2 provider. +- `openIdConnect.client_secret` +- `openIdConnect.dynamic` +- `openIdConnect.post_logout_redirect_uri` +- `openIdConnect.response_type` +- `openIdConnect.scope` + +See the [oidc-client-ts documentation](https://authts.github.io/oidc-client-ts/interfaces/OidcClientSettings.html) for more information. + +### `customTranslations` + +Specify custom translations to overwrite existing ones. Expects an array of objects that specify a `url` attribute, like `[{url: "https://host.docker.internal:9200/customTranslations.json"}]`. + +### `styles` + +Additional CSS files to further customize the user experience and adapt it to your specific needs. Expects an array of objects that specify a `href` attribute, pointing to the path/URL of your stylesheet, like `[{ "href": "css/custom.css" }]`. + +### `scripts` + +Additional JavaScript files to further customize the user experience and adapt it to your specific needs. Expects an array of objects that specify a `src` attribute, pointing to the path/URL of your script, and an optional `async` attribute (defaults to false), like `[{ "src": "js/custom.js", "async": true }]`. + +:::note +Check out the [extension system docs](./extension-system) for a more convenient way to add functionality to the Web client. +::: -### Sentry +### `sentry` Web supports [Sentry](https://sentry.io/welcome/) to provide monitoring and error tracking. To enable sending data to a Sentry instance, you can use the following configuration keys: diff --git a/docs/dev/web/testing/e2e-testing-standards.md b/docs/dev/web/testing/e2e-testing-standards.md index 9d8171e2..9fdcc4cb 100644 --- a/docs/dev/web/testing/e2e-testing-standards.md +++ b/docs/dev/web/testing/e2e-testing-standards.md @@ -4,8 +4,6 @@ sidebar_position: 2 id: e2e-testing-standards --- - - ## Introduction In OpenCloud, we use Playwright for webUI test automation. We benefit from lower barriers to entry, readability, and usability when test standards are consistent across repositories. For example: @@ -154,326 +152,7 @@ DO 👍 ```typescript await page.goto(fooBarURL, { - waitUntil: 'domcontentloaded' -}) -``` - -DO 👍 - -```typescript -const element = page.locator('some-locator-path') -element.waitFor({ visible: true }) -``` - -DO 👍 - -```typescript -await fooPage.buttonFoo.click() -await expect(fooPage.titlePage).toBeVisible() -``` - -## Selectors - -Avoid selectors tied to implementation and page structure. - -Instead, we can prioritize the below, based on [testing-library guiding principles](https://testing-library.com/docs/queries/about/#priority) - -- `getByRole` (this aids accessibility, reflects how users and assistive technology perceive the page) - -- `getByText` - -- `getByTestId` (add them when needed) - -DO NOT ⚔️ - -```javascript -page.locator('.opt-u > div > .summary > div:nth-child(4) > div') -``` - -DO 👍 - -```javascript -page.locator('#foo-button') -page.getByText('OK') -``` - -## Naming Conventions - -### Files and folders - -- **Files**: Declare in **_camelCase_** -- **Folders**: Declare in **_kebab-case_** - -### Variables - -Declare in **_camelCase_**. - -### Booleans - -Start with ‘is’, ‘has’, ‘are’, ‘have’. This helps spot that this is a boolean while skimming the code. Still declared in **_camelCase_**. - -```typescript -let isTurnedOn = false -``` - -### Page Objects / Classes - -Declare in **_PascalCase_**. - -Use descriptive naming, which can help the reader quickly identify what page or page component this is covering. Use as much context as needed from your product to make the name meaningful. - -DO NOT ⚔️ - -```typescript -export class newModal -``` - -DO 👍 - -```typescript -export class AddWorksOrderModal -``` - -### Locators - -Use descriptive naming, which can help the reader quickly identify what element the locator is targeting. - -As an example, you can use a naming structure that contains **_“action / name of element” + “type of element”_**. - -**_Defining type of element_** - These are your basic HTML element types, they’ll be defined and named in the design system, or as a team you can align on a consistent naming of the elements. Example: checkbox, tickbox, button, tooltip - -**_Defining action / name -_** Think about what action this element will perform when interacted with. Or any existing name/text of the element - -DO 👍 - -```typescript -// This element is a submit button for the user registration form -const submitButton = await page.locator('') -``` - -DO 👍 - -```typescript -// This element is a button for uploading a profile picture -const uploadProfilePictureButton = await page.locator('') -``` - -### Function names - -Always start function names with a **_“verb”_**, followed by the **_“component context”_** that the function is interacting with i.e. what entity it is having an effect on. - -DO 👍 - -```typescript -getWorksOrder() -printTransactions() -deleteProperty() -``` - -## Gherkin Best Practices: Do's and Don'ts for Effective Features & Scenarios - -### Writing Features - -DO 👍 - -- **Be Descriptive:** Use clear and descriptive language that accurately reflects the functionality. -- **Keep It Concise:** Avoid overly long titles or descriptions. Aim for brevity while maintaining clarity. -- **Use Active Voice:** Write in an active voice to make it clear who is performing the action. -- **Contextual Information:** If applicable, provide context about the user role or the scenario to clarify who benefits from the feature. - -DO NOT ⚔️ - -- **Avoid Vague Titles:** Titles like "Test Feature" or "Feature 1" do not provide meaningful information. -- **Neglect User Perspective:** Failing to mention the user role can make it unclear who the feature is intended for. - -Example of a well-written feature: - -```gherkin -Feature: Password Management for Registered Users - As a registered user - I want to set a new password - So that I can secure my account -``` - -### Writing Scenarios - -- **Use Clear and Descriptive Scenario Titles:** Ensure that each scenario title clearly conveys the action being tested and the expected outcome. - -```gherkin -Scenario: User successfully registers with valid details -``` - -- **Use Clear Given/When/Then Steps:** Clearly define the context, action, and expected outcome(success or error messages if any). - -```gherkin -Given the user is on the registration page -When the user enters valid details -Then the user should see a confirmation message "Registration successful! Welcome to our platform." -``` - -- **Use "tries to" for Negation:** This syntax is effective for scenarios where an action is expected to fail. - -```gherkin -Scenario: User tries to log in with incorrect credentials -Given the user is on the registration page -When the user tries to log in with username "Alice" and password "wrongPassword" -Then the user should see an error message - """ - Incorrect username or password. - """ -``` - -## Broad Gherkin Guidelines - -This [OpenCloud developer manual](https://docs.opencloud.eu/server/next/developer_manual/testing/acceptance-tests.html#how-to-write-acceptance-tests) provides comprehensive guidelines and best practices for writing acceptance tests using the Gherkin syntax, a widely adopted language for defining test scenarios in a human-readable format. The manual outlines the specific syntax and structure required when crafting feature files and scenarios to ensure consistency and maintainability within the OpenCloud testing framework. - -In OpenCloud, we use Playwright for webUI test automation. We benefit from lower barriers to entry, readability, and usability when test standards are consistent across repositories. For example: - -- **Reusability:** Enhances reusability by making it easier to reuse functions, locators, shared steps, and other test code. Finding the necessary components and functionalities will be simple for someone working on a test resulting in reduced duplication and the requirement for rework after the initiation of a code review. - -- **Facilitates reviews:** Code can be examined more quickly. Since you can quickly determine what the test code is doing, it eases the mental strain of code review. - -- **Faster onboarding:** By following naming conventions, new contributors are onboarded more rapidly and feel comfortable enough to contribute to the codebase. - -Here are the test standards and guidelines we adhere to when creating Playwright tests at OpenCloud. - -## Folder Structure: - -- `tests/:` - - - `e2e/`: Main folder containing all (end-to-end) E2E test-related files. - - - `cucumber/`: Main folder containing all Cucumber(BDD) test-related files. - - - `features/`: Contains Gherkin feature files. - - - `/`: Collection house for "**related"** feature files. - - - `.feature`: A feature file. - - - `steps/`: Holds the step definition files for mapping Gherkin steps to code. - - - `.ts`: Step definitions for each feature. - - - `hooks/`: Cucumber hooks for setting up and tearing down test environments. - - `hooks.ts`: Contains `Before`, `After`, and other lifecycle hooks. - - - `support/`: Playwright (Test implementation) - - - `api/`: Contains API-related test files and configurations. - - - `/ `: Specific API tests for a particular service. - - - `objects/`: Contains the Page Object classes. - - - `/`: Collection house for related page objects for each webpage or component. - - - `.ts`: Page Object for each webpage or component. - - - `utils/`: Utility functions and common helpers. - - - `helpers.ts`: Common utility functions (e.g., date formatting, data generation). - - - `test-data/`: Static test data files or folders for upload. - - - `filesForUpload/`: Static test data files for upload. - - - `config/`: Configuration files for Playwright and other tools. - - - `playwright.config.ts`: Playwright configuration. - - - `reports/`: Generated test reports (e.g., HTML, JSON). - - - `screenshots/`: Captured screenshots during test execution. - - - `videos/`: Recorded videos of test runs. - -## Test Structure - Arrange, Act, Assert: - -We can follow the AAA (Arrange, Act, Assert) pattern when structuring the tests. In most cases, the Arrange step can be included in a Before block(hook). -Consider including comments defining each section to ease readability. - -```typescript -// arrange, set up the initial conditions for the test -// create a property -await createProperty() - -// act, perform the action that you want to test -// raise a charge -// this could involve calling methods or functions defined in your page objects -await raiseCharge() - -// assert, verify that the action had the expected outcome -// confirm charge has been raised -expect(charge).toBe('raised') -``` - -## Page Object Model (POM) - -Every page should possess one POM file to enhance maintainability and scalability of our tests. It should include all the selectors and functions which are needed to interact with the UI page or component(s). - -All interactions should be done using the page objects, no selectors in your tests. - -All assertions should be in your test, no assertion in the POM - -DO 👍 - -```typescript -// POM file './pageOobjects/foo/' -// add all locators and functions related to the page. -// allowing all tests to reuse - -import { expect, Locator, Page } from '@playwright/test' - -export class FooPage { - readonly errorMessage: Locator - - constructor(page: Page) { - this.page = page - this.errorMessage = page.locator('.error-message') - } -} - -// test file './steps/foo.ts' -import { FooPage } from './pageObjects/foo' - -let fooPage: FooPage - -Then('error message should be visible', async function ({ page }) { - const fooPage = new FooPage({ page }) - await expect(fooPage.errorMessage).toBeVisible() -}) -``` - -DO NOT ⚔️ - -```typescript -// test file './steps/foo.ts' -// include locators directly in test -import { Locator, Page } from '@playwright/test' - -Then('error message should be visible', async function ({ page }) { - await expect(page.locator('.error-message')).toBeVisible() -}) -``` - -## Waiting: - -Playwright uses auto-waiting, so we avoid artificial waiting, the exception being if it is really necessary. - -DO NOT ⚔️ - -```typescript -await page.waitForTimeout(5000) -``` - -This can cause flaky tests as we can rarely be certain the amount of wait time is enough. It can also unnecessarily increase the test run time. Instead, we can try: - -DO 👍 - -```typescript -await page.goto(fooBarURL, { - waitUntil: 'domcontentloaded' + waitUntil: 'domcontentloaded', }) ``` @@ -641,7 +320,3 @@ Then the user should see an error message Incorrect username or password. """ ``` - -## Broad Gherkin Guidelines - -This [OpenCloud developer manual](https://docs.opencloud.eu/server/next/developer_manual/testing/acceptance-tests.html#how-to-write-acceptance-tests) provides comprehensive guidelines and best practices for writing acceptance tests using the Gherkin syntax, a widely adopted language for defining test scenarios in a human-readable format. The manual outlines the specific syntax and structure required when crafting feature files and scenarios to ensure consistency and maintainability within the OpenCloud testing framework. diff --git a/docs/dev/web/testing/running-tests.md b/docs/dev/web/testing/running-tests.md index 03154dd7..aeb524ca 100644 --- a/docs/dev/web/testing/running-tests.md +++ b/docs/dev/web/testing/running-tests.md @@ -4,20 +4,11 @@ sidebar_position: 1 id: running-tests --- - - ## Introduction In order to allow us to make changes quickly, often and with a high level of confidence, we heavily rely on tests within the `web` repository. -All the steps below require you to have the `web` repo cloned locally and dependencies installed. -This can be achieved by running - -```shell -$ git clone https://github.com/opencloud-eu/web.git -$ cd web -$ pnpm install -``` +This section assumes you have the Web development stack up and running. Please check out the [development setup docs](./../development/tooling.md#development-setup) if you haven't. ### Unit Tests @@ -27,7 +18,7 @@ We have a steadily growing coverage of unit tests. You can run them locally via $ pnpm test:unit ``` -You can also specify which tests to run by giving a path param, like so: `pnpm test:unit packages//tests/unit/path/to/test.spec.js`. +You can also specify which tests to run by giving a path param, like so: `pnpm test:unit packages//tests/unit/path/to/test.spec.ts`. #### Unit Test File Structure @@ -46,20 +37,14 @@ with only `describe` blocks and nested `it.todo("put your test description here" Our end-to-end test suite is built upon the [Playwright Framework](https://github.com/microsoft/playwright), which makes it easy to write tests, debug them and have them run cross-browser with minimal overhead. -#### Preparation - -Please make sure you have installed all dependencies and started the server(s) as described in [tooling](./../development/tooling.md). +#### Bundling Web -#### Prepare & Start Web - -Bundle the web frontend with the following command: +Make sure the Web frontend has been bundled with the following command since the dev server won't work: ```shell $ pnpm build:w ``` -Our compose setup automatically mounts it into an OpenCloud backend, respectively. Web also gets recompiled on changes. - #### Run E2E Tests The following command will run all available e2e tests: @@ -137,7 +122,7 @@ We can run some of the e2e tests on OpenCloud setup with Keycloak as an external #### Run OpenCloud With Keycloak -There's a documentation to serve [OpenCloud with Keycloak](https://docs.opencloud.eu/opencloud/deployment/opencloud_keycloak/). Please follow each step to run **OpenCloud with Keycloak**. +There's a documentation to serve [OpenCloud with Keycloak](./../../../admin/configuration/authentication-and-user-management/keycloak). Please follow each step to run **OpenCloud with Keycloak**. #### Run E2E Tests From 900e91f17afc78643674ffb865d35105a08ebfea Mon Sep 17 00:00:00 2001 From: Jannik Stehle <50302941+JammingBen@users.noreply.github.com> Date: Thu, 17 Apr 2025 07:46:02 +0200 Subject: [PATCH 2/2] docs: fix typos Co-authored-by: Phil Davis --- docs/dev/web/development/repo-structure.md | 2 +- docs/dev/web/extension-system/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/web/development/repo-structure.md b/docs/dev/web/development/repo-structure.md index a8369fb1..c65d56ca 100644 --- a/docs/dev/web/development/repo-structure.md +++ b/docs/dev/web/development/repo-structure.md @@ -65,7 +65,7 @@ unique and consistent look and feel and branding throughout the OpenCloud Web ec very own apps and extensions will blend in with all the others. Documentation and code examples can be found in the [design system documentation](https://docs.opencloud.eu/design-system/). -The OpenCloud Design System is a standalone project that gets published on npmjs.com as [@opencloud-eu/design-system](https://www.npmjs.com/package/@opencloud-eu/design-system). Since it's bundled with OpenCloud Web, you should not bundle it with your app or extension. However, you can add is as a dev dependency for better IDE support. +The OpenCloud Design System is a standalone project that gets published on npmjs.com as [@opencloud-eu/design-system](https://www.npmjs.com/package/@opencloud-eu/design-system). Since it's bundled with OpenCloud Web, you should not bundle it with your app or extension. However, you can add it as a dev dependency for better IDE support. ### web-client diff --git a/docs/dev/web/extension-system/index.md b/docs/dev/web/extension-system/index.md index e8a4bcc8..f5bfe42d 100644 --- a/docs/dev/web/extension-system/index.md +++ b/docs/dev/web/extension-system/index.md @@ -27,7 +27,7 @@ Feel free to contribute or just be inspired for your own apps or extensions. ### Apps -Apps define a `src/index.ts` file which act as an entrypoint. Below is the most basic example of its content: +Apps define a `src/index.ts` file which acts as an entrypoint. Below is the most basic example of its content: ```typescript import {