Scenarioo Development Environment with IntelliJ

This readme contains important developer information for developers on how to develop the open source project Scenarioo with IntelliJ.

This is the recommended setup, to get up started and productive most quickly!

Prerequisites

  • Java JDK 1.8
  • Take care to still set the language level to 1.6 in IntelliJ, because currently we still try to be backward compatible, for some projects that can not yet use Java 1.7 or 1.8 on their tomcat servers (for scenarioo 3.0 we will break that and can update to 1.8)
  • Tomcat 7 needs to be installed: http://tomcat.apache.org
    • you can also try Tomcat 8, which should also work, but might not yet be tested for this setup here

Setup and Use of GIT

  • Install GIT

  • Keep in mind to always commit with Unix style line endings, also if you are working on Windows (make sure to configure GIT accordingly, if not yet!).

  • Make sure that you personalize your GIT by setting your username and email for commits (!! important !!):

       $ git config --global user.name "John Doe"             
   $ git config --global user.email johndoe@example.com

    IMPORTANT - Set correct email: Make sure to configure the same email of your github account, otherwise your commits will not be recognized as contributions by you on github! See also here: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup

  • For most things you will work with the IntelliJ GIT client or use the GIT command line

  • Please refer to our branching strategy about how we use branches and create releases.

  • (optional) you can use whatever other GIT tools you need

    • for working with github, github desktop might be helpful: https://desktop.github.com/
    • on the linux developer VM we had once following additional tools installed (probably not needed when working with IntelliJ):
      • gitk : Very rich functionality
      • git gui : gui to stage, stash, commit and push your changes
      • gitg : Simple git interface (very nice git history tree)
      • giggle : more of a git viewer to review changes in the files graphically

Install NodeJS and NodeJS development tools

  • NodeJS: http://nodejs.org/download (newest version should be okay: higher than 6.2 !) Use the latest versions of nodejs / npm / bower and you should be fine. If you discover that something does not work with the latest version and you have to fix it, please inform the community about it so that they have a chance to upgrade their tools.

  • Install nodejs dev tools globaly (might not be needed anymore, but is useful for working on command line): npm install -g gulp bower phantomjs protractor

Get the Sources

You need to clone at least the following repositories:

There are more interesting repositories with more examples and other writer libraries available under https://github.com/scenarioo

But this two repositories should be sufficient for most usual developers.

Setup projects in IntelliJ

  • Install IntelliJ IDEA Ultimate

    • newest version
    • License: either use one of our scenarioo open source licenses or even better get yourself a commercial personal license (especially if you also need it for commercial work!)

  • Install IntelliJ Plugins (this list is not yet consolidated):

    • Gradle (probably allready included, but not sure)
    • NodeJs (if not allready included ?? not sure about that)
    • .gitignore plugin
    • Karma plugin (IntelliJ recommends this!)
    • Markdown Plugins:
      • Make sure to only use "Markdown support" by Jetbrains (it is now the best and should be part of IntelliJ)
      • disbale any other "Markdown"-Plugins (if you have, otherwise you might not be able to see and use the nice preview that comes with "Markdown support")
      • Make sure to use the new nice "JavaFX"-preview for markdown under Settings/Markdown/Preview (you will like that!)
      • after changing those plugins settings you might have to restart IntelliJ to let the changes take effect.
      • if you open a markdown file you should see a blue MD icon in the file's editor tab, and be able to choose a side-by-side View wirh Preview that looks nicely (in editor's toolbar).

  • Import scenarioo web app by using "New project from existing sources":

    • choose 'scenarioo' folder
    • Import "From external model: Gradle" and use the gradle wrapper (default settings)

  • By using "File/New module" you can add additional repositories to be part of the same project setup in one IntelliJ window:

    • Import 'scenarioo-java' by using "New module from existing sources":
    • choose 'scenarioo-java' folder
    • Import "from external model: Gradle" and use the gradle wrapper (default settings)

  • From "Gradle"-tab in intelliJ simply run the following gradle tasks, to build everything cleanly:

    • scenarioo-java: clean build test install
    • scenarioo: clean build test
      • take care to configure JVM 1.7 as runtime JVM for gradle, otherwise I got errors somehow when running this (Tab "Gradle">Button "Gradle Settings">Gradle JVM).
      • And if you get some python errors in npm install part on windows, you can probably ignore this optional npm dependency problems and just try to run it once again

  • Configure a run configuration to run the installed Tomcat 7 from IntelliJ

    • set the tomcat path to tomcat 7 installation
    • set it running on port 8080
    • on "Deployment" tab:
      • choose to deploy the artifact "gradle....scenarioo-server...war" (not exploded) on startup
      • Application context (!important!): /scenarioo
    • on "Startup/Connection" tab: set environment variable "SCENARIOO_DATA" to following path: <your-project-source-path>\scenarioo\scenarioo-docu-generation-example\build\scenarioDocuExample

  • Run all tests of the sub-project "scenarioodocu-generation-example" (right click on folder and choose "Run 'All Tests'") to generate example documentation data in Folder build/scenarioDocuExample

===== TODO issue #427 === 

 * when the issue #427 has been resolved, the following is obsolete: 

 ==== obsolete after #427 has been merged ====


    * Start the server using the run configuration, you should see something like following in the server log on first startup:

        WARN  org.scenarioo.dao.configuration.ConfigurationDaoImpl: no configuration directory is configured in server context, therefore trying to use fallback directory in user home.
        WARN  org.scenarioo.dao.configuration.ConfigurationDaoImpl:   file C:\Users\rbr\.scenarioo\config.xml does not exist --> loading default config.xml from classpath

    * Copy the file `scenarioo-server\src\main\resources\config-for-demo\config.xml` to the location where your server tries to load the configuration by default from (see server output).
                [TODO: this will change with the new directory configuration by @mi-we soon anyway, see issue # )
            * change the configured documentation path configured inside this copied file to point to the following location instead:
                * &lt;your-project-source-path&gt;\scenarioo\scenarioo-docu-generation-example\build\scenarioDocuExample

    * Stop the server again            

==== end of obsolete part after #427 has been merged ===

* then we have to test, that the above allready mentioned configuration of the variable "SCENARIOO_DATA" in tomcat run configuration works as expected.

=== end of TODO for issue #427 ===

  • Start the tomcat server by using the run configuration: you should see in the log output that it is importing the example documentation data properly.

  • To start the web server for serving the Angular JS frontend (scenarioo-client) proceed as following (or as described in the Developer Guide, see below):

    cd scenarioo-client
npm install
bower install
gulp serve
# then open the browser to browse the application 
# on given URL, usually http://localhost:9000
# if you change files in the client the browser will refresh automatically

Developer Guide

For more informations on how to develop, build and test scenarioo properly, please read the following carefully:

Developer Guide

Testing the setup

What has been tested and works with this setup

[x] build and install scenarioo-java library (using gradle) [x] debugging the server (yes, check!) [x] run karma tests [x] gulp serve [x] run e2e-tests (runs very fast and very stable!) [x] develop ScenariooJS library [x] build ScenariooJS library [x] test ScenariooJS library (including e2e test example)

Not yet tested

  • change something in the writer library and link to it in server during development
  • release new writer library
  • release new web app (should work, when JVM is set to 1.7 for gradle)
  • release scenariooJS Library

Known Issues

General Issues

  • There seems to be an issue, when not using JVM 1.7 for gradle. But when this is currently configured to 1,7, it works well :-) Has been documented above accordingly.

Only on Windows

  • For updating the local webdriver you have to use the gulp task in client:
    • use gulp webdriver_update
    • then also "gulp test-e2e` should work now (without need to install protractor globaly anymore)

Open points - To be considered / improved / solved

from old setup to be integrated in this development setup instructions here

  • check your JavaScript code against our .eslintrc file!
  • See also WebStorm IDE Settings.
  • All developers have to use same formatting and other java settings in eclipse, as explained here

should be improved

  • automation (skript or run config) to reset config before running e2e tests.
  • in general some run configs, maybe also some templates etc. that we can share for working more fast in IntelliJ.

results matching ""

    No results matching ""