gh-5: guides/setup section

pages/guide/setup.md

@@ -16,28 +16,30 @@ First, you need to choose which test framework you are going to use.
 
 Testdeck supports Mocha, Jasmine and Jest.
 
-With some limitations, you can always change the test framework later on. (limitations: assertion/expectation framework.)
+With some limitations, you can always change the test framework later on.
+
+Current limitations are the mocking framework and the assertion/expectation framework that you will use.
 
 ### Mocha
 
 {% highlight shell %}
-npm install @testdeck/mocha mocha @types/mocha
+npm install --save-dev @testdeck/mocha mocha @types/mocha
 {% endhighlight %}
 
 Alternatively, you can clone the existing <a href="https://github.com/testdeck/testdeck-mocha-seed">mocha-seed</a> and start from there.
 
 ### Jasmine
 
 {% highlight bash %}
-npm install @testdeck/jasmine jasmine @types/jasmine
+npm install --save-dev @testdeck/jasmine jasmine @types/jasmine
 {% endhighlight %}
 
 Alternatively, you can clone the existing <a href="https://github.com/testdeck/testdeck-jasmine-seed">jasmine-seed</a> and start from there.
 
 ### Jest
 
 {% highlight bash %}
-npm install @testdeck/jest jest @types/jest
+npm install --save-dev @testdeck/jest jest @types/jest
 {% endhighlight %}
 
 Alternatively, you can clone the existing <a href="https://github.com/testdeck/testdeck-jest-seed">jest-seed</a> and start from there.
@@ -63,17 +65,34 @@ npm install --save-dev chai @types/chai
 #### Example Code
 
 {% highlight TypeScript linenos %}
-import { suite, test } from '@testdeck/mocha';
+import { suite, test } from '@testdeck/mocha'; // might as well use jasmine/jest here
 import * as chai from 'chai';
 
+// let's have chai should augmentations
+chai.should();
+
 @suite
 class TestSuite {
 
   @test
-  someTest() {
+  assertTest() {
 
     chai.assert.isOk(false);
   }
+
+  @test
+  expectTest() {
+
+    chai.expect(false).to.be.true;
+  }
+
+  @test
+  shouldTest() {
+
+    const val = false;
+
+    val.should.be.true;
+  }
 }
 {% endhighlight %}
 
@@ -87,9 +106,10 @@ class TestSuite {
 {% highlight TypeScript linenos %}
 {% endhighlight %}
 
+
 ### NodeJS assert
 
-A simple assertion framework that is included with the standard NodeJS library.
+A simple, no fuss, assertion framework that is included with the standard NodeJS library.
 
 #### Setup
 
@@ -98,7 +118,7 @@ This is part of the standard NodeJS library.
 #### Example Code
 
 {% highlight TypeScript linenos %}
-import { suite, test } from '@testdeck/mocha';
+import { suite, test } from '@testdeck/mocha'; // might as well use jasmine/jest here
 import * as assert from 'assert';
 
 @suite
@@ -115,32 +135,135 @@ class TestSuite {
 
 ### Jasmine built-in
 
+For Jasmine, we recommend the built-in expectation framework.
+
+#### Setup
+
+This is an integral part of Jasmine.
+
+#### Example Code
+
+{% highlight TypeScript linenos %}
+import { suite, test } from '@testdeck/jasmine';
+
+@suite
+class TestSuite {
+
+  @test
+  someTest() {
+
+    expect(false).toBe(true);
+  }
+}
+{% endhighlight %}
+
 
 ### Jest built-in
 
+For Jest, we recommend the built-in expectation framework.
 
-<dt>assert</dt>
+#### Setup
 
-<dt>Jasmine built-in</dt>
-<dd>For Jasmine, we recommend the built-in expectation framework.</dd>
+This is an integral part of Jest.
 
-<dt>Jest built-in</dt>
-<dd>For Jest, we recommend the built-in expectation framework.</dd>
-</dl>
+#### Example Code
+
+{% highlight TypeScript linenos %}
+import { suite, test } from '@testdeck/jest';
+
+@suite
+class TestSuite {
+
+  @test
+  someTest() {
+
+    expect(false).toBe(true);
+  }
+}
+{% endhighlight %}
+
+
+### Our Recommendation
+
+For you to be able to switch between test frameworks easily, we recommend that you use the expectation style alone.
 
 
 ## Mocking Frameworks
 
-<dl>
-<dt>Sinon</dt>
-<dd>For mocha, we recommend Sinon.</dd>
 
-<dt>Jasmine built-in</dt>
-<dd>For Jasmine, we recommend using the built-in mocking facility.</dd>
+### Sinon
 
-<dt>Jest built-in</dt>
-<dd>For Jest, we recommend using the built-in mocking facility.</dd>
-</dl>
+#### Setup
+
+#### Example Code
+
+
+### Jasmine built-in
+
+Jasmine provides you with a built-in mocking facility.
+
+#### Setup
+
+This is an integral part of Jasmine.
+
+#### Example Code
+
+{% highlight TypeScript linenos %}
+import { suite, test } from '@testdeck/jasmine';
+
+class SUT {
+
+  private flags: {};
+
+  public setFlag(flag: string, value: boolean): void {
+
+    this.flags[flag] = value;
+  }
+
+  public getFlag(flag: string): boolean {
+
+    return this.flags[flag] || false;
+  }
+}
+
+@suite
+class TestSuite {
+
+  private sut: SUT;
+
+  before() {
+
+    this.sut = new SUT();
+  }
+
+  @test
+  someTest() {
+
+    spyOn(this.sut, 'getFlag').and.returnValue(false);
+    expect(this.sut.getFlag('foo')).toBe(true);
+  }
+}
+{% endhighlight %}
+
+
+### Jest built-in
+
+Jest, similarly to Jasmine, provides you with a built-in mocking facility.
+
+And we will not go into length here on how that works.
+
+See the official documentation [here](https://jestjs.io/docs/en/jest-object.html) and [here](https://jestjs.io/docs/en/mock-function-api).
+
+#### Setup
+
+This is an integral part of Jest.
+
+#### Example Code
+
+Since Jest is highly opinionated about its mocks, we refrain from providing you with an example here. YMMV.
+
+
+### Our Recommendation
 
 
 ## Dependency Injection