added: test example

README.md

@@ -2198,6 +2198,16 @@ const report = await reader.read('report.json');
 
 ## Testing
 
+#### Goal
+
+Our goal is to aim for 80% test coverage.
+
+#### Examples
+
+Example of good and bad unit tests [here](./examples/unit-testing/)
+
+---
+
 Testing is more important than shipping. If you have no tests or an inadequate amount, then every time you ship code you won't be sure that you didn't break anything.
 Deciding on what constitutes an adequate amount is up to your team, but having 100% coverage (all statements and branches)
 is how you achieve very high confidence and developer peace of mind. This means that in addition to having a great testing framework, you also need to use a good [coverage tool](https://github.com/gotwarlost/istanbul).

examples/unit-testing/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+coverage

examples/unit-testing/jest.config.ts

@@ -0,0 +1,28 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  verbose: true,
+  // setupFiles: ['dotenv/config'],
+  roots: ['<rootDir>'],
+  preset: 'ts-jest',
+  transform: {
+    '^.+\\.(ts|tsx)?$': ['ts-jest', { tsconfig: 'tsconfig.json' }],
+  },
+
+  // Test File Settings
+  modulePathIgnorePatterns: ['lib', 'dist'],
+  testMatch: ['**/*.(unit|spec|test).(j|t)s'],
+
+  // Code Coverage Settings
+  collectCoverage: true,
+  collectCoverageFrom: [
+    'src/**/*.ts',
+
+    // Ignore Coverage For these Files
+    '!src/test/**/*.ts',
+  ],
+  coverageReporters: ['html', 'json', 'text'],
+  reporters: ['default'],
+};
+
+export default config;

examples/unit-testing/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "unit-testing",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^29.2.4",
+    "@types/node": "^18.11.13",
+    "jest": "^29.3.1",
+    "ts-jest": "^29.0.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.4"
+  }
+}

examples/unit-testing/src/example.ts

@@ -0,0 +1,43 @@
+export const asyncCall = async () => {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => resolve('this works as expected'), 1000);
+  })
+};
+
+export const asyncCallFailed = async (errMessage: string = 'this DID NOT work') => {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => reject(new Error(errMessage)), 1000);
+  })
+};
+
+
+export const catchErrMessage = async () => {
+  try {
+    await asyncCallFailed('Error has been caught and reported');
+  } catch (err) {
+    return err.message;
+  }
+}
+
+export const throwErr = async () => {
+  try {
+    await asyncCallFailed('Error has been caught and reported');
+  } catch (err) {
+    throw err;
+  }
+}
+
+export const catchErr = async () => {
+  await throwErr().catch();
+  return true;
+}
+
+export const catchErr2 = async () => {
+  throwErr().catch();
+  return true;
+}
+
+export const catchErr3 = () => {
+  throwErr().catch();
+  return true;
+}

examples/unit-testing/test/bad.test.ts

@@ -0,0 +1,6 @@
+describe('testing', () => { // non description describe block
+  it('should work', () => { // non description it/test block
+    expect(1 + 2).toBe(3);
+  });
+});
+

examples/unit-testing/test/example/asynCall.test.ts

@@ -0,0 +1,24 @@
+import { asyncCall, asyncCallFailed, catchErrMessage } from '../../src/example';
+
+describe('Name of the file being tested', () => {
+  it('should describe what is being tested. Optionally put in function/method name', () => {
+    expect(1 + 2).toBe(3)
+  })
+
+  it('should return a value from asyncCall', async () => {
+    const result = await asyncCall();
+    expect(result).toBe('this works as expected');
+  });
+
+  it('should throw error when calling asyncCallFailed', async () => {
+    expect(async () => await asyncCallFailed()).rejects.toThrowError('this DID NOT work');
+  });
+
+  describe('Handle errors', () => {
+    it('should catch error and return error message', async () => {
+      const errMessage = await catchErrMessage();
+      expect(errMessage).toBe('Error has been caught and reported');
+    });
+  })
+});
+

examples/unit-testing/test/example/catchErr.test.ts

@@ -0,0 +1,19 @@
+import { catchErr, catchErr2, catchErr3 } from '../../src/example';
+
+describe('catchErr', () => {
+  it('1', async () => {
+    const bool = await catchErr();
+    expect(bool).toBe(true);
+  });
+
+  it('2', async () => {
+    const bool = await catchErr2();
+    expect(bool).toBe(true);
+  });
+
+  it('3', () => {
+    const bool = catchErr3();
+    expect(bool).toBe(true);
+  });
+});
+

examples/unit-testing/test/example/jest-gotcha.test.ts

@@ -0,0 +1,12 @@
+import { readFileSync } from 'fs';
+
+describe('Error', () => {
+  it('an error must be of instance Error', () => {
+    try {
+      readFileSync('some file that does not exist');
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+    }
+  });
+});
+

examples/unit-testing/test/good.test.ts

@@ -0,0 +1,15 @@
+describe('Name of the file being tested', () => {
+  it('should describe what is being tested. Optionally put in function/method name', () => {
+    expect(1 + 2).toBe(3);
+  });
+
+  describe('Describing a group of tests handled under main describe block example: error handling', () => {
+    it('should catch error and return error message', async () => {
+      const err = () => {
+        throw Error();
+      }
+      expect(err).toThrowError();
+    });
+  });
+});
+

examples/unit-testing/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "diagnostics": true,
+    "skipLibCheck": true,
+    "module": "commonjs",
+    "target": "es2017",
+    "sourceMap": true,
+    "declaration": true,
+    "noImplicitAny": false,
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "strictNullChecks": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "types": [
+      "jest",
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "src/test/**/*"
+  ]
+}