nole 2.2.2 → 3.1.0

package/README.md

@@ -1,388 +1,474 @@
-![](docs/nole.png)
-
-Nole
-==========
-
-Nole is a testing platform just like mocha.. You can create test classes and declare specs with decorators..
-
-> Use nole 2.x for ESM and Typescript.
-
-> Use nole 1.x for CommonJS. (ability to disable Typescript with -T option)
-
-```ts
-// test/queue.test.ts
-import { Spec } from 'nole';
-
-class QueueTest {
-  queue!: Queue;
-
-  @Spec()
-  CreateInstance() {
-    this.queue = new Queue();  
-  }
-
-  @Spec()
-  Push() {
-    this.queue.push(10);
-  }
-
-  @Spec(1000)
-  async Pipe() {
-    await this.queue.pipe(somewhere);
-  }
-}
-```
-
-```bash
-$ nole ./test/**/*.test.ts
-  (ok)      0.09 ms QueueTest.CreateInstance()
-  (ok)      0.11 ms QueueTest.Push()
-  (ok)      1.09 ms QueueTest.Pipe()
-```
-
-## Spec
-
-Declaring the spec tag will notify the nole core and assigns the tasks for later use. You can also specify timeout. Default timeout is 5000 ms.
-
-```ts
-// test/queue.test.ts
-import { Spec } from 'nole';
-
-class QueueTest {
-  @Spec(10000)
-  Push() {
-    this.queue.push(10);
-  }
-}
-```
-
-> * All specs will be executed as creation order.
-> * Timing colors are defined by timeout value. If value smaller than (timeout / 5) output will be green. If value bigger than this but smaller than (timeout / 2.5); it will be yellow. In all other cases color will be red.
-
-
-## Skip
-
-You can skip tests. (hooks will be disabled for this spec)
-
-```ts
-// test/queue.test.ts
-import { Spec, Skip } from 'nole';
-
-class QueueTest {
-  @Skip('deprecated unit')
-  @Spec()
-  Push() {
-    this.queue.push(10);
-  }
-}
-```
-
-> * Skipping the task make it yellow colored.
-
-```bash
-$ nole ./**/test/*.test.ts
-  (skip)              QueueTest.Push() {deprecated unit}
-```
-
-## SkipClass
-
-You can skip whole test classes. It's equivalent of spec skipping, but you don't have to select one by one. 
-**Kindly reminder**: Dependents might require this test class and props. 
-
-```ts
-// test/queue-skip-class.test.ts
-import { Spec, Skip, SkipClass } from 'nole';
-
-@SkipClass('No need anymore')
-class QueueTest {
-  @Spec()
-  Push() { }
-
-  @Skip('deprecated unit')
-  @Spec()
-  PushButSomehowDifferent() { }
-}
-```
-
-```bash
-$ nole ./**/test/*.test.ts
-  (skip)              QueueTest.Push() {No need anymore}
-  (skip)              QueueTest.PushButSomehowDifferent() {deprecated unit}
-```
-
-
-## Dependencies
-
-You can include other tests and wait them to complete.
-
-```ts
-// test/database.test.ts
-import { Spec } from 'nole';
-
-export class Database {
-  connection!: any;
-
-  @Spec() 
-  async Connect() {
-    connection = new Connection('...');
-
-    await connection.connect();
-  }
-}
-```
-
-```ts
-// test/other.test.ts
-import { Spec, Dependency } from 'nole';
-import { Database } from './database.test';
-
-class Other {
-  @Dependency(Database)
-  database!: Database;
-
-  @Spec() 
-  async DoThings() {
-    await database.connection.doStuff();
-  }
-}
-```
-
-> * All dependencies will be waited until done
-> * If dependencies cannot resolve, it will occurr an error after the available tests done.
-
-
-## Multi Dependencies
-
-Easier way to declare dependencies by decorating class with an array.
-
-```ts
-// test/redis.test.ts
-import { Spec, Dependencies } from 'nole';
-import { Database } from './database.test';
-import { Other } from './other.test';
-
-@Dependencies([
-  Database,
-  Other
-])
-class Redis {
-  database: Database; // camel-case syntax
-  // even though other does not exist in this test, but nole will make sure it is completed when this test runs
-
-  @Spec() 
-  async DoThings() {
-    await database.connection.doStuff();
-  }
-}
-```
-
-## Lazy multi Dependencies / after
-
-Can solve order of execution issues
-
-```ts
-// test/redis.test.ts
-import { Spec, Dependencies, After } from 'nole';
-
-@Dependencies(() => [ B ])
-// or
-// @After(() => [ B ])
-class A {
-  b: B;
-
-  @Spec() 
-  async DoThings() { }
-}
-
-class B {
-  @Spec() 
-  async DoThings() { }
-}
-```
-
-## Reverse dependency / dependent / before
-
-
-
-```ts
-// test/redis.test.ts
-import { Spec, Dependents, Before } from 'nole';
-
-class A {
-  b: B;
-
-  @Spec() 
-  async DoThings() { }
-}
-
-@Before(() => [ A ])
-class B {
-  @Spec() 
-  async DoThings() { }
-}
-```
-
-## Hook
-
-Hooks will help you to develop helper methods.
-
-```ts
-// test/hook.test.ts
-import { Spec, Hook, HookType } from 'nole';
-
-class HookTest {
-  value!: number;
-
-  @Hook(HookType.BeforeEach)
-  async beforeEach() {
-    this.value = Math.random();
-  }
-
-  @Spec()
-  ValidateNumber() {
-    if (this.value > 0.5) {
-      throw new Error('Should not be higher than 0.5');
-    }
-  }
-}
-```
-
-> * Hooks can be async tasks.
-> * Hooks do have timeout, you can change it by second parameter.
-> * If you name hook same as hook type then; When it occurr an error, It will print "class:hookType" otherwise "class.name:hoopType"
-> * Hooks cannot be spec
-> * Hooks cannot skipped
-
-## Dynamic Tests
-
-Dynamic tests are not featured in but you can create another method and call it dynamicly.
-
-
-```ts
-// test/dynamic.test.ts
-import { Spec } from 'nole';
-
-class DynamicTest {
-  @Spec()
-  Some() {
-    for (let i = 0; i < 10; i++) {
-      this.single(i);
-    }
-  }
-
-  single(i) {
-    // ...    
-  }
-}
-```
-
-## Dependency hook
-
-After end of the test tree, special hook will be called. Nole will follow execution order to run; first executed spec's "CleanUp" hook will be called last.
-
-
-```ts
-// test/database-with-cleanup.test.ts
-import { Spec, HookType, Hook } from 'nole';
-
-export class DatabaseWithCleanup {
-  connection!: any;
-
-  @Spec() 
-  async Connect() {
-    connection = new Connection('...');
-
-    await connection.connect();
-  }
-
-  @Hook(HookType.CleanUp)
-  async cleanUp() {
-    this.connection.close();
-    console.log('Connection closed!');
-  }
-}
-```
-
-```ts
-// test/other.test.ts
-import { Spec, Dependency } from 'nole';
-import { Database } from './database.test';
-
-class Other {
-  @Dependency(DatabaseWithCleanup)
-  database!: DatabaseWithCleanup;
-
-  @Spec() 
-  async DoThings() {
-    await database.connection.doStuff();
-  }
-}
-```
-
-```bash
-$ nole ./test/**/*.test.ts
-  (ok)      0.09 ms DatabaseWithCleanup.Connect()
-  (ok)      0.11 ms Other.DoThings()
-Connection closed!
-```
-
-
-
-## Assert
-
-We do not provide assert library. You can use chai or should.js.
-
-## Debugging
-
-Having cleanup features with missing dependencies could lead to issues and time loses. To make sure execution of tests correct, use `-O` parameter to print out every spec and hook without calling the function. It will also print before/after hook orders.
-
-```bash
-$ nole -O ./test/**/*.test.ts
-  (skip)             SkipAllTest.wontRun() {skip all class}
-  (skip)             SkipAllTest.wontRunToo() {wont run too}
-  (skip)             SkipAllWithoutReason.wontRun()
-   (ok)         0 ms BasicTest.checkEqual()
-   (ok)         0 ms DependencyTest.check()
-   (ok)         0 ms CleanUpLayer1Test.start()
-   (ok)         0 ms CleanUpLayer2Test.start()
-   (ok)         0 ms CleanUpLayer3Test.start()
-   (ok)         0 ms DynamicSkipTest.thisShouldBeSkipped()
-   (ok)         0 ms HookTest.pushFourIntoArray:beforeEach()
-   (ok)         0 ms HookTest.hasToBe4()
-  (skip)             HookTest.hasToBe4Again() {no need}
-   (ok)         0 ms HookTest.pushFourIntoArray:beforeEach()
-   (ok)      0.03 ms HookTest.hasToBe4AgainButNotSkipped()
-   (ok)         0 ms MultiDependency.test()
-   (ok)         0 ms CleanUpLayer3Test:cleanUp()
-   (ok)         0 ms CleanUpLayer2Test:cleanUp()
-   (ok)         0 ms CleanUpLayer1Test:cleanUp()
-   (ok)         0 ms DynamicTest.thisTestsShouldNotFail()
-   (ok)         0 ms TimeFactorTest.evaluate()
-   (ok)         0 ms TimeDifferenceTest.evaluate()
-   (ok)         0 ms ExecutorTest.evaluate()
-   (ok)         0 ms ExecutorTest.throws()
-   (ok)         0 ms ExecutorTest.timeout()
-```
-
-## Compiled files
-
-> Deprecated (v2.x+), It will always use ts-node/esm module
-
-You can run the compiled test files with `-T` option.
-
-```bash
-$ nole -T ./build/test/**/*.test.js
-  (ok)      0.09 ms QueueTest.CreateInstance()
-  (ok)      0.11 ms QueueTest.Push()
-  (ok)      1.09 ms QueueTest.Pipe()
-```
-
-> This will prevent to load ts-node register. It will be quite faster.
-
-## Environment values to configure stuff
-
-```
-NOLE_PRESERVE_CONSECUTIVE_UPPERCASE=true
-NOLE_PASCALCASE=false
-NOLE_WAIT_PERIOD=500
-```
+![](docs/nole.png)
+
+# Nole
+
+Nole is a testing platform just like mocha.. Feels simple, works really well.
+
+```ts
+// test/queue.test.ts
+import { Test } from "nole";
+
+export class QueueTest extends Test() {
+  queue!: Queue;
+
+  createInstance() {
+    this.queue = new Queue();
+  }
+
+  push() {
+    this.queue.push(10);
+  }
+
+  async pipe() {
+    await this.queue.pipe(somewhere);
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (ok)      0.09 ms QueueTest.createInstance()
+  (ok)      0.11 ms QueueTest.push()
+  (ok)      1.09 ms QueueTest.pipe()
+```
+
+## Skip
+
+You can skip tests. Make sure method name starts with skip
+
+```ts
+// test/queue.test.ts
+import { Test } from "nole";
+
+export class QueueTest extends Test() {
+  skip_Push() {
+    this.queue.push(10);
+  }
+}
+```
+
+```bash
+$ nole ./**/test/*.test.ts
+  (skip)              QueueTest.skip_Push() {marked as skipped}
+```
+
+```ts
+// test/queue.test.ts
+import { Test } from "nole";
+
+export class QueueTest extends Test({
+  skip: "no need",
+}) {
+  push() {
+    this.queue.push(10);
+  }
+}
+```
+
+```bash
+$ nole ./**/test/*.test.ts
+  (skip)              QueueTest.skip_Push() {no need}
+```
+
+## Dynamic Skip
+
+Sometimes you only know at runtime whether a test should run. Call `skipTest()`
+inside a spec to skip just that spec.
+
+```ts
+// test/queue.test.ts
+import { Test, skipTest } from "nole";
+
+export class QueueTest extends Test() {
+  push() {
+    if (!process.env.QUEUE_URL) {
+      skipTest("QUEUE_URL is not set");
+    }
+
+    this.queue.push(10);
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (dskip)          QueueTest.push() {QUEUE_URL is not set}
+```
+
+### Skipping the whole class
+
+Use `skipClass()` to dynamically skip every remaining spec of the class. This is
+handy inside the `before` hook, so an unmet precondition skips the entire class
+instead of failing.
+
+```ts
+// test/queue.test.ts
+import { Test, skipClass } from "nole";
+
+export class QueueTest extends Test() {
+  async before() {
+    if (!process.env.QUEUE_URL) {
+      skipClass("QUEUE_URL is not set");
+    }
+  }
+
+  push() {
+    this.queue.push(10);
+  }
+
+  async pipe() {
+    await this.queue.pipe(somewhere);
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (dskip)          QueueTest:before() {QUEUE_URL is not set}
+  (dskip)          QueueTest.push()
+                        ↳ skip came from :before
+  (dskip)          QueueTest.pipe()
+                        ↳ skip came from :before
+```
+
+> You can also call `skipClass()` from a spec — every spec that hasn't run yet
+> will be skipped, and the report shows where the skip came from.
+>
+> `skipClass()` can only be used inside specs and the `before` hook. Hooks
+> cannot be skipped — calling `skipTest()` inside `before` is an error; you
+> probably meant `skipClass()`.
+
+## Internal functions
+
+Nole treats every method as a spec by default. If you need a plain helper method
+that Nole should not run as a spec, prefix its name with `_`.
+
+```ts
+// test/queue.test.ts
+import { Test } from "nole";
+
+export class QueueTest extends Test() {
+  async _connect() {
+    // not a spec, just a helper you call yourself
+    return new Connection("...");
+  }
+
+  async push() {
+    const conn = await this._connect();
+    conn.push(10);
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (ok)      0.11 ms QueueTest.push()
+```
+
+> The prefix is configurable via the `SPEC_SKIP_PREFIX` environment variable
+> (defaults to `_`).
+
+## Dependencies
+
+You can include other tests and wait them to complete.
+
+```ts
+// test/database.test.ts
+import { Test } from "nole";
+
+export class Database extends Test() {
+  connection!: any;
+
+  async connect() {
+    connection = new Connection("...");
+
+    await connection.connect();
+  }
+}
+```
+
+```ts
+// test/other.test.ts
+import { Test } from "nole";
+import { Database } from "./database.test";
+
+export class Other extends Test({
+  dependencies: {
+    database: () => Database,
+  },
+}) {
+  async DoThings() {
+    await this.database.connection.doStuff();
+  }
+}
+```
+
+> - All dependencies will be waited until done
+> - If dependencies cannot resolve, it will occurr an error after the available tests done.
+
+## Wait other tests
+
+```ts
+// test/redis.test.ts
+import { Test } from "nole";
+
+export class A extends Test() {
+  async doThings() {}
+}
+
+export class B extends Test({ before: () => [A] }) {
+  async doThings() {}
+}
+```
+
+## Hook
+
+Hooks will help you to develop helper methods.
+
+```ts
+// test/hook.test.ts
+import { Test } from "nole";
+
+export class HookTest {
+  value!: number;
+
+  async beforeEach() {
+    this.value = Math.random();
+  }
+
+  validateNumber() {
+    if (this.value > 0.5) {
+      throw new Error("Should not be higher than 0.5");
+    }
+  }
+}
+```
+
+## Dynamic Tests
+
+```ts
+// test/dynamic.test.ts
+import { Test, addTest } from "nole";
+
+// not exported, nole cannot auto-bind this class
+class DynamicTest extends Test() {
+  test() {}
+}
+
+// adds it anyway
+addTest(() => DynamicTest);
+```
+
+```ts
+// test/dynamic2.test.ts
+import { Test, addTest } from "nole";
+
+if (something) {
+  addTest(
+    () =>
+      class Special extends Test() {
+        check() {}
+      },
+  );
+}
+```
+
+```ts
+// test/dynamic3.test.ts
+import { Test, addTest } from "nole";
+
+export class DeepTest extends Test() {
+  check() {
+    if (something) {
+      addTest(() => class Wololo extends Test() {});
+    }
+  }
+}
+```
+
+## Test cleanup
+
+There is a special hook that can be used to capture test finishing stage.
+
+> **Lifecycle:**
+>
+> - (class) Before
+> - - (method) BeforeEach
+> - - (method) Spec
+> - - (method) AfterEach
+> - (class) After
+> - (class) CleanUp \*called after dependency execution
+
+```ts
+// test/database-with-cleanup.test.ts
+import { Test } from "nole";
+
+export class DatabaseWithCleanup extends Test() {
+  connection!: any;
+
+  async connect() {
+    this.connection = new Connection("...");
+
+    await connection.connect();
+  }
+
+  async cleanUp() {
+    this.connection.close();
+    console.log("Connection closed!");
+  }
+}
+```
+
+```ts
+// test/other.test.ts
+import { Test } from "nole";
+import { Database } from "./database.test";
+
+export class Other extends Test({
+  dependencies: {
+    database: () => DatabaseWithCleanup,
+  },
+}) {
+  async doThings() {
+    await this.database.connection.doStuff();
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (ok)      0.09 ms DatabaseWithCleanup.connect()
+  (ok)      0.11 ms Other.doThings()
+Connection closed!
+```
+
+## Test extending
+
+If they are classes we should be able to extend them right
+
+```ts
+// test/extending.test.ts
+import { Test } from "nole";
+
+// Simple is not exported, so nole wont handle it
+class Simple extends Test() {
+  value = 1;
+
+  check() {
+    if (this.value !== 1) {
+      // yeah it should be 1 anyway
+    }
+  }
+}
+
+export class Complex extends Simple {
+  check() {
+    if (this.value > 0) {
+      // maybe it is more than just 1?
+    }
+
+    super.check(); // or
+  }
+}
+
+export class MoreComplex extends Simple {
+  moreSpecs() {
+    // mooree
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (ok)      0.09 ms Complex.check()
+  (ok)      0.11 ms MoreComplex.check()
+  (ok)      0.11 ms MoreComplex.moreSpecs()
+```
+
+### Execution order
+
+Inherited specs run parent-first, so a child can rely on the state left behind
+by its ancestors.
+
+```ts
+// test/inheritance.test.ts
+import * as assert from "assert";
+import { Test } from "nole";
+
+export class GrandparentTest extends Test() {
+  variable = 1;
+
+  async doesSomething() {
+    assert.equal(this.variable, 1);
+    this.variable = 2;
+  }
+}
+
+export class FatherTest extends GrandparentTest {
+  async doesSomethingElse() {
+    assert.equal(this.variable, 2);
+    this.variable = 3;
+  }
+}
+
+export class ChildTest extends FatherTest {
+  async doesMoreStuff() {
+    assert.equal(this.variable, 3);
+    this.variable = 4;
+  }
+}
+```
+
+```bash
+$ nole ./test/**/*.test.ts
+  (ok)      0.09 ms ChildTest.doesSomething()
+  (ok)      0.10 ms ChildTest.doesSomethingElse()
+  (ok)      0.11 ms ChildTest.doesMoreStuff()
+```
+
+### Inheriting behavior
+
+Skips and hooks are inherited too. A `skipClass()` defined on a base class skips
+every subclass that reaches it, and an overridden hook can call `super` to keep
+the parent's setup.
+
+```ts
+// test/inheritance.test.ts
+import { Test, skipClass } from "nole";
+
+// not exported, only used as a base
+class CompanyTest extends Test() {
+  async noWorkingAllowed() {
+    skipClass("no working allowed");
+  }
+}
+
+export class EmployeeTest extends CompanyTest {
+  async work() {
+    // never runs, the class is skipped
+  }
+}
+
+class HookInitialTest extends Test() {
+  variable = 1;
+
+  before() {
+    this.variable = 2;
+  }
+
+  test() {
+    assert.equal(this.variable, 2);
+  }
+}
+
+export class HookOverrideTest extends HookInitialTest {
+  before() {
+    super.before(); // keep the parent's setup
+    this.variable = 10;
+  }
+
+  test() {
+    assert.equal(this.variable, 10);
+  }
+}
+```