From dc292ed1fcb84352b437996f43adf2afff253a56 Mon Sep 17 00:00:00 2001 From: Jannik Stehle <50302941+JammingBen@users.noreply.github.com> Date: Tue, 8 Aug 2023 10:23:06 +0000 Subject: [PATCH] Merge pull request #9557 from owncloud/cherry-pick-sc-bump chore: bump sonarcloud to v5.0 (backport from master) --- development/tooling.md | 15 +++----- getting-started.md | 38 +++++++++++++------- testing/testing.md | 80 ++++++++++++++---------------------------- theming/_index.md | 21 +++++------ 4 files changed, 67 insertions(+), 87 deletions(-) diff --git a/development/tooling.md b/development/tooling.md index 2da762fb3ce..810dd4241bf 100644 --- a/development/tooling.md +++ b/development/tooling.md @@ -30,23 +30,16 @@ After cloning the source code, install the dependencies via `pnpm install`. ### Starting the Server -You can start the server by running `docker-compose up ocis`. +Web supports oCIS and oC10 as servers. You can start both of them by running `docker-compose up ocis oc10`. -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. +Note that `ocis` 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. ### 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. -Now you can access Web via https://host.docker.internal:9200. +Now you can access Web via https://host.docker.internal:9200 (oCIS) and http://host.docker.internal:8080 (OC10). ### 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. - -### Running Web with oC10 - -Older versions of Web (< 7.1.0) also support running oC10 as server. The development setup is nearly the same as mentioned above, the only differences are: - -* The server can be started via `docker-compose up oc10` -* The server port is `8080` (`8081` when running Web via `pnpm vite:oc10`) +To work with instant hot-reloading, you can also build Web by running `pnpm vite`. The ports to access Web are slightly different then: https://host.docker.internal:9201 (oCIS) and http://host.docker.internal:8081 (OC10). Also note that the initial page load may take a bit longer than usual. This is normal and to be expected. diff --git a/getting-started.md b/getting-started.md index badf3a54641..0632cdcdf16 100644 --- a/getting-started.md +++ b/getting-started.md @@ -1,5 +1,5 @@ --- -title: "Getting Started" +title: 'Getting Started' date: 2018-05-02T00:00:00+00:00 weight: 10 geekdocRepo: https://github.com/owncloud/web @@ -27,11 +27,13 @@ This setup currently doesn't work on Windows out of the box. After cloning the [source code](https://github.com/owncloud/web), install the dependencies via `pnpm install` and bundle the frontend code by running `pnpm build:w`. -Then, you can start the backends by running `docker-compose up oc10 ocis` and access them via [https://host.docker.internal:9200](https://host.docker.internal:9200) (oCIS) and [http://host.docker.internal:8080](http://host.docker.internal:8080) (OC10). If you're not using Docker Desktop, you might have to modify your `/etc/hosts` and add `172.17.0.1 docker.host.internal` to make the `host.docker.internal` links work. +Then, you can start the backends by running `docker-compose up oc10 ocis` and access them via [https://host.docker.internal:9200](https://host.docker.internal:9200) (oCIS) and [http://host.docker.internal:8080](http://host.docker.internal:8080) (OC10). 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. 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! -### Source code +For more details on how to set up Web for development, please see [tooling]({{< ref "tooling.md#development-setup" >}}). + +### Source Code The source code is hosted at [https://github.com/owncloud/web](https://github.com/owncloud/web). Please refer to the [build documentation for Web]({{< ref "./building.md" >}}). @@ -43,34 +45,44 @@ Depending on the backend you are using, there are sample config files provided i - `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.homeFolder` You can specify a folder that is used when the user navigates `home`. Navigating home gets triggered by clicking on the `All files` -menu item. The user will not be jailed in that directory. It simply serves as a default location. You can either provide a static location, or you can use -variables of the user object to come up with a user specific home path. This uses twig template variable style and allows you to pick a value or a -substring of a value of the authenticated user. Examples are `/Shares`, `/{{.Id}}` and `/{{substr 0 3 .Id}}/{{.Id}`. + menu item. The user will not be jailed in that directory. It simply serves as a default location. You can either provide a static location, or you can use + variables of the user object to come up with a user specific home path. This uses twig template variable style and allows you to pick a value or a + substring of a value of the authenticated user. Examples are `/Shares`, `/{{.Id}}` and `/{{substr 0 3 .Id}}/{{.Id}`. - `options.openAppsInTab` Configures whether apps and extensions generally should open in a new tab. Defaults to false. - `options.disablePreviews` Set this option to `true` to disable previews in all the different file listing views. The only list view that is not affected by this is the trash bin, as that doesn't allow showing previews at all. - `options.previewFileMimeTypes` Specifies which mimeTypes will be previewed in the ui. For example to only preview jpg and text files set this option to `["image/jpeg", "text/plain"]`. - `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.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 ownCloud 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://owncloud.com/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 `ownCloud 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 ownCloud team.` + - `options.feedbackLink.href` Set a different target URL for the feedback link. Make sure to prepend it with `http(s)://`. Defaults to `https://owncloud.com/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 `ownCloud 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 ownCloud team.` - `options.sharingRecipientsPerPage` Sets the amount of users shown as recipients in the dropdown when sharing resources. Default amount is 200. - `options.sidebar.shares.showAllOnLoad` Sets the list of (link) shares list in the sidebar to be initially expanded (default is a collapsed state, only showing the first three shares). -- `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.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`, and we recommend reaching out to [the ownCloud web team](https://talk.owncloud.com/channel/web) if you're not CERN and thinking about enabling this feature flag. - `options.cernFeatures` Enabling this will activate CERN-specific features. Defaults to `false`. - `options.hoverableQuickActions` Set this option to `true` to hide the quick actions (buttons appearing on file rows), and only show them when the user -hovers the row with his mouse. Defaults to `false`. + hovers the row with his mouse. Defaults to `false`. - `option.routing` This accepts an object with the following fields to customize the routing behaviour: - - `options.routing.idBased` Enable or disable fileIds being added to the URL. Defaults to `true` because otherwise e.g. spaces with name clashes can't be resolved correctly. Only disable this if you can guarantee server side that spaces of the same namespace can't have name clashes. + - `options.routing.idBased` Enable or disable fileIds being added to the URL. Defaults to `true` because otherwise e.g. spaces with name clashes can't be resolved correctly. Only disable this if you can guarantee server side that spaces of the same namespace can't have name clashes. - `options.upload.xhr.timeout` Specifies the timeout for XHR uploads in milliseconds. - `options.editor.autosaveEnabled` Specifies if the autosave for the editor apps is enabled. - `options.editor.autosaveInterval` Specifies the time interval for the autosave of editor apps in seconds. - `options.contextHelpersReadMore` Specifies whether the "Read more" link should be displayed or not. +- `options.openLinksWithDefaultApp` Specifies whether single file link shares should be opened with default app or not. +- `options.tokenStorageLocal` Specifies whether the access token will be stored in the local storage when set to `true` or in the session storage when set to `false`. If stored in the local storage, login state will be persisted across multiple browser tabs, means no additional logins are required. Defaults to `true`. + +#### Scripts and Styles + +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. + +- `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 }]`. ### Sentry diff --git a/testing/testing.md b/testing/testing.md index 85c9d4f5b41..01873c8df7e 100644 --- a/testing/testing.md +++ b/testing/testing.md @@ -1,5 +1,5 @@ --- -title: "Running tests" +title: 'Running tests' date: 2021-07-27T00:00:00+00:00 weight: 60 geekdocRepo: https://github.com/owncloud/web @@ -8,11 +8,12 @@ geekdocFilePath: testing.md --- {{< toc >}} + ## 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. +All the steps below require you to have the `web` repo cloned locally and dependencies installed. This can be achieved by running ```shell @@ -31,33 +32,28 @@ $ 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`. -#### Unit test file structure +#### Unit Test File Structure + Our unit tests spec files follow a simple structure: + - fixtures and mocks at the top - helper functions at the bottom - tests in between -We usually organize tests with nested `describe` blocks. If you would like to get feedback from the core team about -the structure, scope and goals of your unit tests before actually writing some, we invite you to make a pull request -with only `describe` blocks and nested `it.todo("put your test description here")` lines. +We usually organize tests with nested `describe` blocks. If you would like to get feedback from the core team about +the structure, scope and goals of your unit tests before actually writing some, we invite you to make a pull request +with only `describe` blocks and nested `it.todo("put your test description here")` lines. ### E2E Tests (Playwright) -Our end-to-end test suite is built upon the [Playwright Framework](https://github.com/microsoft/playwright), +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. -#### Prerequisites - -To run e2e tests with Docker, please make sure you have the following tools installed: +#### Preparation -- docker -- docker-compose (if not already included in your docker installation) -- pnpm -- node +Please make sure you have installed all dependencies and started the server(s) as described in [tooling]({{< ref "tooling.md#development-setup" >}}). -Please also make sure to point `host.docker.internal` to `127.0.0.1` by adding it to your `/etc/hosts` file. - -#### Prepare & start web +#### Prepare & Start Web Bundle the web frontend with the following command: @@ -67,23 +63,7 @@ $ pnpm build:w Our compose setup automatically mounts it into an oC10 and oCIS backend, respectively. Web also gets recompiled on changes. -#### Start Docker - -Using compose, you can start the required Docker containers by running - -For running the test with oc10 run -```shell -$ docker compose up oc10 -``` - -For running the test with ocis run -```shell -$ docker compose up ocis -``` - -and make sure there are no conflicting ports and everything runs smoothly. You can check if everything has worked by opening [https://host.docker.internal:9200](https://host.docker.internal:9200) (oCIS) and [http://host.docker.internal:8080](http://host.docker.internal:8080) (OC10) and logging in using the demo user (admin/admin). - -#### Run E2E tests +#### Run E2E Tests Depending on the backend you want to run the tests on, you can either run @@ -104,6 +84,7 @@ for an **oCIS** backend (filenames including `.oc10` are excluded). To run a particular test, simply add the feature file and line number to the test command, e.g. `pnpm test:e2e:cucumber tests/e2e/cucumber/shareFileJourney.feature:13` Various options are available via ENV variables, e.g. + - `OCIS=true` to run the E2E tests against an oCIS backend - `RETRY=n` to retry failures `n` times - `SLOW_MO=n` to slow the execution time by `n` milliseconds @@ -111,7 +92,7 @@ Various options are available via ENV variables, e.g. - `HEADLESS=bool` to open the browser while the tests run (defaults to true => headless mode) - `BROWSER=name` to run tests against a specific browser. Defaults to Chrome, available are Chrome, Firefox, Webkit, Chromium -For debugging reasons, you may want to record a video or traces of your test run. +For debugging reasons, you may want to record a video or traces of your test run. Again, you can use the following ENV variables in your command: - `REPORT_DIR=another/path` to set a directory for your recorded files (defaults to "reports") @@ -128,8 +109,8 @@ $ npx playwright show-trace path/to/file.zip ### Acceptance Tests (Nightwatch) {{< hint info >}} -We've decided to switch to playwright for end-to-end tests. As we steadily increase the coverage of our playwright -based e2e tests we keep the existing nightwatch based e2e tests maintained. However, we decided to not add new scenarios +We've decided to switch to playwright for end-to-end tests. As we steadily increase the coverage of our playwright +based e2e tests we keep the existing nightwatch based e2e tests maintained. However, we decided to not add new scenarios to the nightwatch based e2e tests anymore. In other words: only continue reading about our nightwatch based acceptance tests below if you need to debug a failing test. @@ -137,18 +118,11 @@ In other words: only continue reading about our nightwatch based acceptance test At ownCloud, we have decided to adopt Docker as the main environment for developing our application. This also applies for running our acceptance tests. -#### Prerequisites +#### Preparation -To run acceptance tests with Docker, please make sure you have the following tools installed: +Please make sure you have installed all dependencies and started the server(s) as described in [tooling]({{< ref "tooling.md#development-setup" >}}). -- docker -- docker-compose (if not already included in your docker installation) -- pnpm -- node - -Please also make sure to point `http://host.docker.internal/` to `127.0.0.1` by adding it to your hosts. - -#### Prepare & start web +#### Prepare & Start Web Bundle the web frontend, which then gets mounted into the respective backends. It also gets recompiled on changes. @@ -158,14 +132,16 @@ $ pnpm build:w #### Start Docker -Using compose, you can start the required Docker containers by running +The acceptance tests need additional docker containers to be running. For running the test with oc10 run + ```shell $ docker compose up oc10 vnc selenium middleware-oc10 ``` For running the test with ocis run + ```shell $ docker compose up ocis vnc selenium middleware-ocis ``` @@ -192,13 +168,11 @@ If you're using a M1 Mac, you need to use `seleniarm/standalone-chromium:4.4.0-2 for oCIS acceptance tests. - -#### Watch the test run +#### Watch the Test Run To watch the tests while running, open [http://host.docker.internal:6080/](http://host.docker.internal:6080/) in the browser to access your VNC client. - -### Analyze the test report +### Analyze the Test Report The cucumber library is used as the test runner for both e2e and acceptance tests. The report generator script lives inside the `tests/e2e/cucumber/report` folder. If you want to create a report after the tests are done, run the command: @@ -213,7 +187,7 @@ node tests/e2e/cucumber/report --report-input=tests/acceptance/report/report.jso ``` By default, the report gets generated to reports/e2e/cucumber/releaseReport/cucumber_report.html. -The location can be changed by adding the ```--report-location``` flag. +The location can be changed by adding the `--report-location` flag. To see all available options run diff --git a/theming/_index.md b/theming/_index.md index 36bbd51f28a..a4ac513155a 100644 --- a/theming/_index.md +++ b/theming/_index.md @@ -1,5 +1,5 @@ --- -title: "Theming" +title: 'Theming' date: 2021-04-01T00:00:00+00:00 weight: 55 geekdocRepo: https://github.com/owncloud/web @@ -82,7 +82,6 @@ Using the `"autoRedirect"` boolean, you can specify whether the user is shown a To further customize your ownCloud instance, you can provide your own styles. To give you an idea of how a working design system looks like, feel free to head over to the [ownCloud design tokens](https://owncloud.design/#/Design%20Tokens) for inspiration. - **Hint:** All the variables are initialized using the [ownCloud design tokens](https://owncloud.design/#/Design%20Tokens) and then overwritten by your theme variables. Therefore, you don't have to provide all the variables and can use the default ownCloud colors as a fallback. In general, the theme loader looks for a `designTokens` key inside your theme configuration. Inside the `designTokens`, it expects to find a `colorPalette`, `fontSizes` and `spacing` collection. The structure is outlined below: @@ -117,8 +116,7 @@ If you define different key-value pairs inside any of the objects in `"designTok If you'd like to set different breakpoints than the default ones in the ownCloud design system, you can set them using theming variables. -Breakpoint variables get prepended with `--oc-breakpoint-`, so e.g. *"large-default"* creates the custom CSS property `--oc-breakpoint-large-default`. - +Breakpoint variables get prepended with `--oc-breakpoint-`, so e.g. _"large-default"_ creates the custom CSS property `--oc-breakpoint-large-default`. ```json { @@ -139,7 +137,7 @@ Breakpoint variables get prepended with `--oc-breakpoint-`, so e.g. *"large-defa For the color values, you can use any valid CSS color format, e.g. **hex** (#fff), **rgb** (rgb(255,255,255)) or **color names** (white). -Color variables get prepended with `--oc-color-`, so e.g. *"background-default"* creates the custom CSS property `--oc-color-background-default`. +Color variables get prepended with `--oc-color-`, so e.g. _"background-default"_ creates the custom CSS property `--oc-color-background-default`. Again, you can use the [ownCloud design tokens](https://owncloud.design/#/Design%20Tokens) as a reference implementation. @@ -168,12 +166,15 @@ Again, you can use the [ownCloud design tokens](https://owncloud.design/#/Design "swatch-inverse-muted": "", "swatch-passive-default": "", "swatch-passive-hover": "", + "swatch-passive-hover-outline": "", "swatch-passive-muted": "", "swatch-passive-contrast": "", "swatch-primary-default": "", "swatch-primary-hover": "", "swatch-primary-muted": "", + "swatch-primary-muted-hover": "", "swatch-primary-gradient": "", + "swatch-primary-gradient-hover": "", "swatch-primary-contrast": "", "swatch-success-default": "", "swatch-success-hover": "", @@ -194,7 +195,7 @@ Again, you can use the [ownCloud design tokens](https://owncloud.design/#/Design You can change the `default`, `large` and `medium` font sizes according to your needs. If you need more customization options regarding font sizes, please [open an issue on GitHub](https://github.com/owncloud/web/issues/new) with a detailed description. -Font size variables get prepended with `--oc-font-size-`, so e.g. *"default"* creates the custom CSS property `--oc-font-size-default`. +Font size variables get prepended with `--oc-font-size-`, so e.g. _"default"_ creates the custom CSS property `--oc-font-size-default`. ```json { @@ -220,10 +221,10 @@ Please note that you also need to make the font available as a `font-face` via C ### Sizes -Use sizing variables to change various UI elements, such as icon and logo appearance, table row or checkbox sizes, according to your needs. +Use sizing variables to change various UI elements, such as icon and logo appearance, table row or checkbox sizes, according to your needs. If you need more customization options regarding sizes, please [open an issue on GitHub](https://github.com/owncloud/web/issues/new) with a detailed description. -Size variables get prepended with `--oc-size-`, so e.g. *"icon-default"* creates the custom CSS property `--oc-size-icon-default`. +Size variables get prepended with `--oc-size-`, so e.g. _"icon-default"_ creates the custom CSS property `--oc-size-icon-default`. ```json { @@ -243,7 +244,7 @@ Size variables get prepended with `--oc-size-`, so e.g. *"icon-default"* creates Use the six spacing options (`xsmall | small | medium | large | xlarge | xxlarge`) to create a more (or less) condensed version of the user interface. If you need more customization options regarding sizes, please [open an issue on GitHub](https://github.com/owncloud/web/issues/new) with a detailed description. -Spacing variables get prepended with `--oc-space-`, so e.g. *"xlarge"* creates the custom CSS property `--oc-space-xlarge`. +Spacing variables get prepended with `--oc-space-`, so e.g. _"xlarge"_ creates the custom CSS property `--oc-space-xlarge`. ```json { @@ -264,7 +265,7 @@ An empty template for your custom theme is provided below, and you can use the i ```json { - "common": { + "common": { "name": "", "slogan": "", "logo": ""