sebastianbenz / jnario

Executable specifications for Java

Overview

Jnario is a framework for writing executable specifications for Java. It provides all the goodness of Xtend while being specifically tailored to writing acceptance and unit tests. It is easy to integrate as Jnario specifications are compiled to plain Java Junit tests. Head over to Jnario.org for more information.

See the release notes for the current version.

Dependencies & Installation

• Jnario requires at least Eclipse 3.6 with Xtext 2.6 and Xtend 2.6. You can install both from this update site http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/.
• The latest snapshot verion of Jnario can be installed from the following update site http://www.jnario.org/updates/snapshot/.

Examples

Acceptance Specification

Feature: Addition

  In order to avoid silly mistakes
  As a math idiot
  I want to be told the sum of two numbers
  
  Scenario: Add two numbers
    Calculator calculator = new Calculator()
    Given I have entered "50" into the calculator
      calculator.enter(args.first)
    And I have entered "70" into the calculator
    When I press "add"
      calculator.press(args.first)
    Then the result should be "120" on the screen
      calculator.result => args.first

Unit Specifications

package example

import java.util.Stack
import java.util.EmptyStackException

describe Stack{
  context "empty stack"{
    fact subject.size should be 0
    fact subject.pop throws EmptyStackException
  }
  context "one element"{ 
    before subject.add("element")
    fact subject.size should be 1
    fact "pop decreases size"{
      subject.pop
      subject.size => 0 
    }
    fact "pop removes last element"{
      subject.pop => "element"
      subject.contains("element") => true
    } 
  } 
}

Setting up a development environment

• If you haven't got an Eclipse installation, download the Xtend Distribution.
• Install the latest Xtext 2.6.1 release from: http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ (this is not required if you have downloaded the Xtend distribution).
• Install the latest Jnario snapshot: http://www.jnario.org/updates/snapshot/.
• Clone the jnario repository:

$ git clone git://github.com/bmwcarit/Jnario.git

• Start Eclipse and import all projects from jnario/* into your Eclipse workspace
• Open the target definition tools/org.jnario.target/juno.target and click Set as Target Plattform in the upper right corner
• If you want to change the grammar import org.eclipse.xtend.core and org.eclipse.xtext.xbase into your workspace via import->Plug-in Development->Plug-ins and Fragments with Import As->Projects with source folder. This is necessary for the workflow to find the custom source classes of Xtend and Xbase.

Build

Build with Maven 3 and Tycho. Run the following command in the repository root:

mvn clean install

jnario's Issues

Create type quickfix should add import

When creating a new type in a different package, a corresponding import statement should be generated.

No create type quickfix when using typeOf

The create type quickfix won't show for the following mockito example:

mock(typeof(EnumCompiler))

Feature request: Generating java classes and methods from specs

Hi,

In the documentation, you write "To turn our scenario into an executable specification you have to add the necessary code to each of our steps. For each step the implementation is done directly after the description of the step. The language used to define the logic is Xtend. Create a Java class with the name Calculator in the same project as your feature file. Add the necessary import to the feature file or include it by auto completion while typing (CTRL + SPACE)."

What I'd like to do is quite opposite. I'd like to be able to write:
Calculator calculator = new Calculator();
then click the quick fix and make eclipse generate the type for me. Now, I can only quick-fix it with generating an Extend class, which is not what I want.

Also, I'd like to be able to first write:
calculator.add(10);
and then choose quick fix to implement the method in Calculator type for me. Now, I can only quick-fix it with generating an extension method, which is not what I want.

Anyway, the power of JUnit is in that you can write the whole spec as you'd like the API to look, and then just click->generate class, click->generate method, click->generate method etc. This fits nicely with the Need Driven Development concept introduced by Steve Freeman and Nat Pryce. I'd be very grateful if you could somehow enable this, since it would be a great productivity boost, plus, this is a feature that is already enabled for specs written in native Java code, so it would be nice to have it in JNario as well.

[Feature Lang] Pending background steps missing @ignore in Scenario class

Given steps that are defined in a background get generated with the @ignore annotation in the Background java class but the in the Scenario Java class the step methods miss this annotation and appear therefor as passed in the JUnit test result.

[Suite Lang] Order resolved specs alphabetically

[Spec] Complex boolean expressions left of =>

Sorry, but here is another one :-)

(true && (true || true)) => true

Produces java, but not spec error:

_or cannot be resolved to a variable

necessary line break after example table

In feature files it is necessary to have a line break after an example table to be able to parse the file. Reason is the definition of the table in the grammar. Would be good if that is not necessary.

Add code completion templates

For specs:

context "${TEXT}"{

${cursor}

}

describe "${TEXT}"{
${cursor}
}fact "${TEXT}"{
${cursor}
}

For features:

Scenario: ${name}

Given ${context}
When ${trigger}
Then ${expectation}</template><template autoinsert="true" context="org.jnario.feature.Feature.Feature" deleted="false" description="new Scenario" enabled="true" name="Scenario">Scenario: ${name}

Given ${context}
When ${trigger}
Then ${expectation}</template></templates>

Literal for 'any' values

Introduce '_' as a new literal to declare extranous values. The value of the literal should be a default value of the expected type:

1 + _ => 1
_ => typeof(Object)
"a string" + _ => "a string"

[Feature Lang] Support calling other steps from within step implementations

"«" and "»" can't be entered within the spec editor

Hello,

the "«" and "»" characters can't be entered (using Ctrl+< on a German keyboard), if editing a spec file.

Eclipse Java EE IDE for Web Developers.

Version: Indigo Release
Build id: 20110615-0604

Jnario IDE 0.3.0.201209121203 org.jnario.ui.feature.group BMW Car IT
Jnario Runtime 0.3.0.201209121203 org.jnario.feature.group BMW Car IT
Jnario SDK 0.3.0.201209121203 org.jnario.sdk.feature.group BMW Car IT

[Spec Lang] Facts can call themselves

The following spec:

describe "something"{
fact myFact
}

doesn't show a validation error and results in a SOE. The problem is that for the fact a method "myFact" is generated that calls itself.

Calling function in subject does not compile

The code below is not compiling on the call to:

subject.bindCalculator(new DefaultCalculator())

The error message is: Couldn't resolve reference to JvmIndentifiableElement 'bindCalculator'

The code under test is in an OSGi bundle, and the spec is in a fragment

Here's the code...

package org.example.target;

public interface ICalculator {
    int add(int x, int y);
}


package org.example.target;

public class DefaultCalculator implements ICalculator {
    @Override
    public int add(int x, int y) {
        return x + y;
    }
}


package org.example.target;

public class Accumulator {
    public Accumulator()
    {
        this.sum = 0;
    }

    public void add(int value)
    {
        sum = calculator.add(sum, value);
    }

    public int getSum()
    {
        return sum;
    }

    public void bindCalculator(ICalculator calculator)
    {
        this.calculator = calculator;
    }

    private ICalculator calculator;
    private int sum;
}

package org.example.target

import org.example.target.Accumulator

describe Accumulator "Target"{
    before
    {
        subject.bindCalculator(new DefaultCalculator())
    }

    fact subject.sum should be 0

    fact "accumulating increases sum by value"
    {
        subject.add(10)
        subject.sum should be 10
    }
}

problems together with Xtext 2.4

Hi!

I am using the 2.4 nightly builds of Xtext and noticed that Jnario creates problems for Xtend. For example, Xtend breakpoints can't be set and some icons can't be found.

I'm not sure if you can do anything about this, but thought it might be useful to be aware of it.

Example error stacktrace is below.

best regards,
Vlad

241  [main] ERROR org.jnario.feature.ui.internal.FeatureActivator  - Failed to create injector for org.jnario.feature.Feature
242  [main] ERROR org.jnario.feature.ui.internal.FeatureActivator  - com.google.inject.internal.util.$ComputationException: java.lang.NoClassDefFoundError: org/eclipse/xtend/core/services/XtendGrammarAccess$ClassElements
com.google.inject.internal.util.$ComputationException: com.google.inject.internal.util.$ComputationException: java.lang.NoClassDefFoundError: org/eclipse/xtend/core/services/XtendGrammarAccess$ClassElements
        at com.google.inject.internal.util.$MapMaker$StrategyImpl.compute(MapMaker.java:553)
        at com.google.inject.internal.util.$MapMaker$StrategyImpl.compute(MapMaker.java:419)
........
        at com.google.inject.internal.InternalInjectorCreator.build(InternalInjectorCreator.java:106)
        at com.google.inject.Guice.createInjector(Guice.java:95)
        at com.google.inject.Guice.createInjector(Guice.java:72)
        at com.google.inject.Guice.createInjector(Guice.java:62)
        at org.jnario.feature.ui.internal.FeatureActivator.createInjector(FeatureActivator.java:67)
        at org.jnario.feature.ui.internal.FeatureActivator.getInjector(FeatureActivator.java:55)
        at org.jnario.feature.ui.FeatureExecutableExtensionFactory.getInjector(FeatureExecutableExtensionFactory.java:25)
        at org.eclipse.xtext.ui.guice.AbstractGuiceAwareExecutableExtensionFactory.create(AbstractGuiceAwareExecutableExtensionFactory.java:49)

Expecting exception does not compile

Hopefully this is a real problem ...

Given the class:

public class Test {
    void doSomething(int value)
    {
        if(value < 0)
            throw new IllegalStateException();
    }
}

and the spec:

describe Test {
    fact subject.doSomething(-1) throws IllegalStateException
}

The generated code does not compile. It tries to assign the void return value to a variable.

Create method quickfix fails for mock

Invoking the create method quickfix results in a NPE for the following mockito example:

 verify(compiler).compile(selectedFiles)

Stacktrace:

Caused by: java.lang.NullPointerException
at org.jnario.ui.quickfix.CreateJavaMethod$1.apply(CreateJavaMethod.java:57)
at org.jnario.ui.quickfix.CreateJavaMethod$1.apply(CreateJavaMethod.java:1)
at org.eclipse.xtext.xbase.lib.IterableExtensions.forEach(IterableExtensions.java:395)
at org.jnario.ui.quickfix.CreateJavaMethod.generateMethod(CreateJavaMethod.java:65)
at org.jnario.ui.quickfix.CreateJavaMethod.apply(CreateJavaMethod.java:37)
at org.eclipse.xtext.ui.editor.quickfix.IssueResolution.apply(IssueResolution.java:80)

[Spec Lang] Duplicate Methods are generated for facts with special charactes

Two facts:

 fact "a***" 

and
fact "a???"

will generate the same method as the special characters will be deleted.

[Mock] Let's discuss mocking

Hello Sebastian,

I read about your wish to discuss mocking support within Jnario/Xteand. This is exactly one of my tasks at the moment :-)

I evaluated all available mock libraries. At the mean time the Jmockit is in my option the best one. The core features:

• Mocking of everything including static methods, constructors, ....
• Proving the mock class definition in the middle of the tested code without need to do anything
• Two APIs to choose from

How do you plan to integrate the mock API? I would suggest to override some of the Xtend Nonterminals, like BlockExpression (or something like this) to introduce some new keywords ('mock', 'stub', ...).

What do you think?

[Suite Lang] Add validation when a suite references itself

[Feature Lang] Show step implementation in step hover

XtextCasts

Hello Sebastian,

I would like to point you to the last episode of the XtextCasts about Jnario, that I made last week:

http://xtextcasts.org/episodes/9-jnario-test-framework

I find your framework incredible cool and plan to make more detailed episodes in the future. Any critics are appreciated :-)
Please, feel free to post comments to the episode, if you fill, that the information could be useful for others. 

Regards,
Boris

free text after feature definition

After a feature definition it should be possible to write free text before the first background or scenario.

Jnario is not working with Mockito

I'm trying to get Jnario to work with Mockito, and I'm having problems. Here's a simple example:

package org.example.target

import static org.mockito.Mockito.*;
import java.util.List

describe "Test"{
    before {
        myList = mock(List::class)  << Incompatible types.  Expected java.uti.List or java.lang.Object[] but was java.lang.Object
    }

    List myList;
}

Here's something else I tried:

package org.example.target

import static org.mockito.Mockito.*;
import java.util.List

describe "Test"{
    List myList = mock(List::class) << Incompatible implicit return type.  Expected java.uti.List or java.lang.Object[] but was java.lang.Object
}

Ideally, I'd like to use @mock, but that requires either the MockitoJUnitRunner which I understand we can't use, or

MockitoAnnotations.initMocks(this)

which does not work either.

[Spec] Problems with automatic conversion from List to Array

In xtend a List is automatically converted to an array if needed.
This does not seem to work in JNario.

The following xtend code:

package net.davymeers.demo

class Test {
    def String[] x(){
        newArrayList("some string")
    }
}

gives problems when used in JNario spec:

package net.davymeers.demo

import java.lang.String

describe String "String"{

    def String[] x(){
        list("some string")
    }

}

Namely:

• No viable input at '[]'
• Mismatched input '{' expecting '=>'
• Extraneous input '"some string"' expecting ')'
• The field list needs an explicit type since there is no initialization expression to infer the type from
• The field null needs an explicit type since there is no initialization expression to infer the type from*
• mismatched input '}' expecting '=>'

As a workaround you can use varargs in a conversion function.

generation of documentation for features

Add wait expression to Jnario Lib

First draft:

waitUntil[x > 42]
waitUntil[
duration = 100
pollingInterval = 1
x > 42
]

[Feature Lang] Generate separate class for every step

Generate a separate class for every step in order to make it's reuse either.

Auto import feature

In Xtend I miss some kind of auto-import of the static extensions. For example, I always import the Matchers and my personal collection of Xtend extensions.

This could be done by defining some kind of annotation of the one of the base classes. Something like this:

@XtendAutoImport({"my.cool.extensions"}, static = true, extension = true)
class AbstractTest {
}

For this to work, you will need a way to extend test classes from this AbstractTest or add it with the JUnit-Rule.

[Feature Lang] In JUnit view propagate ignored symbol to scenario and feature if all steps/scenarios are ignored

Cannot install (missing junit bundle)

Could not install using the eclipse update site.

Missing requirement: Jnario Library 0.1.0.201207031315 (org.jnario.lib 0.1.0.201207031315) requires 'bundle org.junit 4.10.0' but it could not be found

[Spec Lang] Fix false duplication error in specs

Currently there is a validation error when multiple specs in the same file reference a type, eg:

    describe String{

    }

    describr Integer{

    }

[Spec Lang] Code completion does not work in facts without description

The code completion doesn't work for facts without a description. The same problem also occurs for before and after.

[Feature Lang] Normalize white space for multine string arguments

Give a step with a multiline argument:
'''
hello
world
'''
Then the argument value should be " hello\n world\n"

[Feature Lang] Fix support for extension field

Referencing steps which require an extension field currently results in a compile error.

Include execution status (pending, passed, failed) into generated documentation

[Feature Lang] No proposals for steps without implementation

Currently the editor does not propose steps which have no implementation and are defined in a different file.

with-operator support

Please support the "with-operator" (=>) of Xtend 2.3.

// in context section and value definition
val subject = new Subject => [
name = 'xxx'
date = new Date
]

val article = ModelFactory::createArticle => [
title = 'foo'
author = 'bar'
]

// in before section
before {
object => [
member = value
]
}

// in fact section
fact '...' {
subject.post(new Article => [title='xxx']) => Accepted
}

// in def section
...

I love Jnario.

[Feature Lang] Using different spoken languages

With cucumber it is possible to use different spoken languages within feature definitions:

https://github.com/cucumber/cucumber/wiki/Spoken-languages

It would be great, if Jnario had the same feature too. I think, that the solution with the '# language: XX' first line comment would be convenient way to do this.

Thank you for the great tool !

Compiler main method should return error codes

As a Java software developer when compiling jnario files with gradle using the main method org.jnario.compiler.CompilerMain I would like grade to stop the build if the compilation fails.

To enable that gradle should be able to recognize the outcome of the compilation. This can be done by changing the

public static void main(String[] args)

to

public static int main(String[] args)

and returning 0 if the compilation succeeds and an error code other than 0 when the compilation fails.

[Feature Lang] Make extension fields in Backgrounds usable from Scenarios

[Feature Lang] problem with field inference for background steps

Example:

Feature: Feature 1
Background:
String testString
Given something
testString = "test"
And it is upper case
testString.toUpperCase

Feature: Feature 2
Background:
Given something
Scenario: Scenario 1
Given it is upper case

For the second feature in the Background class there is a field "String testString"(which is ok) but also in the Scenario class a field "private String testString" is generated, which shouldn't be there -> results in NullPointerException.

highlight of last pipe in example table not correct

The hightlighting of the last pipe in the example header should be added.

Multi-byte characters

Multi-byte characters are not displayed correctly in JUnit view when used in the labels "describe", "context" or "fact".

[Feature Lang] Remove invalid duplicate type validation

The following feature results in a validation error:

import java.util.Stack

Feature: Stack

....

[Feature Lang] Step proposals should automatically add import statements

When a step is defined in a different package, the code completion should automatically add the required import statements.

[Spec] Long specs brake Jvm -> Eclipse JUnit communication

If you use a lot of assertions in a spec fact (for example 30 or more), then the name of the spec becomes very long. As a consequence, Eclipse JUnit view looses the network connection to the Jvm (tested on Windows).

Suggestion: cut long names of the facts up to 200 or 300 characters.

double click on word step in feature shouldn't select the entire step

In feature files when double clicking on a word in a step the entire step is selected instead of the word.

[Spec] Assertion "obj => null" doesn't work

In a spec the line

object => null

results in a java error but not the spec error (double click on the error message does nothing).

The method assertTrue(String, boolean) in the type Assert is not applicable for the arguments (String, Integer)

The problem is, that the "ObjectExtensions::operator_doubleArrow()" get called.

Workarounds:

• object should be null
  • (contra: "should be null" and "should not be null" can't be parted at the first glance, especially within multiple lines of the same pattern)
• object => nullValue
  • (contra: not intuitive)

[Feature Lang] Add support for "But"

[Spec Lang] Fix potential runtime exception with implicit subjects

The following spec will result in a runtime exception:

 describe Integer{
   before subject = new Integer(3) 
   fact subject => 3
 }

Jnario does not know if the subject field is initialized within a spec.