Merge branch 'master' of https://github.com/nokia/RED

First_steps.md

@@ -0,0 +1,11 @@
+## First steps with RED Robot Editor
+
+Following documents are intended for first time users of RED, especially not familiar with working with Eclipse based tools.
+
+*   [Download&install](doc/download_install.md) - step by step instructions how to prepare your environment to work with RED Robot Editor
+*   [Eclipse principles](doc/eclipse_princiles.md) - overview of main Eclipse principles
+*   [Create&run first testcase](doc/create_run.md) - how to create first project and testcase,execute it
+*   [Debug perspective](doc/debug.md) - short introduction to Debug options
+*   [Preferences & red.xml](doc/preferences_misc.md) - how to manage multiple python instances, include external libraries to RED
+
+

LICENSE

@@ -0,0 +1,13 @@
+Copyright 2016 Nokia Solutions and Networks
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,46 @@
+# RED - Robot Editor
+## General information 
+
+RED is modern editor based on Java IDEs (Eclipse, IntelliJ in future) to allow quick and comfortable work with Robot testware.
+
+**Latest release - RED 0.6.5 (2016-07-07): https://github.com/nokia/RED/releases/latest**
+
+## What RED provides:
+* text editor with validation and code colouring
+* table editors like in Ride (currently read-only)
+* debug&remote debug with:
+	* breakpoints
+	* testcase stepping (step into, step over)
+	* runtime variable lookup & modification
+* code assistance & completion for variables, keywords, testcases, resources and libraries
+* real time testcase validation
+* execution view
+* support for plugins via Eclipse mechanisms
+
+## Binaries distribution:
+RED is distributed as independent binary (Eclipse product) and Eclipse feature to be installed on existing Eclipse binary. 
+
+###Install form Marketplace/Update Site
+
+Marketpalce: Click Help -> Eclipse Marketplace -> and type into Find field "RED"
+
+Update Site: Click Help -> Install New Software -> Add and set address in Location to:
+http://master.dl.sourceforge.net/project/red-robot-editor/repository
+
+### Update existing RED installation
+We recommend to not to do direct update of newer version, instead perform unistall old RED and install new RED after Eclipse restart.
+Open Help -> Installation Details, select old RED feature and perform unistall, restart Eclipse
+
+## RED Help
+![RED Robot Editor's application help](https://github.com/nokia/RED/tree/master/red_help)
+## Look & feel
+![](https://github.com/nokia/RED/blob/master/doc/img/red_overview_source_1.png "Robot perspective with text editor")
+
+![](https://github.com/nokia/RED/blob/master/doc/img/red_testcases_table.png "Table editor")
+
+![](https://github.com/nokia/RED/blob/master/doc/img/red_overview_debug.png "Debug perspective")
+
+
+
+
+

changelog.txt

@@ -0,0 +1,36 @@
+RED 0.6.5 - 2016/07/07
+
+Bug
+	#21 - Editor do not open when separator is pipe and for-item text after \ is like ${a} s
+	#23 - RED run of of memory during debugging StackOverflowException happens 
+	#29 - Missing suite file for execution during debug caused by __init__.py file 
+    Not refreshing decorator for Exclude/Include options
+    Removing by right click entries from red.xml (variable files, referenced libs) does not work under mint
+    NP when path in Library is windows on Linux machine
+    Jython server process do not close own subprocesses
+    Cannot debug Suite Setup inside __init__ file on RF ver > 3.0
+    Error after deleting project with Libs
+    Referenced libs are not generated after removing second project
+    adding ${} in path to lib produces annoying popup
+    Editor do not open when separator is pipe and for-item text after `\` is like `${a} s`
+    RED run of of memory during debugging StackOverflowException happens often
+	Elements order in navigator is different than in outline view
+
+Enhancement
+	It should be possible to add/remove RED project nature without editing project file
+    Use eclipse refactoring API to reflect project changes in excluded paths
+    Provide initial infrastructure for Search feature
+    Create Join View for Setting section multiple declaration elements
+    Common documentation controller
+    Common comment controller
+    Create variable operation helper inside RED core
+	PREFERENCES - cell selection can stay in same cell after commiting editor
+
+Feature
+    Variable view on Nebula - sync with model
+    Settings table on Nebula
+
+Task
+    Dumper for testcases & keywords
+    Merge Nebula from branch to trunk
+

doc/create_run.md

@@ -0,0 +1,76 @@
+## Create Project, add test,run
+
+In order to start working with RED & Eclipse, you need to set up couple of things first. 
+
+### Robot Perspective
+
+All RED activities are performed within 2 perspectives: _Robot_ , _Debug_ . Former one is used to construct and execute tests, later one is for debugging test-cases. To start working with RED, you should activate Robot perspective first.
+
+*   Check if you have already set Robot perspective:
+
+    ![](img/create_run/perspective_1.png)
+*   Set perspective to Robot by issuing action: _Window -> Open Perspective -> Other ... -> Robot_
+
+### Workspace & project
+
+**Workspace** stores all global Eclipse & Red preferences, if not set previously (first run or workspace path is non valid) Eclipse will show dialog to set path.
+User can always switch workspaces, and if necessary, perform projects import from locations outside of current workspace.
+Switching Workspace is done by menu action: _File -> Switch Workspace ..._
+
+**Project** is an equivalent to folder in OS, it stores files and settings relevant to a group of files. In order to work with RED, **Robot Project** has to be created.
+Create new Project can be done by:
+
+*   _File->New-> Robot Project_ (item can be found under selection _New -> Project .. -> Robot Framework -> Robot Project_ )
+*   Right click menu on Project Explorer with selection as above
+
+If you wish to import anything into Workspace ( already existing Project) or into Project (existing testcases), menu _Import ..._ will open up wizard.
+Upon creating Project, you should see similar structure in Project Explorer tree as below which will also indicate that RobotFramework is visible to Eclipse
+
+![](img/create_run/simple_project_1.png)
+
+### Create TestSuite
+
+To create sample test you should invoke action: _File -> New -> Other ... -> Robot Framework -> Robot Test Suite_. Same action can be accessed by right click menu. RED consists of 2 different modes of editing, a Table (Ride-like style) and Text style.
+By default Table editor is used when TestCase file is opened.
+
+![](img/create_run/editors_1.png)
+
+Additionally, Source tab shows text representation of TestSuite:
+
+![](img/create_run/editors_2.png)
+
+#### Content assistant
+
+Just like other modern Developments Environments, RED supports content assistance/code completion.
+When editing tab or item in text editor, press CTRL+SPACE keys to activate hints for Keywords.
+
+### Running TestSuite
+
+To run TestSuite, _Run_ button needs to be selected or right-click menu on file can be issued.
+
+![](img/create_run/toolbar-1.png)
+
+#### Limiting test cases to be run
+
+To limit list of test cases to be run, open _Run Configurations ..._,
+
+![](img/create_run/run_1.png)
+in Robot part you can specify which test cases should be run by using either tags or include/exclude list of test cases in active project.
+
+![](img/create_run/run_configurations.png)
+
+#### Console and message log
+
+During TestSuite execution, RED displays RobotFramework console and message logs.
+Those information are available by view Console and Message Log, by default visible in the Robot perspective or by _Window -> Show View -> Other.... -> Robot_
+
+![](img/create_run/console_1.png)
+If any of those 2 views are missing, best way is to reset perspective settings by using action _Window -> Reset Perspective ..._
+
+#### Execution status
+
+RED can show execution status of TestCases along with outcome result and execution time.
+
+![](img/create_run/exec_1.png)
+Execution View is not in default Robot perspective thus it needs to be manually added.
+Visit _Window-> Show View -> Robot -> Execution View_

doc/debug.md

@@ -0,0 +1,75 @@
+## Debug
+
+Debug functionality is unique way of checking what is happening during TestCase and TestSuite execution.It works similiary as debug functionality in most of programming languages - it allows track execution of program for checking unwanted behaviour either on TestCase side or in tested software.
+
+It is important to note that Debug functionality works only with text editor (debug actions can be set only there) therefore it is crucial to active it before switching to Debug perspective.
+Try to not make changes in script in Debug mode as Eclipse have a problem with following changes respectful to Breakpoints.
+
+### Basics
+
+In order to work with Debug, save the file beforehand. If you made any changes in Table editors, close and reopen file so changes will be visible in Source tab (this will be non issue in close future). Activate Source view and change to Debug perspective:
+
+![](img/debug/debug_1.png)
+
+Debug perspective looks as follows:
+
+![](img/debug/debug_2.png)
+
+First thing with working with Debug is to place at least one breakpoint. This allows RED to pause Debug execution and activate Stepping options.
+To place breakpoint in Source view click on line in script and under right click menu choose Add breakpoint. You can also add breakpoint directly by clicking on line number in Source editor view.
+When successful, blue ball icon will appear next to it, new breakpoint entry will be visible in Breakpoint lists.
+
+#### Start Debug
+
+To execute Debug, click on "green bug" icon at the top toolbar.
+
+![](img/debug/debug_3.png)
+
+#### Limiting TestCases to be debugged
+
+Limit works just like TestCase limitation in Robot perspective.
+In order to limit which TC will be executed in Debug, open _Debug Configurations..._ from Debug button:
+
+![](img/debug/debug_4.png)
+
+### Working with Debug
+
+#### Breakpoints and execution stepping
+
+Breakpoints are essential item, each pause execution and allows to initiate Debug actions.
+When breakpoint line is activated during execution, following icons are active:
+
+![](img/debug/debug_5.png)
+
+moving from left to right:
+
+*   Blue circle - Skip All Breakpoints - allow to continue testcase execution onwards without stopping on defined breakpoints
+*   Green Play - Resume - resumes test execution
+*   Pause
+*   Stop
+*   Disconnect
+*   Step Into - F5 key - each F5 key press will execute active line and move to next one. If active line consists Keyword or embedded TestCase, test executor will jump into item and execute it line by line. To exit from executing inherited items use Step Return - key F7
+*   Step Over - F6 key- each F6 key press will execute active line and move to next one. If keyword exists in current line, keyword result will be returned without going into Keyword content
+*   Step Return - F7 key - allows to return to main TestCase execution from embedded TestCase or Keyword if Step Into was used before
+
+List of breakpoints can be seen in upper right side of the Debug perspective.
+
+![](img/debug/break_1.png)
+
+*   each breakpoint can be enabled/disabled
+*   each breakpoint can be removed
+*   for each breakpoint, action condition can be set
+
+*   Hit count: breakpoint pause execution only after selected number of previous hits. Useful to activate breakpoint inside a loop statement on certain iteration
+*   Conditional: expression when pass will activate breakpoint. Expression should be in RobotFramework syntax, for instance: Should be Equal ${variable} 10
+
+#### Variables watch
+
+Variables can be watched and changed during TestCase Debug. All actions related to variables are accessible in Variables window which is shared with Breakpoints list.
+Variables are only showed during TestCase execution.
+
+![](img/debug/var_1.png)
+
+At the top of the list, TestCase variables are displayed followed by RF & environmental variables.
+Each variable can be changed during test run during breakpoint event.
+When variable is changed, it is indicated by distinct colour in the list.

doc/download_install.md

@@ -0,0 +1,48 @@
+## Download&install;
+
+### Get Java
+
+RED is compatible with any Oracle Java newer than 1.7 . Java official website:
+[www.java.com](https://www.java.com)
+
+### Get Eclipse
+
+Currently RED is tested with Eclipse Luna ( v4.4.x ) release although RED is
+compatible with Eclipse Luna,Mars and Neon.  
+Official Eclipse website: [ Eclipse.org](https://www.eclipse.org/)
+
+### Get RED
+
+RED feature can be downloaded from
+[github.com/nokia/RED](https://github.com/nokia/RED) RED feature is a file
+with zip extension. RED Product is RED bounded with Eclipse platform.
+
+### Get Python & RobotFramework
+
+In order to use full spectrum of RED features, Python & RobotFramework should
+be installed with respectful dependencies (currently Python 2.7.x is supported
+by RobotFramework).  
+Python official site: [www.python.org](http://www.python.org)  
+RobotFramework official site: [robotframework.org](http://robotframework.org/)  
+We recommend to install Python packages using pip  
+**Note: in some cases like using portable Python&RF;, there may be a need to run Eclipse and pybot with administrative privileges**  
+
+### Install RED into Eclipse
+
+#### Install from Eclipse Marketplace
+
+Start Eclipse, open Help -> Eclipse Marketplace Search for "RED Robot Editor"
+Install preferred version accepting license Restart Eclipse to apply changes
+
+#### Install from zip file
+
+Start Eclipse, accept default Workspace folder placement  
+Open _Help -> Install New Software_  
+Click _Add -> Archive_ and select RED zip feature (eg.
+org.robotframework.ide.eclipse.feature_1.0.0.201507130728.zip )  
+Tick all boxes in Robot Framework IDE Category and apply Next  
+Accept all prompts and user licences, proceed with installation process  
+Restart Eclipse as prompted  
+Verify RED installation by opening _Help -> Installation Details_ to check if
+RED is visible on installed features list  
+

doc/eclipse_princiles.md

@@ -0,0 +1,35 @@
+## Eclipse principles
+
+### Eclipse platform overview
+
+The Eclipse platform itself is structured as subsystems which are implemented in one or more plug-ins. The subsystems are built on top of a small runtime engine. The figure below depicts a simplified view.
+
+![](img/eclipse_principles/arch-npi.jpg)
+
+#### Workbench
+
+The term Workbench refers to the desktop development environment. The Workbench aims to achieve seamless tool integration and controlled openness by providing a common paradigm for the creation, management, and navigation of workspace resources.
+
+Each Workbench window contains one or more perspectives. Perspectives contain views and editors and control what appears in certain menus and tool bars. More than one Workbench window can exist on the desktop at any given time.
+
+### Perspective & View
+
+Each Workbench window contains one or more perspectives. A perspective defines the initial set and layout of views in the Workbench window. Within the window, each perspective shares the same set of editors. Each perspective provides a set of functionality aimed at accomplishing a specific type of task or works with specific types of resources. For example, the Java perspective combines views that you would commonly use while editing Java source files, while the Debug perspective contains the views that you would use while debugging Java programs. As you work in the Workbench, you will probably switch perspectives frequently.
+
+Perspectives control what appears in certain menus and toolbars. They define visible action sets, which you can change to customize a perspective. You can save a perspective that you build in this manner, making your own custom perspective that you can open again later.
+
+Views support editors and provide alternative presentations as well as ways to navigate the information in your Workbench. For example, the Project Explorer and other navigation views display projects and other resources that you are working with. Views also have their own menus. To open the menu for a view, click the icon at the left end of the view's title bar. Some views also have their own toolbars. The actions represented by buttons on view toolbars only affect the items within that view. A view might appear by itself, or stacked with other views in a tabbed notebook. You can change the layout of a perspective by opening and closing views and by docking them in different positions in the Workbench window.
+
+![](img/eclipse_principles/main_view.png)
+
+### Workspace & Project
+
+The central hub for user's data files is called a workspace.
+
+The workspace contains a collection of resources. From the user's perspective, there are three different types of resources: projects, folders, and files. A project is a collection of any number of files and folders. It is a container for organizing other resources that relate to a specific area. Files and folders are just like files and directories in the file system. A folder contains other folders or files. A file contains an arbitrary sequence of bytes. Its content is not interpreted by the platform.
+
+A workspace's resources are organized into a tree structure, with projects at the top, and folders and files underneath. A special resource, the workspace root resource, serves as the root of the resource tree. The workspace root is created internally when a workspace is created and exists as long as the workspace exists.
+
+A workspace can have any number of projects, each of which can be stored in a different location in some file system.
+
+The workspace resource namespace is always case-sensitive and case-preserving. Thus the workspace allows multiple sibling resources to exist with names that differ only in case. The workspace also doesn't put any restrictions on valid characters in resource names, the length of resource names, or the size of resources on disk. Of course, if you store resources in a file system that is not case-sensitive, or that does have restrictions on resource names, then those restrictions will show through when you actually try to create and modify resources.