N4JS Design Specification

keep memory consumption of the test class generator low

mvn clean verify
    @BenchmarkOptions(benchmarkRounds = 5, warmupRounds = 2)
    @Test
    public void test() throws Exception {
        //test...
    }
@BenchmarkMethodChart(filePrefix = "benchmark-method")
@BenchmarkHistoryChart(filePrefix = "benchmark-history", labelWith = LabelType.CUSTOM_KEY)
public class PerformanceTest extends AbstractGeneratingPerformanceTest {

    public PerformanceTest() {
        super("PerfTest");
    }

    @Rule
    public TestRule benchmarkRun = new BenchmarkRule();

    @Test
    @BenchmarkOptions(benchmarkRounds = 5, warmupRounds = 2)
    public void Test1() throws Exception {

        //Test...
    }

    @Test
    @BenchmarkOptions(benchmarkRounds = 5, warmupRounds = 2)
    public void Test2() throws Exception {

        //Test...
    }
}
-Xms512m -Xmx1024m -XX:MaxPermSize=512m $-$Djub.consumers=CONSOLE,H2 $-$Djub.db.file=.benchmarks $-$Djub.customkey=${current_date}
@RunWith(XtextParameterizedRunner.class)
@InjectWith(N4JSInjectorProvider.class)
public class DataDrivenParserTestSuite {

    /**
     * Zip archives containing test files.
     */
    public static final Collection<String> TEST_DATA_RESOURCES = Arrays.asList("foo.zip", "bar.zip");

    /**
     * Blacklist of files requiring an execution engine.
     */
    public static final String BLACKLIST_FILENAME = "blacklist.txt";

    /**
     * Every generated test will use different ZipEntry as test data
     */
    final ZipEntry entry;

    /**
     * Name of resource containing corresponding ZipEntry
     */
    final String resourceName;

    @Inject
    protected ParseHelper<Script> parserN4JS;

    Collection<String> blackList;

    static final Logger logger = Logger.getLogger("someLogger");

    public CopyOfLibraryParsingTestSuite(ZipEntry entry, String resourceName, Collection<String> blackList) {
        this.entry = entry;
        this.resourceName = resourceName;
        this.blackList = blackList;
    }

    @Rule
    public TestRule blackListHandler = new TestRule() {
        @Override
        public Statement apply(final Statement base, Description description) {
            final String entryName = entry.getName();
            if (blackList.contains(entryName)) {
                return new Statement() {
                    @Override
                    public void evaluate() throws Throwable {
                        try {
                            base.evaluate();
                        } catch (AssertionError e) {
                            // expected
                            return;
                        }
                    }
                };
            } else {
                return base;
            }
        }
    };

    /**
     * Generates collection of ZipEntry instances that will be used as data
     * provided parameter is mapped to name of the test (takes advantage of fact
     * that ZipEntry.toString() is the same as entry.getName())
     *
     * @return
     * @throws URISyntaxException
     * @throws ZipException
     * @throws IOException
     */
    @Parameters(name = "{0}")
    public static Collection<Object[]> data() throws URISyntaxException, ZipException, IOException {
        return TestCodeProvider.getDataFromZippedRoots(TEST_DATA_RESOURCES, BLACKLIST_FILENAME);
    }

    /**
     * generated instances of the tests will use this base implementation
     *
     * @throws Exception
     */
    @Test
    public void test() throws Exception {
        assertNotNull(this.entry);
        assertNotNull(this.resourceName);
        assertNotNull(this.parserN4JS);

        //actual test code

    }
}
// XPECT ! errors --> '~$message$~' at "~$location$~"
/* XPECT_SETUP org.eclipse.n4js.spec.tests.N4JSSpecTest END_SETUP */
<extension point="org.xpect.testSuite">
    <testSuite class="org.eclipse.n4js.spec.tests.N4JSSpecTest" fileExtension="n4js" />
</extension>
/* XPECT_SETUP org.eclipse.n4js.tests.N4JSXpectTest

IssueConfiguration {
    IssueCode "AST_LOCAL_VAR_UNUSED" {enabled=true}
}

END_SETUP
*/
// XPECT errors --> '~$message$~' at "~$location$~"
/* XPECT errors ---
'~$message_1$~' at "~$location_1$~"
~$\dots$~
'~$message_n$~' at "~$location_n$~"
--- */
// XPECT warnings --> '~$Message$~' at "~$Location$~"
/* XPECT warnings ---
'~$message_1$~' at "~$location_1$~"
~$\dots$~
'~$message_n$~' at "~$location_n$~"
--- */
// XPECT noerrors --> '~$messageOrComment$~' at "~$location$~"
/* XPECT noerrors ---
'~$messageOrComment_1$~' at "~$location_1$~"
~$\dots$~
'~$messageOrComment_n$~' at "~$location_n$~"
--- */
function foo(any o): number {
    if (o instanceof string) {
        // XPECT noerrors --> "effect systems knows that o is a string" at "o"
        return o.length;
    }
    return 0;
}
function foo(any o): number {
    if (o instanceof string) {
        // here should be no error:
        return o.length;
    }
    return 0;
}
// XPECT scope at $location$ --> ~$[$~!~$]$~~$name_1$~, ~$\dots$~, ~$[$~!~$]$~~$name_n$~ ~$[$ ~, ...~$]$~
/* XPECT scope $location$ ---
~$[$~!~$]$~~$name_1$~, ~$\dots$~,
~$[$~!~$]$~~$name_n$~~$[$ ~, ...~$]$~
--- */
// XPECT scope at 'this.|$data_property_b' --> a, b, $data_property_b, !newB, ...
return this.$data_property_b + "_getter";
// XPECT scopeWithPosition at $location$ --> ~$[$~!~$]$~~$name_1$~ - ~$pos_1$~, ~$\dots$~, ~$[$~!~$]$~~$name_n$~ - ~$pos_n$~ ~$[$ ~, ...~$]$~
/* XPECT scopeWithPosition $location$ ---
~$[$~!~$]$~~$name_1$~ - ~$pos_1$~, ~$\dots$~,
~$[$~!~$]$~~$name_n$~ - ~$pos_n$~ ~$[$ ~, ...~$]$~
--- */
/* XPECT scopeWithPosition at foo2 ---
    b - 9,
    c - 25,
    foo - T3,
    foo2 - T9,
    ...
---*/
foo2()
//
//
// XPECT linkedPathname at '$location$' --> ~$pathname$~
// XPECT linkedPathname at 'foo()' --> C/foo
new C().foo();
// XPECT type of '$location$' --> ~$type$~
// XPECT type of 'x' --> string
var x = 'hello';
// XPECT type of 'foo()' --> union{A,number}
var any y = foo();
// XPECT expectedType at 'location' --&gt; Type
The location (at) is optional.
// XPECT elementKeyword at 'myFunction' -> function
interface I {
  fld: int;
  get g(): string;
  set s(p:string);
}

//XPECT elementKeyword at 'string' --> primitive
var v1: string;

//XPECT elementKeyword at 'I' --> interface
var i: I;

//XPECT elementKeyword at 'fld' --> field
i.fld;
// XPECT accessModifier at 'myFunction' -> function
// XPECT accessModifier -> function
// XPECT accessModifier --> publicInternal
export @Internal public abstract class MyClass2 {

// XPECT accessModifier --> project
abstract m1(): string;

// XPECT accessModifier at 'm2' --> project
m2(): string {
    return "";
  }
}
//
//
/* XPECT lint */
/* XPECT lintFails */
// XPECT FIXME  xpectmethod ... --> ...
// Perfectly right behaviour XPECT FIXME noerrors -->
console.log("fine example code with wrong error marker here.");
/* XPECT_SETUP org.eclipse.n4js.tests.N4JSNotValidatingXpectPluginUITest
    ...
    Config {
        content_assist_timeout = 1000
        ...
    }
    ...
*/
VarDef "objectProposals" {
    ...
}
/* XPECT_SETUP
VarDef "stringProposals" { MemberList  "String" "methods" "public" {}}
END_SETUP */
<$variable>
// XPECT contentAssistList at 'a.<|>methodA' proposals --> <$stringProposals>, methodA2
a.methodA
// XPECT contentAssistList at 'a.<|>methodA' apply 'methodA2' --> a.methodA2()<|>methodA
// XPECT contentAssistList at 'a.<|><[>methodA<]>' apply 'methodA2' override --> a.methodA2()<|>
a.methodA
/* XPECT SETUP
...
content_assist_timeout = 2000ms
...
END_SETUP */
// XPECT contentAssistList at 'a.<|>methodA' proposals --> <$stringProposals>, methodA2
a.methodA
// XPECT contentAssistList at 'a.<|>methodA' display 'methodA2' --> 'methodA2(): any - A'
a.methodA
// XPECT contentAssist at 'a.<|>methodA' apply 'methodA2' --> a.methodA2()methodA
// XPECT contentAssist at 'a.<|>methodA' apply 'methodA2' insert --> a.methodA2()methodA
// XPECT contentAssist at 'a.<|>methodA' apply 'methodA2' override --> a.methodA2()
a.methodA
// XPECT quickFix at 'a.<|>method' apply 'methodA2' --> a.methodA2();
a.methodTypo();
/* XPECT contentAssistList at 'a.me<|>thodA' apply 'methodA2' ---
<...>
import A from "a/b/c"
<...>
a.methodA2()<|>methodA
<...>
--- */
a.methodA
/* XPECT contentAssistList at 'a.me<|>thodA' apply 'methodA2' ---
 import B from "p/b"
+import A from "a/b/c"

 ...
 foo() {
|a.[me|thodA2()]
 }
 ...
--- */
a.methodA
/* XPECT quickFix at 'sameVendor.protected<|>Method()' apply 'Declare member as public, @Internal' resource='../../otherProject/src/other_file.n4js' ---
diff here
---
*/
/* XPECT_SETUP
content_assist_kind = 'recommenders'
END_SETUP */
// XPECT contentAssistList kind 'smart' at 'a.<|>methodA' display 'methodA2' --> 'methodA2(): any - A'
a.methodA
// XPECT quickFix at 'a.<|>method' apply 'methodA2' fileValid --> a.<|>methodA2();
a.methodTypo();
// XPECT quickFixAndRun at 'a.<|>method' apply 'methodHelloWorld' --> Hello World
a.methodTypo();
/* XPECT quickFixAndRun at 'a.<|>method' apply 'methodHelloWorld' ---
Hello World
--- */
a.methodTypo();
/* XPECT organizeImports ---
~Failure given by line-syntax starting with two characters:~
+ additional line
| line with inplace[removed part|added part]
+ removed line
  unchanged line
--- */
// XPECT warnings --> "The import of A is unused." at "A"
import A from "a/a1/A"
...
}
// XPECT organizeImports ambiguous '~Failure String of Exception~'-->
}
/* XPECT_SETUP org.eclipse.n4js.tests.N4JSXpectPluginUITest
   Workspace {
     Project "P1" {
        Folder "src" {
            Folder "a" {  Folder "a1" { File "A.n4js" { from="../../a/a1/A.n4js" } }
                            Folder "c"  { ThisFile {} }  }  }
        File "package.json" { from="package_p1.json" }  }  }
   END_SETUP
*/

/* XPECT organizeImports ---

 | import [A from "a/a1/A"|]
 | [import|] AR from "a/a1/A"
   export public role BRole with AR {
   }
--- */
// XPECT warnings --> "The import of A is unused." at "A"
import A from "a/a1/A"
import AR from "a/a1/A"

// XPECT noerrors --> "Couldn't resolve reference to Type 'AR'."
export public role BRole with AR {
}
@Test
def void testNoNPE_03() {
    val script = ``  '
        var target = {
            s: "hello",
            set x
    ``  '.parse
    analyser.analyse(script, "script", "script")
}
bot.menu("File").menu("New").menu("Project...").click();
sleep 5; metacity --replace --sm-disable &
Xvfb starting$ Xvfb :1 -screen 0 1024x768x24 -fbdir /var/lib/build/2014-09-05_10-36-343337290231975947044xvfb
[N4JS-IDE_Oliver] $ /bin/sh -xe /tmp/hudson4475531813520593700.sh
+ sleep 5
+ metacity --replace --sm-disable
Xlib:  extension "RANDR" missing on display ":1.0".
Window manager warning: 0 stored in GConf key /desktop/gnome/peripherals/mouse/cursor_size is out of range 1 to 128
Process leaked file descriptors. See http://wiki.jenkins-ci.org/display/JENKINS/Spawning+processes+from+build for more information
Parsing POMs
...
ssh -l viewer -L 5900:localhost:5900 build-linux-25 ’x11vnc -localhost -display :1

Cluster	A cluster is a set of projects, each project of a cluster may depend on another project of the cluster. There are no dependencies between projects of different clusters
Project	A project simply is a N4JS project, containing packages. A project may depend on other projects.
Package	A package is a folder in a source folder of a project. A package contains classes.
Class	A class is defined in a file, usually one class per file. The file, and with it the class, is contained in a package. The class contains members.
Member	A member is either a field or method of a class. A method may has a body, which may contain variables with references to other classes.

Definition	Single line: `// XPECT warnings --> '~$Message$~' at "~$Location$~"` Multi line: `/* XPECT warnings --- '~$message_1$~' at "~$location_1$~" ~$\dots$~ '~$message_n$~' at "~$location_n$~" --- */`
Description	Checks that one or more warnings are issued at given location and compares the actual messages at a given location with the expected messages specified in the test.

Provided by	`NoerrorsValidationTest`
Description	Checks that at the given location no error (or warning) is issued. This tests is roughly speaker the opposite of `errors`. The idea behind this test is to replace comments in the code, stating that an expression is assumed to be valid, with an explicit test. This is in particular useful when you start working on a task, in which there are (wrong) errors at a given position, or for bug report.
Example	`function foo(any o): number { if (o instanceof string) { // XPECT noerrors --> "effect systems knows that o is a string" at "o" return o.length; } return 0; }` is clearer and more explicit than `function foo(any o): number { if (o instanceof string) { // here should be no error: return o.length; } return 0; }` Also, the `noerrors` version will fail with a correct description, while the second one would fail with a general error and no location. Once the feature is implemented, regressions are detected much easier with the explicit version.

Provided by	`PositionAwareScopingXpectTest`
Description	Checks that the expected elements are actually found in the scope (or explicitly not found, when `!` is used). This is a modified version of the Xpect built-in scope test, ensuring that also elements only put into the scope when they are explicitly requested are found.
Example	`// XPECT scope at 'this.\|$data_property_b' --> a, b, $data_property_b, !newB, ... return this.$data_property_b + "_getter";`

Definition	Single line: `// XPECT scopeWithPosition at $location$ --> ~$[$~!~$]$~~$name_1$~ - ~$pos_1$~, ~$\dots$~, ~$[$~!~$]$~~$name_n$~ - ~$pos_n$~ ~$[$ ~, ...~$]$~` Multi line: `/* XPECT scopeWithPosition $location$ --- ~$[$~!~$]$~~$name_1$~ - ~$pos_1$~, ~$\dots$~, ~$[$~!~$]$~~$name_n$~ - ~$pos_n$~ ~$[$ ~, ...~$]$~ --- */`
Provided by	`PositionAwareScopingXpectTest`
Description	Checks that the expected elements are actually found in the scope (or explicitly not found, when `!` is used). The concrete syntax of the position, which is usually the line number, or the line number prefix with `T` if a type element is referenced, is described in `EObjectDescriptionToNameWithPositionMapper`.
Example	`/* XPECT scopeWithPosition at foo2 --- b - 9, c - 25, foo - T3, foo2 - T9, ... ---*/ foo2()`

Definition	Single line: `//` Multi line:
Provided by	`N4JSXpectTest`
Description	Compares scope including resource name but not line number.

Definition	Single line: `// XPECT linkedPathname at '$location$' --> ~$pathname$~`
Provided by	`LinkingXpectMethod`
Description	Checks that an identifier is linked to a given element identified by its path name. The path name is the qualified name in which the segments are separated by ’/’. This test does not use the qualified name provider, as the provider may return null for non-globally available elements. It rather computes the name again by using reflection, joining all `name` properties of the target and its containers.
Example	`// XPECT linkedPathname at 'foo()' --> C/foo new C().foo();`

Definition	Single line: `// XPECT type of '$location$' --> ~$type$~`
Provided by	`N4JSXpectTest`
Description	Checks that the type inferred at location is similar to expected type.
Example	`// XPECT type of 'x' --> string var x = 'hello'; // XPECT type of 'foo()' --> union{A,number} var any y = foo();`

Definition	-
Single line	`// XPECT expectedType at 'location' --> Type` The location (at) is optional.
Provided by	`N4JSXpectTest`
Description	Checks that an element/expression has a certain expected type (i.e. Xsemantics judgment expectedTypeIn).

Definition	Single line: `// XPECT elementKeyword at 'myFunction' -> function`
Example	`interface I { fld: int; get g(): string; set s(p:string); } //XPECT elementKeyword at 'string' --> primitive var v1: string; //XPECT elementKeyword at 'I' --> interface var i: I; //XPECT elementKeyword at 'fld' --> field i.fld;`
Provided by	`ElementKeywordXpectMethod`
Description	Checks that an element/expression has a certain element keyword. The expected element keyword is identical to the element keyword shown when hovering the mouse over that element/expression in the N4JS IDE. This method is particuarly useful for testing merged elements of union/intersection.

Definition	Single line: `// XPECT accessModifier at 'myFunction' -> function` or `// XPECT accessModifier -> function`
Example	`// XPECT accessModifier --> publicInternal export @Internal public abstract class MyClass2 { // XPECT accessModifier --> project abstract m1(): string; // XPECT accessModifier at 'm2' --> project m2(): string { return ""; } }`
Provided by	`AccessModifierXpectMethod`
Description	Checks that an element/expression has a certain accessibility.

Provided by	-
Description	This test should only be used during development of compiler and not used in the long run, because this kind of test is extremely difficult to maintain.

Provided by	-
Description	The most important test for compiler/transpiler, but also for ensuring that N4JS internal validations and assumptions are true at runtime.

Definition	Single line: `/* XPECT lint */`
Provided by	`CompileAndLintTest`
Description	Passes the generated code through the JSHint JavaScript linter. This test includes for instance checking for missing semicolons and undefined variables. The whole test exclusively refers to the generated javascript code.

Definition	Single line: `/* XPECT lintFails */`
Provided By	`CompileAndLintTest`
Description	Negation of lint. Fails on linting success. Expects linting errors.

Definition	Single line: `//` Multi line:
Provided by	`N4JSXpectTest`
Description	Checks that a given element is bound to something identified by (simple) qualified name. The check is designed as simple as possible. That is, simply the next following expression is tested, and within that we expect a property access or a direct identifiable element. The compared name is the simple qualified name, that is container (type) followed by elements name, without URIs of modules etc.

displayString	the string displayed in the proposal list
replacementString	simple variant of which is to be added to document, not necessarily the whole replacement (as this may affect several locations and even user interaction)

unordered	by default
ordered	the given expectations have to have that order, between these expectations other proposals may be present (in case of contains)

exactly	(default, maybe changed later) no other expectations as the given ones (usually `contains` is recommended).
contains	at least the given expectations must be present, but others may be there as well. Using contains must be used with care since we match items by searching for a proposal which contains one of the expected strings as a substring. So if the only available proposal were ’methodA2’ and we would test if proposals contain ’methodA’, ’methodA2’ we would obtain a passing test.
not	any of the given proposals must be NOT be proposed

Syntax	FIXME can be applied on any test just after the XPECT keyword: `// XPECT FIXME xpectmethod ... --> ...` Tests will still be ignored if an exclamation mark (!) is put between XPECT and FIXME.
Description	Using FIXME on a test negates the result of the underlying JUnit test framework. Thus a failure will be reported as a `true assertion` and an assertion that holds will be reported as `failure` . This enables to author valuable tests of behaviour, which is still not functional.
Example	For instance, if we encounter an error-message at a certain code position, but the code is perfectly right, then we have an issue. We can annotate the situation with a ’fix me’ ’noerrors’ expectation: `// Perfectly right behaviour XPECT FIXME noerrors --> console.log("fine example code with wrong error marker here.");` This turns the script into an Xpect test. We can integrate the test right away into our test framework and it will not break our build (even though the bug is not fixed). When the issue will be worked on, the developer starts with removing ’FIXME’ turning this into useful unit-test.

insert	(default) Ctrl not pressed, proposal is inserted at given location
override	Ctrl is pressed, proposal overrides selection.

Definition	Multi line: `/* XPECT organizeImports --- ~Failure given by line-syntax starting with two characters:~ + additional line \| line with inplace[removed part\|added part] + removed line unchanged line --- */ // XPECT warnings --> "The import of A is unused." at "A" import A from "a/a1/A" ... }` Single line: `// XPECT organizeImports ambiguous '~Failure String of Exception~'--> }`
Provided by	`OrganizeImportXpectMethod`
Description	Checks that the resulting source-file differs in the described way. The Multiline variant checks the result of a successful application of organise import to the file. All errors and warnings prior to organising imports must be marked as the appropriate XPECT-error or warning. The single-line notation checks the failure of an fully automatic reorganisation of the imports due to some reason. The reason is verified to be the given string after the `ambiguous` keyword. The expectation side (right of `-→`) is empty.
Example	/* XPECT_SETUP org.eclipse.n4js.tests.N4JSXpectPluginUITest Workspace { Project "P1" { Folder "src" { Folder "a" { Folder "a1" { File "A.n4js" { from="../../a/a1/A.n4js" } } Folder "c" { ThisFile {} } } } File "package.json" { from="package_p1.json" } } } END_SETUP / / XPECT organizeImports --- \| import [A from "a/a1/A"\|] \| [import\|] AR from "a/a1/A" export public role BRole with AR { } --- */ // XPECT warnings --> "The import of A is unused." at "A" import A from "a/a1/A" import AR from "a/a1/A" // XPECT noerrors --> "Couldn't resolve reference to Type 'AR'." export public role BRole with AR { }

N4JS Design Specification

Quick Links