docs: add jest and mocha tutorial (#39)

* docs: add jest tutorial

* docs: move tutorial.md to docs/jest-tutorial.md and add keeping Jests expect section

* docs: add install and usage section to README.md and moved Development section to docs/development.md

* docs: add mocha tutorial and minor fix to jest tutorial

* docs: added links to tutorials in README

* address @JoseLion feedback

* implement feedback from @JoseLion

* Implement feedback

* Address feedback from @jpvillaisaza and @flandrade

Co-authored-by: Christian <[email protected]>

Author: ChristianSama

README.md

@@ -5,38 +5,62 @@
 
 A type-safe fluent assertion library inspired by [Jest](https://jestjs.io/docs/expect) assertions and the popular [AssertJ](https://assertj.github.io/doc/).
 
-## Development
+## Install
+```
+npm install --save-dev @stackbuilders/assertive-ts
+```
+Or:
+```
+yarn add --dev @stackbuilders/assertive-ts
+```
 
-To setup your local environment follow the next steps.
+## Usage
 
-### Requirements
+Import the library in your test script:
+```typescript
+import { expect } from "@stackbuilders/assertive-ts"
+```
 
-* Latest [Yarn Classic](https://classic.yarnpkg.com)
-* NodeJS (Use version set on [.nvmrc](https://github.com/stackbuilders/assertive-ts/blob/master/.nvmrc))
+Use the `expect` function along with a "matcher" function on the value you want to assert:
+```typescript
+expect(sum(1, 2)).toBeEqual(3);
+```
 
-### Install dependencies
+To assert the opposite, just add `.not` before a matcher:
+```typescript
+expect(sum(1, 2)).not.toBeNull();
+```
 
-```console
-yarn install
+With `assertive-ts` you can use **fluent assertions**, which means you can chain multiple matcher functions to the same value under test:
+```typescript
+expect("assertive-ts is awesome!")
+  .toStartWith("assertive-ts")
+  .not.toContain("unsafe")
+  .toEndWith("awesome!");
 ```
 
-### Compile TS files
+The matcher functions depend on the type of the value on the `expect`. If you're using TypeScript, the compiler will let you know if something is not available for that assertion:
+```typescript
+// Boolean assertion
+expect(isEven(2)).toBeTrue();
 
-```console
-yarn compile
-```
+// String assertion
+expect("foobar").toStartWith("foo");
 
-### Lint code
+// Number assertion
+expect(sum(1, 2)).toBePositive();
 
-```console
-yarn lint
+expect(14).toEndWith("4");
+           ^ ? type error: `toEndWith` does not exist in `NumberAssertion`
 ```
 
-### Run tests
+For a list of all matchers and extended documentation, please refer to the API documentation.
+
+## Test Runner Integration
+
+- [Jest Integration](docs/jest-tutorial.md)
+- [Mocha Integration](docs/mocha-tutorial.md)
 
-```console
-yarn test
-```
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

docs/development.md

@@ -0,0 +1,32 @@
+## Development
+
+To setup your local environment follow the next steps.
+
+### Requirements
+
+* Latest [Yarn Classic](https://classic.yarnpkg.com)
+* NodeJS (Use version set on [.nvmrc](https://github.com/stackbuilders/assertive-ts/blob/master/.nvmrc))
+
+### Install dependencies
+
+```console
+yarn install
+```
+
+### Compile TS files
+
+```console
+yarn compile
+```
+
+### Lint code
+
+```console
+yarn lint
+```
+
+### Run tests
+
+```console
+yarn test
+```

docs/jest-tutorial.md

@@ -0,0 +1,66 @@
+# Usage with Jest
+
+Let's set up a project with Jest and assertive-ts to write our first assertion.
+
+First, let's install the dependencies:
+
+```
+npm install --save-dev typescript ts-jest jest @types/jest @stackbuilders/assertive-ts
+```
+
+This library is meant to be used with TypeScript, so to have better results we encourage you to use TypeScript in your project. 
+
+Let's create a `tsconfig.json` file:
+```
+npx tsc -init
+```
+
+Let's also create a jest configuration file at the root directory by running the following command:
+```
+npx ts-jest config:init
+```
+
+**For more information about Jest and its configuration please refer to the [official documentation](https://jestjs.io/docs/getting-started).**
+
+We are going to test a simple function:
+
+*src/mathUtils.ts*
+```typescript
+export const sum = (a: number, b: number): number => {
+  return a + b;
+}
+```
+
+Now let's write a test for that function. Make sure to import `expect` from the `@stackbuilders/assertive-ts` module:
+
+*tests/mathUtils.test.ts*
+```typescript
+import { expect } from "@stackbuilders/assertive-ts";
+import { sum } from "../src/mathUtils";
+
+describe("sum", () => {
+  it("adds two numbers", () => {
+    expect(sum(1, 2)).toBeEqual(3);
+  })
+});
+```
+
+And that's it! Now you can run your tests as usual with your test script.
+
+## Keeping Jest's `expect` function
+
+You might want to use the `expect` function from Jest along with assertive-ts assertions. There are a couple ways to achieve this:
+
+- Instead of importing `expect` from the `assertive-ts` module, you can import one of the available aliases: `assert` or `assertThat`:
+
+```typescript
+    import { expect } from "@jest/globals";
+    import { assert } from "@stackbuilders/assertive-ts";
+```
+
+- Or use an explicit import to rename the `expect` function from Jest to something like `jestExpect`:
+
+```typescript
+    import { expect as jestExpect } from "@jest/globals";
+    import { expect } from "@stackbuilders/assertive-ts";
+```

docs/mocha-tutorial.md

@@ -0,0 +1,57 @@
+# Usage with Mocha
+
+Let's set up a project with Mocha and assertive-ts.
+
+First, let's install the dependencies:
+```
+npm install --save-dev typescript mocha @types/mocha ts-node @stackbuilders/assertive-ts
+```
+
+This library is meant to be used with TypeScript, so to have better results we encourage you to use TypeScript in your project. 
+
+Let's create a `tsconfig.json` file:
+```
+npx tsc -init
+```
+
+Let's also create a Mocha configuration file:
+
+*.mocharc.json*
+```json
+{
+  "extension": ["ts"],
+  "spec": "tests/**/*.test.ts",
+  "require": [
+    "ts-node/register"
+  ]
+}
+```
+
+As the config includes the TypeScript transpilation hook `ts-node/register` it does not require pre-compilation before running.
+
+**For more information about Mocha configuration please refer to the [official documentation](https://mochajs.org/#configuring-mocha-nodejs)**
+
+We are going to test a simple function:
+
+*src/mathUtils.ts*
+```typescript
+export const sum = (a: number, b: number): number => {
+  return a + b;
+}
+```
+
+Now let's write a test for that function. Make sure to import `expect` from the `@stackbuilders/assertive-ts` module.
+
+*tests/mathUtils.test.ts*
+```typescript
+import { expect } from "@stackbuilders/assertive-ts";
+import { sum } from "../src/mathUtils";
+
+describe("sum", () => {
+  it("adds two numbers", () => {
+    expect(sum(1, 2)).toBeEqual(3);
+  })
+});
+```
+
+And that's it! Now you can run your tests as usual with your test script.