examples/rcptt.extensions.ecl/README.org

*** Custom commands overview
This repository is a complete example on how to create a custom [[http://git.eclipse.org/c/rcptt/org.eclipse.rcptt.git/tree/ecl][ECL]] command and use it in [[https://www.eclipse.org/rcptt/][RCPTT]].


The challenge with custom ECL commands is that they should be executed inside an application under test, therefore they have to be installed into it. However making a custom build for tests or including these extra plug-ins and dependencies into a final product is not desired. As a solution, RCPTT has mechanism to automatically include extra dependencies into an application-under-test -- in RCPTT IDE this can be done by wrapping an update site into a special plug-in, which can be installed into RCPTT IDE itself.

This example shows a sample Maven build, which allows to build a runtime update site for RCPTT IDE in a single Tycho build, and can be used as a starting point for creating custom application-specific commands.

As an example, we create a custom ECL command *get-problem-messages* which returns all error messages from Problems view (more precisely, it searches for all resource markers with type 'problemmarker' and gets and error messages from them).

Combined with other ECL commands, this command can be used to assert that there are no errors in Problems view, like this:

#+BEGIN_SRC none
get-problem-messages | length | eq 0 | assert-true "There are build problems"
#+END_SRC

Or it can be used to assert that a Problems view contains a certain message:
#+BEGIN_SRC none
// here we use 'foreach' as a filter --
// it returns only those elements, which match
// to a condition inside an 'if' statement
get-problem-messages | foreach [val msg] {
	if [$msg | invoke contains "Foo cannot be resolved to a type"] {
		$msg
	}
} | length | gt 0 | assert-true "Expected problem not found"
#+END_SRC

*** Structure

A custom command is split into two plug-ins:
- *org.eclipse.rcptt.extensions.ecl.model*, which holds a EMF model for a command
- *org.eclipse.rcptt.extensions.ecl.impl*, which contains a Java implementation for a command

This separation is not strictly required, but very convenient -- in case of a custom application-specific ECL command only an implementation plugin has a dependency on an application plug-ins, so model plug-in can be added to RCPTT IDE in order to provide completion and documentation.

A repository is structured as following:
- *common*
  - plug-in with a command model
  - feature, which consists of this plug-in only
- *runtime*
  - plug-in with a command implementation
  - feature, which includes implementation plug-in and a common feature
  - repository, which provides runtime feature
- *ide*
  - plug-in, which holds a binary runtime repository (it is automatically copied inside a plug-in during maven build)
  - feature, which includes ide plug-in and a common feature
  - repository, which provides IDE feature
- *tests* contains sample RCPTT tests

*** Usage
    Use =mvn clean install -Dtycho.localArtifacts=ignore= in repository root to build Runtime and IDE update sites. After that IDE update site can be installed into RCPTT from =ide/repository/org.eclipse.rcptt.extensions.ide.site/target/repository=. Note that for optimization purposes RCPTT IDE does not check for new injections for existing AUTs, so it is required to remove and add back an AUT in RCPTT after installing/updating RCPTT IDE extensions.

    Use =mvn clean install= in =tests/rcptt.extensions.ecl= folder to run sample test cases using custom command.