Merge pull request #32 from nikitawootten-nist/nikitawootten-nist/iss…

…ue31

Create a `TESTING.md` document

.github/workflows/test.yaml

@@ -20,5 +20,5 @@ jobs:
         run: npm run build
       - name: Lint
         run: npm run lint
-      - name: Test
-        run: npm run test
+      - name: Test with Coverage
+        run: npm run test-coverage

TESTING.md

@@ -0,0 +1,74 @@
+# Testing
+
+## Local Testing
+
+### Lint
+
+To ensure that your changes are consistent with the project coding style, run `npm run lint`.
+This checks the repository against a variety of [ESLint](https://eslint.org/) rules, including (but not limited to):
+
+-   Consistent spacing and indentation
+-   The presence of the NIST license/distribution notice in all source files
+-   Anti-patterns such as unused symbols
+
+Some issues can be fixed automatically by running `npm run lint-fix`.
+
+The linter is invoked by GitHub Actions when a pull request is run via the [Lint and Test workflow](./.github/workflows/test.yaml).
+Lint checks must pass before a pull request can be merged.
+
+### Test
+
+Tests can be found along source code in files with the `.spec.` infix.
+To run all unit tests, run `npm run test`.
+A test coverage report can be generated by running `npm run coverage`.
+This project uses [Jest](https://jestjs.io/) to generate coverage reports.
+
+These tests are run by GitHub Actions when a pull request is run via the [Lint and Test workflow](./.github/workflows/test.yaml).
+Tests must pass before a pull request can be merged.
+
+This project is broken up into packages using [NPM Workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces).
+Packages can be tested independently using the syntax `npm run test -- packages/<package>`, where `<package>` is the name of the target package.
+This syntax can also be used to test explicit subsets or sub-folders of a package.
+
+## CI/CD
+
+### Testing and Evaluation
+
+**SA-11: Developer Security Testing And Evaluation**:
+The NIST ITL CSD developers that maintain the `metaschema-node` application system at all post-design stages of the system development life cycle:
+
+-   Perform unit and integration testing/evaluation for every commit in a development branch submitted for code review in the form of a pull request sent to the development team before merging it to the main release branch at the development team's recommended level of depth and coverage as described in the code coverage tool's configuration file [`jest.config.base.ts`](./jest.config.base.ts);
+-   Produce evidence of the execution of the assessment plan and the results of the testing and evaluation;
+-   Implement a verifiable flaw remediation process;
+-   Correct flaws identified during testing and evaluation
+    The required coverage is defined in this repository by the config file [`jest.config.base.ts`](./jest.config.base.ts).
+
+This check is performed by GitHub Actions via the [Lint and Test workflow](./.github/workflows/test.yaml) for all pull requests.
+
+#### Static Code Analysis
+
+**SA-11(02): Threat Modeling and Vulnerability Analysis**:
+The NIST ITL CSD developers that maintain `metaschema-node` are required to employ static code analysis tools to identify common flaws and document the results of the analysis.
+
+This check is performed by GitHub Actions via the [CodeQL Analysis workflow](./.github/workflows/codeql-analysis.yaml) as well as the linting portion of the [Lint and Test workflow](./.github/workflows/test.yaml).
+
+#### Vulnerability Analysis
+
+**SA-11(02): Threat and Vulnerability Analyses**:
+The NIST ITL CSD developers that maintain `metaschema-node` are required to perform vulnerability analyses during development and the subsequent testing and evaluation of the system that:
+
+-   Uses the following contextual information:
+    -   The library dependencies as defined in this project's lock file [`package-lock.json`](./package-lock.json);
+-   Employs the following tools and methods:
+    -   [Dependabot](https://github.com/dependabot);
+-   Produces evidence that meets the following acceptance criteria:
+    -   All project dependencies on the main branch, as well as dependencies on incoming pull requests, have no known applicable reported vulnerabilities;
+
+Vulnerability alerts are published to [this dashboard](https://github.com/usnistgov/metaschema-node/security/dependabot) and via email.
+
+#### Manual Code Reviews
+
+**SA-11(04): Manual Code Reviews**:
+The NIST ITL CSD developers that maintain `metaschema-node` are required to perform a manual code review of all incoming pull requests using the following processes, procedures, and/or techniques:
+
+-   Organization-defined members are required to provide a review before a pull request can be merged, as defined in the [`CODEOWNERS`](./.github/CODEOWNERS) file;

jest.config.base.ts

@@ -1,6 +1,18 @@
+import { Config } from 'jest';
+
 export default {
     clearMocks: true,
-    collectCoverage: true,
+    // override with --coverage flag when running jest
+    collectCoverage: false,
+    coverageDirectory: '<rootDir>/coverage',
+    coverageThreshold: {
+        global: {
+            branches: 80,
+            functions: 50,
+            lines: 80,
+            statements: 80,
+        },
+    },
     coverageProvider: 'v8',
     testEnvironment: 'node',
     // ts-jest doesn't support nodenext module resolution?
@@ -15,4 +27,4 @@ export default {
             tsconfig: '<rootDir>/tsconfig.json',
         },
     },
-};
+} as Config;

jest.config.ts

@@ -1,7 +1,8 @@
+import { Config } from 'jest';
+
 import base from './jest.config.base';
 
 export default {
     ...base,
-    coverageDirectory: '<rootDir>/coverage',
     projects: ['<rootDir>/packages/*/jest.config.ts'],
-};
+} as Config;

package.json

@@ -21,9 +21,11 @@
     "lint": "eslint .",
     "lint-fix": "eslint --fix .",
     "build": "lerna run build",
-    "test": "jest"
+    "test": "jest",
+    "test-coverage": "jest --coverage"
   },
   "workspaces": [
     "packages/*"
-  ]
+  ],
+  "license": "NIST-PD-fallback"
 }

packages/data-utils/jest.config.ts

@@ -1,6 +1,8 @@
+import { Config } from 'jest';
+
 import base from '../../jest.config.base';
 
 export default {
     ...base,
     displayName: 'metaschema-model',
-};
+} as Config;

packages/data-utils/package.json

@@ -7,8 +7,7 @@
         "email": "nikita.wootten@nist.gov"
     },
     "scripts": {
-        "build": "tsc -p tsconfig.build.json",
-        "test": "jest"
+        "build": "tsc -p tsconfig.build.json"
     },
     "exports": {
         "./lib": null,
@@ -26,4 +25,4 @@
         "@xmldom/xmldom": "^0.8.2",
         "fast-xml-parser": "^4.0.8"
     }
-}
+}

packages/metaschema-model-common/jest.config.ts

@@ -1,6 +1,8 @@
+import { Config } from 'jest';
+
 import base from '../../jest.config.base';
 
 export default {
     ...base,
     displayName: 'metaschema-model-common',
-};
+} as Config;

packages/metaschema-model/jest.config.ts

@@ -1,6 +1,8 @@
+import { Config } from 'jest';
+
 import base from '../../jest.config.base';
 
 export default {
     ...base,
     displayName: 'metaschema-model',
-};
+} as Config;

packages/metaschema-model/package.json

@@ -7,8 +7,7 @@
         "email": "nikita.wootten@nist.gov"
     },
     "scripts": {
-        "build": "tsc -p tsconfig.build.json",
-        "test": "jest"
+        "build": "tsc -p tsconfig.build.json"
     },
     "exports": {
         "./lib": null,

packages/metaschema-model/src/processing/enums.spec.ts

@@ -24,18 +24,32 @@
  * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
  */
 
-import { ModuleScope } from '@oscal/metaschema-model-common/util';
+import { JsonGroupAsBehavior, ModuleScope, XmlGroupAsBehavior } from '@oscal/metaschema-model-common/util';
 import { placeholderContext } from '../testUtil/index.js';
-import { processModuleScope } from './enums.js';
+import { processJsonGroupAsBehavior, processModuleScope, processXmlGroupAsBehavior } from './enums.js';
 
-describe('processModuleScope()', () => {
-    it('should process modules scope', () => {
+describe('enums', () => {
+    it('processModuleScope()', () => {
         expect(processModuleScope('local', placeholderContext)).toBe(ModuleScope.LOCAL);
         expect(processModuleScope('inherited', placeholderContext)).toBe(ModuleScope.INHERITED);
         expect(processModuleScope(null, placeholderContext)).toBe(ModuleScope.INHERITED);
+        expect(() => processModuleScope('invalid', placeholderContext)).toThrow();
     });
 
-    it('should throw on invalid module scope', () => {
-        expect(() => processModuleScope('invalid', placeholderContext)).toThrow();
+    it('processXmlGroupAsBehavior()', () => {
+        expect(processXmlGroupAsBehavior('WITH_WRAPPER', placeholderContext)).toBe(XmlGroupAsBehavior.GROUPED);
+        expect(processXmlGroupAsBehavior('UNWRAPPED', placeholderContext)).toBe(XmlGroupAsBehavior.UNGROUPED);
+        expect(() => processXmlGroupAsBehavior(null, placeholderContext)).toThrow();
+        expect(() => processXmlGroupAsBehavior('invalid', placeholderContext)).toThrow();
+    });
+
+    it('processJsonGroupAsBehavior()', () => {
+        expect(processJsonGroupAsBehavior('ARRAY', placeholderContext)).toBe(JsonGroupAsBehavior.LIST);
+        expect(processJsonGroupAsBehavior('SINGLETON_OR_ARRAY', placeholderContext)).toBe(
+            JsonGroupAsBehavior.SINGLETON_OR_LIST,
+        );
+        expect(processJsonGroupAsBehavior('BY_KEY', placeholderContext)).toBe(JsonGroupAsBehavior.KEYED);
+        expect(() => processJsonGroupAsBehavior(null, placeholderContext)).toThrow();
+        expect(() => processJsonGroupAsBehavior('invalid', placeholderContext)).toThrow();
     });
 });