Home

Welcome to the PackageFactory.Guevara wiki! This page hosts developer documentation and conventions.

Getting Started

Please follow the instructions in the README for getting started! This documentation is mainly for developers of this package.

Overall folder structure

The JS frontend of this code resides in Resources/Private/JavaScript.

As this package uses a Guest iFrame for rendering the actual website, we have two JS contexts which communicate with each other. The "outer frame" which contains the Neos UI is called host, while the iFrame containing the website is called the guest.

This structure is reflected in the sub-folder/package structure:

• Host: the main application of Neos.
  • This is the React.JS/Redux application.
• Guest: the connector running inside the guest frame.
• API: the draft for the soon to be separated Neos JS API which handles the communication with the server instance.
  • The API is bootstrapped in the root of the Host application, since it relies on the csrfToken of the logged in user.
• Login: The login screen. Currently not used.
• Shared: helper functions which are necessary both inside the guest and the host.
  • Should not contain state!
  • We try to get rid of these functions!

TODO: explain how the guest and the host frame communicate.

Our Style of Writing React.js

TODO

• React Style
  • stateless functional components
• especially plow.js
  • currently Immutable.js not included; but important in the longer run.
• Redux-Saga (how it is used)

Testing

Writing unit tests

The unit tests are executed with Karma and PhantomJS. Instead of relying on the default settings of Karma, we use chai as our assertion library and sinon for spies. To run the unit tests, execute npm run karma in your shell.

Adding unit tests is fairly simple, just create a file on the same tree level as your changed/new feature, named [filename].spec.js and karma will execute all tests found within the spec file, other than that, just orient yourself on the existing tests.

Use it.only(() => {}) and describe.only(() => {}) if you want to run a specific test and not the whole test suite.

Writing integration/acceptance tests

The tests are running on a selenium grid which is installed & started by the npm run selenium:init command, and executed by codecept which runs WebdriverIO in the background.

Like CucumberJS the test framework uses scenarios and steps. Unlike CucumberJS, common steps are predefined.

Run tests

To run the acceptance tests, execute npm run selenium:init first, and npm run selenium:run in a separate session afterwards.

Adding user stories is as simple as creating unit tests, the only difference is that the file needs to be placed in the Tests/TestCodeceptIo root directory and should end with *.story.js instead of *.spec.js.

Filter tests / run specific test

Since acceptance testing can be relatively time-intensive, it’s important to plan how to organize your tests.

npm run selenium:run -- -f "should be able to type into a nodeType in the guest frame"  

Describe Scenarios and Steps

Tests are written in Javascript DSL instead of Gherkin.

Feature('CodeceptJS Demonstration');

Scenario('submit form successfully', (I) =>
  I.amOnPage('/documentation')
  I.fillField('Email', '[email protected]')
  I.fillField('Password', '123456')
  I.checkOption('Active')
  I.checkOption('Male');
  I.click('Create User')
  I.see('User is valid')
  I.dontSeeInCurrentUrl('/documentation')
});

Neos specific step definitions

We provide some neos specific step helpers which help us testing our interface.

I.focusAndEditInGuestFrame(): Focus the guest frame and edit the first text element.

I.focusAndEditInGuestFrame('Hello Worlds');

I.seeElementInViewport(<Class/ID/Xpath>): Check if element is visible in the current viewport.

I.dontSeeElementInViewport('#neos__topBar__publishDropDown__contents');

I.dontSeeElementInViewport(<Class/ID/Xpath>):

Opposite of seeElementInViewport.

Redux State Structure

TODO

Functional Programming Basics

TODO

Glossary

• Node
• StoredNode
• StoredNodeType / NodeType