references/openproject
1
0
Fork 0
mirror of https://github.com/opf/openproject.git synced 2026-06-14 03:30:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

typo hunting an phrasing

Browse Source 
[ci skip]

Signed-off-by: Florian Kraft <f.kraft@finn.de>
This commit is contained in:
Florian Kraft
2015-08-14 13:14:21 +02:00
parent 44d09c5cc4
commit d47591675f
7 changed files with 81 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/doc/API.md
+18 -18
View File
@@ -1,21 +1,21 @@
API Handling
============
In general, the OpenProject Frontend uses _all_ of the existing working APIs to provide it's functionality. This is due to the fact that the goals for `APIv3` have not yet been reached and it is not feature complete.
In general, the OpenProject Frontend uses _all_ of the existing working APIs to provide its functionality, as the current working version for `APIv3` is not feature complete.
The documentation for these APIs and their capabilities:
- [APIv3](http://opf.github.io/apiv3-doc/)
- APIv2 docs are located in the `opf/openproject` repo at `./doc/apiv2-documentation.md`
- there is no documentation on the experimental API
- APIv2 docs are located in the `opf/openproject` repository at `./doc/apiv2-documentation.md`
- There is no documentation on the experimental API
To get a feel for which API is used at which point, please refer to the `PathHelper` located at `./frontend/app/helpers/path-helper.js`. It is used throughout the application to centralize knowledge about paths.
To get a feeling for which API is used at which point, please refer to the `PathHelper` located at `./frontend/app/helpers/path-helper.js`. It is used throughout the application to centralize knowledge about paths.
## HAL
While having a `PathHelper` certainly helps, the long-term idea is to leverage the [HAL](http://stateless.co/hal_specification.html)-capabilities of the APIv3 (thereby excluding `v2` and `experimental` long term) to let any client discover the paths in the api by inspecting the responses from any given call.
While having a `PathHelper` certainly helps, the long-term idea is to leverage the [HAL](http://stateless.co/hal_specification.html)-capabilities of the APIv3 (thereby leaving `v2` and `experimental` behind) to let any client discover the paths available for a resource by inspecting the responses from any given call.
__Note:__ All responses from the APIv3 are thereby of `Content-Type: application/hal+json` and not just `Content-Type: application/json`. Some developer client tools sometimes get confused with that and do not interpret the formatting correctly.
__Note:__ All responses from the APIv3 are thereby of `Content-Type: application/hal+json` and not just `Content-Type: application/json`. Some developer client tools sometimes get confused with that and will not interpret the formatting correctly.
Example:
@@ -48,33 +48,33 @@ Example:
}
```
The project structure contains links to ressources associated. At the time of writing, there is no ticket endpoint in the API, but just to give an example of using this, given the knowledge about `_links`, one may easily infer the path from the response:
The `Project` structure contains links to ressources associated. At the time of writing, there is no ticket endpoint in the API, but just to give an example of using this, given the knowledge about `_links`, one may easily infer the path from the response:
```javascript
// some magic to retrieve an object, note that the services used are examplary
// and not to be found in the actual codebase
// and can not be found in the actual codebase
ProjectsService.getProject('project_identifier').then(function(project) {
var pathtoVersions = project._links.versions.href;
// the VersionsService has knowledge about pathtoVersions in its
var pathToVersions = project._links.versions.href;
// the VersionsService has knowledge about pathToVersions in its
// forProject method
VersionsService.forProject(project).then(function(versions) {
// versions should be the result of the call to pathtoVersions
console.log(versions);
})
})
});
});
```
This is, in principle a very good concept to delegate responsibility of inference to the client and absolves the client of having to know each path in the application.
This is in principle a very good concept to delegate responsibility of inference to the client and absolves the client of having to know each path in the application in advance.
## Using hyperagent.js
In practise however, the OpenProject frontend use a fork of [`hyperagent.js`](https://github.com/weluse/hyperagent) (actually [this one from a former colleague is used](https://github.com/manwithtwowatches/hyperagent)).
For all practical purposes, the OpenProject frontend uses a fork of [`hyperagent.js`](https://github.com/weluse/hyperagent) (actually [this one is used](https://github.com/manwithtwowatches/hyperagent)).
`hyperagent.js` aims to provide an interface to a structed JSON response, providing a resource object automatically. While this is a nice goal, the current implementation used in the frontend is not complete.
`hyperagent.js` aims to provide an interface to a structed JSON response, providing a resource object automatically. While this is a nice goal, the current implementation used is not complete.
The library has been wrapped as a service in `./frontend/app/api/hal-api-resource.js` and can be injected when needed.
What the service actually does is making resouce objects out out of certain API responses (`v3` only) and providing `LazyResource`s to attached links. This is also the difference to using `_links` and `links` as a property sometimes:
What the service actually does is making resource objects out out of certain API responses (`v3` only) and providing `LazyResource`s to attached links. This is also the difference to using `_links` and `links` as a property sometimes:
```javascript
//@see ./frontend/app/work_packages/services/work-package-attachments-service.js
@@ -86,6 +86,6 @@ var addAttachmentPath = workPackage.links.addAttachment.url();
var addAttachmentPath = workPackage._links.addAttachment.href;
```
One of the minor drawbacks of `hyperagent.js` is that it only supports `GET` requests at the moment and one has to awkwardly inject the `method` desired into the `options` of the AJAX call made (see also the `setup` method of `hal-api-resource.js`, as well as an example in `loadWorkPackageForm` in `./frontend/app/services/work-package-service.js`).
One of the minor drawbacks of `hyperagent.js` is that it (_read_: the fork used) only supports `GET` requests at the moment and one has to awkwardly inject the `method` desired into the `options` of the AJAX call made (see also the `setup` method of `hal-api-resource.js`, as well as an example in `loadWorkPackageForm` in `./frontend/app/services/work-package-service.js`).
The goal should be to leverage `angular.$http` and make the calls accordingly. One of the short term goals should be to remove duplication introduced when building requests via the `HALAPIResource`.
__Note__: The long term goal should be to leverage `angular.$http` and make the calls accordingly. One of the short term goals should be to remove duplication introduced when building requests via the `HALAPIResource`.
frontend/doc/BUILD.md
+9 -12
View File
@@ -3,21 +3,21 @@ Building
__Note__: All tasks involved are found in `./frontend/gulpfile.js`
All builds of the frontend are built via and put into Rails' asset pipeline. Builds are run via [`gulp`](http://gulpjs.com/). The actual build, i.e. merging all components together is done via [`webpack`](https://github.com/webpack/webpack).
All builds are put into Rails' asset pipeline. Builds are run via [`gulp`](http://gulpjs.com/). The actual build, i.e. merging all components together is done via [`webpack`](https://github.com/webpack/webpack).
It __is important to note__ that OpenProject currently still relies on the asset pipeline to serve the assets. Minification is also done via `rake assets:precompile` and does __not__ happen in the `gulp` based pipeline.
It __is important to note__ that OpenProject currently still relies on the asset pipeline to serve the assets. Minification is done via `rake assets:precompile` and does __not__ happen in the `gulp` based pipeline.
Two types of build are performed, the first one is the a OpenProject Standalone JS, which is not required by the Rails views per se and the global dependencies, which are necessary for the rails view to run.
Two types of builds are performed, the first one is the OpenProject Standalone JS, which is not required by the Rails views per se. The second one is a bundle of global dependencies, which are necessary for the Rails views to run properly.
The configuration for building both global and standalone JS is found in `./frontend/webpack.config.js`
## Building OpenProject JS
## Building OpenProject Standalone JS
The resulting output of this buildstep can be found in `./app/assets/javascripts/bundles/openproject-core-app.js`
This is done via `gulp webpack` (see `gulpfile.js`, Line 63 ff.). The actual entrypoint for this is `./frontend/app/openproject-app.js`.
It contains only the the JavaScript needed for the AngularJS based part of the codebase.
It contains only the the JavaScript needed for the AngularJS based part of the codebase (and `lodash`).
## Building globals
@@ -29,9 +29,9 @@ It contains all of the JavaScript necessary for the rails based views, like part
## Building Sass
Sass files are built via `gulp sass`, which handles the main sass file from the Rails stack at `./app/assets/stylesheets/defaults.css.sass`, performs transformations on it and outputs the result to `./frontend/public/assets`. It __is important__ to note, that this serves not the compilation of Sass for production purposes but is mostly for the availability of the CSS for the Living Styleguide.
Sass files are built via `gulp sass`, which handles the main Sass file from the Rails stack at `./app/assets/stylesheets/defaults.css.sass`, performs transformations on it and outputs the result to `./frontend/public/assets`. It __is important__ to note, that this serves __not__ the compilation of Sass for production purposes but is mostly for the availability of the CSS for the Living Styleguide.
The Sass files in the rails stack are handled as one would expect - they are precompiled into one `default-*.css` for production and are reloaded on demand during development. The manifest for this can be found in `./app/assets/stylesheets/defaults.css.sass`.
The Sass files in the rails stack are handled as one would expect: They are precompiled into one `default-*.css` for production and are reloaded on demand during development. The manifest for this can be found in `./app/assets/stylesheets/defaults.css.sass`.
### Important note on Frameworks:
@@ -39,11 +39,8 @@ OpenProject relies on the [Foundation for Apps Framework](http://foundation.zurb
They are provided via LoadPath manipulation in the `gulp` based pipeline.The two frameworks are included as `bower` components (see `./frontend/bower.json`).
On the rails side, both frameworks are included as gems - see the `./Gemfile` - and plug directly into Rails' asset pipeline.
On the Rails side, both frameworks are included as gems - see the `./Gemfile` - and plugged directly into Rails' asset pipeline.
## Misc Tasks
The build pipeline is also responsible for building the [Living Styleguide](https://github.com/livingstyleguide/livingstyleguide), relying heavily on the duplicated functionality of the `gulp` tasks revolving around sass compilation
The build pipeline is also responsible for building the [Living Styleguide](https://github.com/livingstyleguide/livingstyleguide), relying heavily on the duplicated functionality of the `gulp` tasks revolving around Sass compilation
frontend/doc/MISC.md
+5 -5
View File
@@ -8,7 +8,7 @@ There are three ways of passing information from Rails to `angular`:
1. Using tag attributes written directly to the DOM by the rendering process of Rails:
```html
// @see ./app/views/layouts/angular.html.erb
<!-- @see ./app/views/layouts/angular.html.erb -->
<body class="<%= body_css_classes %>" ng-app="openproject" data-relative_url_root="<%= root_path %>" ng-init="projectIdentifier = '<%= (@project.identifier rescue '') %>'">
<!-- [..] -->
</body>
@@ -22,13 +22,13 @@ This is included by all layouts in `<head>`:
<%= include_gon %>
```
`gon` will provide arbitrary settings from Rails to all JavaScript functionality, including `angular`. In an `angular` context a `ConfigurationService` is provided.
`gon` will provide arbitrary settings from Rails to all JavaScript functionality, including `angular`. In an `angular` context a `ConfigurationService` is provided for picking up the settings.
3. From the APIv3
APIv3 introduces a settings endpoint which can be used to query settings from the API directly. This is useful for querying user specific settings and guarded information.
APIv3 introduces a settings endpoint which can be used to query settings from the API directly (see [here for more information](http://opf.github.io/apiv3-doc/#configuration)). This is useful for querying user specific settings and guarded information. _The endpoint is not complete at the time of writing_
The only place this is currently used is within the `ConfigurationService`, which provides an `api`, which can be used in this fashion:
The only place this is currently used is within the `ConfigurationService`, which provides an `api`, which can be used like this:
```javascript
// angular injected
@@ -53,4 +53,4 @@ angular
])
```
Calls to the API are cached between page reloads. It would be advisable to cache them longer in the future, as the data rarely updates.
Calls to the API are cached between page reloads. It would be advisable to cache them longer (e.g. in `localStorage`) in the future, as the data rarely updates.
frontend/doc/OVERVIEW.md
+7 -5
View File
@@ -64,7 +64,7 @@ This is the general structure (to a depth of 3 folders):
## The `app` folder
This is where most of the magic happens. Contains all of the production relevant code for excuting the individual parts of the frontend. Does __not__ contain the test code.
This can be considered the main `src` folder. It contains all of the production relevant code for excuting the individual parts of the frontend. It does __not__ contain the test code.
The `app` folder is furthermore divided into:
@@ -77,7 +77,7 @@ The common components are divided into their usual use cases and are available t
## Using `index.js` to define modules
Most directories contain an `index.js` defining what is actually required in the build process. The `index.js` can be seen as a sort of manifest defining what gets included and what not. __However__ this is slightly misleading, as the code in `index.js` is actually functional, definiing many `angular` modules.
Most directories contain an `index.js` defining what is actually required in the build process. The `index.js` can be seen as a manifest defining what gets included and what not. _However_ this is slightly misleading, as the code in `index.js` is actually functional, defining many `angular` modules.
### Example: `timeEntries`
@@ -95,9 +95,9 @@ angular.module('openproject.timeEntries.controllers')
The file consists of a single module definition, that requires another file (`./frontend/app/time_entries/controllers/time-entries-controller.js`), which contains the actual controller function.
The files mostly follow the __Asynchronous Module Defintion__ (AMD), so the different parts of the application can be isolated.
The files follow the __Asynchronous Module Defintion__ (AMD), so the different parts of the application can be isolated.
However, this makes planning the injections abit harder, as they are spread out over two files (the `$injector` definition being in the respective `index.js`, the actual function signature being in the module itself.)
This makes planning the injections a bit harder, as they are spread out over two files (the `$injector` definition being in the respective `index.js`, the actual function signature being in the module itself.)
## Template handling in `./frontend/app/templates`
@@ -118,5 +118,7 @@ angular.module('foo')
In this example, what would usually happen during compilation is the asynchronous loading of `/templates/foo/test-directive.html`.
As there are quite a few directives, the OpenProject frontend prevents the request to the server by using `angular.$templateCache`. Using a buildstep in the `gulp` process (via `webpack` actually): templates are compiled as JS and put alongside the rest of the code in `openproject-core-app.js`. The `loader` for the templates can be found in `./frontend/webpack.config.js` which is dependent on [`ngtemplate-loader`](https://github.com/WearyMonkey/ngtemplate-loader).
As there are quite a few directives, the OpenProject frontend prevents the request to the server by using `angular.$templateCache`.
Using a buildstep in the `gulp` process (via `webpack` actually): templates are compiled as JS and put alongside the rest of the code in `openproject-core-app.js`. The `loader` for the templates can be found in `./frontend/webpack.config.js` which is dependent on [`ngtemplate-loader`](https://github.com/WearyMonkey/ngtemplate-loader).
frontend/doc/RAILS.md
+14 -13
View File
@@ -1,26 +1,26 @@
Legacy Frontend in Rails
========================
__Important__: There are no explicit tests for the legacy frontend code, however, most of it is covered by Capybara based specs.
__Important__: There are no explicit tests for the legacy frontend code - most of it is covered by Capybara based specs.
## `application.js.erb`
The manifest file osts a plethora of additional javascript used throughout the application. It still maintains it's function as the original manifest used for the asset pipeline.
The manifest file hosts a plethora of additional JavaScript used throughout the application. It still maintains it's function as the original manifest used for the asset pipeline.
If you really do have to add some javascript which ties into either
If you really do have to add some JavaScript which ties into either
- legacy views (i.e. non-angular views, of which there are plenty)
- legacy views (i.e. non-`angular` views, of which there are plenty)
- component based JS (`tooltip.js` is an example)
you should create another JS file in `./app/assets/javascripts` and use the manifest as you would in any other Rails application.
Long term goal here should be to get rid of the JavaScript put directly into `application.js.erb`
The goal here should be to get rid of the JavaScript put directly into `application.js.erb`.
### Tie in with `angular`
The line between the original JavaScript and the "legacy" JavaScript is a little bit blurred, as there are cases where `jQuery` based JavaScript has to rely on existing `angular` behaviour and vice versa.
an exmaple would be the use of the `AutoCompleteHelper` (see `./frontend/app/helpers/auto-complete-helper.js`) in the WorkPackage Legacy form:
An example would be the use of the `AutoCompleteHelper` (see `./frontend/app/helpers/auto-complete-helper.js`) in the old WorkPackage form, after an HTML form has been loaded into the existing DOM after the user has decided to update the Work Package):
```javascript
//@see ./app/assets/javascripts/work_packages.js.erb
@@ -36,32 +36,33 @@ injector.invoke(['AutoCompleteHelper', function(AutoCompleteHelper) {
}]);
```
__Note__: In the above example, a scope is assumed for the elements passed to the service. The full implmentation is a bit more esoteric, as one will have to manually create a `scope`. around newly generated elements.
__Note__: In the above example, a scope is assumed for the elements passed to the service. The full implementation is a bit more esoteric, as one will have to manually create a `scope` around newly generated elements.
## Legacy views in Rails
"Legacy views" are mostly views working with plain JavaScript, of which the most part is hosted in `application.js.erb`.
"Legacy views" are mostly views working with plain JavaScript, of which the most is found in `application.js.erb`.
Also, all of the plugins mainly use their own JavaScript to enable the functionality of these views.
Also, all of the plugins mainly use their own JavaScript to enable the functionality of their views.
The only views that currently rely on `angular` are:
- Work Packages List
- Timelines
- some private plugins
That should change over the course of development, especially to get rid of the `prototype.js` dependecy long term.
That should change over the course of development, especially to get rid of the `prototype.js` dependency.
Keep in mind, that there are places in the aplication, where JavaScript code is safely sored away in a ruby method, an example would be the `ApplicationHelper`s own `user_specific_javascript_includes`.
Keep in mind, that there are places in the application where JavaScript code is safely stored away in a ruby method, an example would be the `ApplicationHelper`s own `user_specific_javascript_includes`.
A quick search for `jQuery` over all ruby files usually yields very good starting points and clues how and where to start refactoring.
## `protoype.js` and plugins
Prototype and all of it's related plugins are used in several of OpenProjects plugins.
Prototype and some of it's related plugins are used in several of OpenProjects plugins.
One extreme example is [`MyProjectPage`](https://github.com/finnlabs/openproject-my_project_page), which duplicates functionality from the core application. It uses [`Sortable`](http://madrobby.github.io/scriptaculous/sortable/) to achieve drag and drop functionality. It's a very old library (~2009) that is not maintained actively anymore.
Be that as it may, the `prototype.js` dependency cannot be fully removed until all of the plugins do not use `prototype.js` anymore.
Be that as it may, the `prototype.js` dependency cannot be fully removed as long as the plugins rely on it.
There are basically two approaches here:
frontend/doc/STYLING.md
+8 -8
View File
@@ -1,9 +1,9 @@
Styling the frontend
====================
Frontend styling is coupled to the Living Styleguide. The guide implements the same CSS that the usual frontend does. It takes the very same Sass files used in the Asset pipeline to build a second css file that is then used for diplaying the guide.
Frontend styling is coupled to the Living Styleguide. The guide implements the same CSS that the application does. It takes the very same Sass files used in the Asset pipeline to build a second css file that is then used for diplaying the guide.
All styles for OpenProject itself are found in `./app/assets/stylesheets`. The frontend folder contains no styling, besides rendered files and some styling for the styleguide itself.
All styles for OpenProject are found in `./app/assets/stylesheets`. The frontend folder contains no styling, besides rendered files and some styling for the styleguide itself.
## Building
@@ -40,11 +40,11 @@ _accounts.sass
The `lsg` is simple markdown containing information on how to use the component described.
Ideally, this should be only one component per Sass partial, but this is not always possible, as seen in the cases of e.g. `./app/assets/stylesheets/content/_work_packages.sass` which describes an area of theapplication instead of a single component.
Ideally, this should be only one component per Sass partial, but this is not always possible, as seen in the case of `./app/assets/stylesheets/content/_work_packages.sass` which describes an area of the application instead of a single component.
### Getting JavaScript to work with the Styleguide
In an ideal world, the styleguide would convey only styling-related information. Unfortunately, for practical purposes such as styling `ui.select`, which require some JavaScript to be active, the styleguide intorduces some custom JavaScript:
In an ideal world, the styleguide would convey only styling-related information. Unfortunately, for practical purposes such as styling `ui.select` which requires some JavaScript to be active, the styleguide introduces some custom JavaScript:
```jade
//from styleguide.jade
@@ -62,12 +62,12 @@ app.use('/assets', express.static(railsRoot + '/app/assets/javascripts'));
app.use('/assets', express.static(railsRoot + '/app/assets/images'));
```
which enables asset serving from the respective Rails directories.
This enables asset serving from the respective Rails directories.
If you want to add more JavaScript to it, you can directly include it in the `styleguide.jade`, but it is ill-advised. The styleguide should be used for the styling of the rendered output and not necessarily display functionality, mostly to avoid duplication of code (use a test to demonstrate functionality!).
If you want to add more JavaScript to it, you can directly include it in the `styleguide.jade`, _but_ it is ill-advised. The styleguide should be used for the styling of the rendered output and not necessarily display functionality, mostly to avoid duplication of code (use a test to demonstrate functionality!).
## A note on the css style used
Originally introduced by @myabc, Sass-Code should ideally follow a convention as described in [Simple naming for CSS class names](http://www.hagenburger.net/BLOG/Modular-CSS-Class-Names.html).
Originally introduced by `@myabc`, Sass-Code should ideally follow a convention as described in [Simple naming for CSS class names](http://www.hagenburger.net/BLOG/Modular-CSS-Class-Names.html).
So far, we mostly used Sass partials, grouped by their component, however, there is still a lot of legacy code in there, especially in the plugins. The legacy code for the core can be found within `./app/assets/stylesheets/_misc_legacy.sass`
So far, mostly Sass partials have been used, grouped by their component. There is still a lot of legacy code in there, especially in the plugins. The legacy code for the core can be found within `./app/assets/stylesheets/_misc_legacy.sass`
frontend/doc/TESTING.md
+20 -19
View File
@@ -13,7 +13,7 @@ All of these are currently run on TravisCI for each push and each Pull Request.
__Note__: the default browser for testing is [PhantomJS](http://phantomjs.org). The configuration for all of this can be found at `/frontend/karma.conf.js`.
All test files for `karma` live under `./frontend/tests/unit/tests`. There are some `factories` and `mocks` present, which at some point in time were usable via `rosie.js`.
All test files for `karma` live in `./frontend/tests/unit/tests`. There are some `factories` and `mocks` present, which at some point in time were usable via [`rosie.js`](https://github.com/bkeepers/rosie).
Karma unit tests can be executed via
@@ -27,28 +27,29 @@ Optionally, if more than the default browser should be used, a `--browsers` flag
./frontend/node_modules/.bin/karma start --browsers PhantomJS,Firefox
```
By default, this command will wait and watch the test files and run the tests again, if something changes. If only one run is required, use a `--single-run` flag.
By default, this command will wait and watch the test files and run the tests again if something changes. If only one run is required, use a `--single-run` flag.
You may also want to use `npm` from the project root:
```
npm karma
```bash
# shorthand for ./frontend/node_modules/.bin/karma start --browsers PhantomJS,Firefox --single-run
$ npm karma
```
The tests use [`mocha`](https://mochajs.org/) for it's test syntax. With a syntax looking like this
The tests use [`mocha`](https://mochajs.org/) for it's test syntax. With a syntax looking like this:
```javascript
describe('my new feature', function() {
/* tests */
})
});
```
individual parts of the test suite can easily be run independently from the suite by adding `.only` to the DSLs constructs (`describe`, `context`, `it`):
Individual parts of the test suite can easily be run independently from the suite by adding `.only` to the DSLs constructs (`describe`, `context`, `it`):
```javascript
describe.only('my new feature', function() {
/* tests */
})
});
```
### Note on Templates
@@ -59,16 +60,18 @@ The karma runner uses a plugin to precompile the templates for directive tests c
__Note__: All of the test files live in `./frontend/tests/integration/specs`.
The protractor based suite offers integration tests for the Angular based views, first and foremost, the WorkPackage application. It's based on AngularJS' own [protractor library](https://github.com/angular/protractor) and therefore requires Selenium.
The protractor based suite offers integration tests for the `angular` based views, first and foremost, the WorkPackage (list) application. It's based on `angular`s own [protractor library](https://github.com/angular/protractor) and therefore requires Selenium.
It does not offer real End to End (E2E) Testing,a s there is currently no way to start up the whole application beforehand, so the suite uses a mock server and mock json to test each component independently and in the context of a page.
It does not offer real End to End (E2E) Testing, as there is currently no way to start up the whole application beforehand, so the suite uses a mock server and mock json to test each component independently and in the context of a page.
Every command related to the suite is wrapped via `gulp`. the most interesting commands are:
Every command related to the suite is wrapped via `gulp`. The commands are:
- `gulp tests:protractor` - starts up a server, recompiles the codebase necessary and starts a single run via protractor.
- `gulp webdriver:*` - the webdriver tasks are in there to update the selenium server necessary to run protractor at all
- `npm protractor` - a wrapper around `gulp tests:protractor`, runnable from the project root
__Note__: Protractor process uses the same static server as the styleguide. All assets are served from `./frontend/public`. To get a grip on the entry point, see `./frontend/public/index.html`.
The `protractor` library brings it's own syntax when it comes to writing the tests themselves:
```javascript
@@ -84,7 +87,7 @@ describe('edit state', function() {
Tests can be focused by using `iit` (not a typo) instead of `it` and can be ignored by using `xit` instead of it.
Configuration is done in `./frontend/tests/integration/protractor.conf.js`. The only usable browser right now for protractor is Firefox. That is, you can change your browser locally to Chrome if you want to, however, TravisCI so far only supports running tests via Firefox.
Configuration is done in `./frontend/tests/integration/protractor.conf.js`. The only usable browser right now for protractor is Firefox. You can change your browser locally to Chrome if you want to, however, TravisCI so far only supports running tests via Firefox.
The protractor suite currently only covers the work packages list and provides no integration testing for timelines and the other components (most of them are tested as collateral).
@@ -92,19 +95,19 @@ The protractor suite currently only covers the work packages list and provides n
As the backend ist not present during testing, the protractor suite actually uses mocked json responses to facilitate the behaviour of data when testing the components.
__Note:__ All mocks are found under `./frontend/tests/integration/mocks/` and a re usually loaded via a custom function defined in the tests which wrap `WorkPackageDetailsPane`, which in turn wraps a call to `browser.get()` (see `./frontend/tests/integration/pages/work-package-details-pane.js`)
__Note:__ All mocks are found under `./frontend/tests/integration/mocks/` and are usually loaded via a custom function defined in the tests which wrap `WorkPackageDetailsPane`, which in turn wraps a call to `browser.get()` (see `./frontend/tests/integration/pages/work-package-details-pane.js`)
A mock usually just represents a probable json response from the backend. As the protractor suite does not use the Rails backend, this can be a source of confusion:
__Make sure you keep your mocks in sync with the current implementation of the API__. Otherwise, you will not be able to detect problems with the API and/or your component.
__Make sure you keep your mocks in sync with the current implementation of the API__. Otherwise you will not be able to detect problems with the API and/or your component.
### Dummy servers
The protractor suite also used dummy services to mock out the endpoints of all of the APIs for mocking. these files are still found under `./frontend/tests/integration/mocks/`. These can probably be removed in future versions.
The protractor suite also used dummy services to mock out the endpoints of all of the APIs. These files are still found under `./frontend/tests/integration/mocks/` and can probably be removed in future versions.
## Capybara/Cucumber/RSpec E2E Testing
The heavy lifting is done via these Testsuites, which are tightly integrated with the Rails stack (and not even part of the `./frontend` folder). Most of the actually test Rails view, but there are a few exceptions, such as the tests in `./spec/features/work_packages/details` which test a good deal of features related to the Work Package Details pane.
The heavy lifting is done via these Testsuites, which are tightly integrated with the Rails stack (and not even part of the `./frontend` folder). Most of them actually test Rails views, but there are a few exceptions: The specs in `./spec/features/work_packages/details` test a good deal of features related to the Work Package Details pane.
## A note on plugins & commands used
@@ -154,6 +157,4 @@ $ pwd
$ rake test:units TEST=../openproject-plugin/test
```
These older legacy tests have been migrated for version `4.1`, but can still popup in some older plugins, or even an old version of OpenProject. the legacy tests have been converted by @myabc via gem and are located (for newer versions) here: `./spec/legacy/`. These should be removed in the future an be replaced by either proper specs or even complete features.
These older legacy tests have been migrated for version `4.1`, but can still popup in some older plugins, or even an old version of OpenProject. the legacy tests have been converted by `@myabc` via gem and are located (for newer versions) here: `./spec/legacy/`. These should be removed in the future an be replaced by either proper specs or even complete features.