@mohalla-tech/doc-coverage
v1.1.5
Published
custom scripts for web
Downloads
88
Maintainers
Keywords
Readme
Documentation Coverage Plugin
Node Version required: 14 or above
Install
1. npm i doc-coverage
2. Create a .doccoverage.json file in the root of the project.
3. For help on the config file created in step 5, refer 'Config Help' section
4. Run the command "./node_modules/.bin/doc" in the terminal in root directory to get coverage.
5. A folder called doc-coverage is created in the root. It contains a detailed coverage report.
Config Help
Config refers to the json that need to be added in .doccoverage.json file. Following are the available keys with description.
1. source - Path to the source folder.
2. excludedPaths - Array of Path regex to be ignored while calculating Coverage of the pure JS Files.
3. excludedComponentPaths - Array of Path regex to be ignored while calculating Component File Coverage(inside components folder).
* Example - if only index files are to be considered for stories, add "^((?!index.js).)*$" in the array. This ignores all files except index.
4. foldersWithComponentFiles - Array of folder names containing all UI components.
5. storiesFolderPath - Path to the stories folder to be provided if it is outside the source folder.
6. ecmaVersion - ECMA Script Version (required for parsing into ast), by default latest is used.
7. framework - framework used (currently react, vue and svelte are supported), by default react.
Ignore a Component File
If a particular Component file is to be ignored and a genric path regex to exclude cannot be created -
Add '/* !Doc Coverage Ignore */' as the first line in the file.
Example of a situation when one might need to ignore a file -
A small Component file with no props, for which niether storybook nor proptype is required.
Sample Config
{
"source": "./src",
"excludedPaths": ["/assets/", "/components/","/containers/", "/__test__/", "/config./"],
"excludedComponentPaths": ["/__test__/", "^((?!index.js).)*$"],
"foldersWithComponentFiles": ["components", "containers"],
"framework": "svelte",
"storiesFolderPath": "./stories"
}
Default Config
If no config is provided, the following is used as the default config
{
source: './src',
excludedPaths: [
'/assets/',
'/components/',
'/containers/',
'/__test__/',
'/config./',
'__snapshots__',
],
excludedComponentPaths: ['/__test__/'],
foldersWithComponentFiles: ['components', 'containers'],
storiesFolderPath: './stories',
}
Results Summary in console
Refer the following image link for example.
https://user-images.githubusercontent.com/92925973/142974147-12e32043-8102-4b81-914b-0a1ae5b7b3c8.png
We get 3 tables in the console -
1. JS Files Coverage - For Non Component files. The script looks for leading documentation comments for all top level blocks of a file.
( 1 scope = 1 top level block/function )
2. Component File Coverage - A Component File is considered fully documented if it is either imported in atleast one '.stories' file or has prop types defined.
We get 3 scores in this table -
1. Fully Covered Components - Fully documented Components / Total Components
2. Storybook Coverage - Components with stories / Total Components
3. PropTypes Coverage - Num of prop types / Total Props
3. Total Coverage - Combined Score of JS Files and each of the three Component Scores.
Detailed Coverage Report
A file called docCoverageReport.json is created under a directory called doc-coverage which contains the file wise coverage.
Apart from giving the same information as the tables in console it has 2 extra keys -
1. fileWiseCoverageJSFiles - Object with file path as the key.
Example:
"path-to-app/src/app.js": {
"funcCoverage": {
"urlB64ToUint8Array": false,
"onMessageReceivedSubscriptionState": true,
"onMessageReceivedSubscribe": true,
"onMessageReceivedUnsubscribe": true,
"broadcastReply": true,
"persistSubscriptionLocally": true
},
"fileCoverage": "83.33%"
},
2. fileWiseCoverageJSX/fileWiseCoverageVue/fileWiseCoverageSvelte - Object with file path as the key.
Example:
"path-to-app/src/index.js": {
"hasStory": false,
"hasAllPropTypes": false,
"componentType": "Functional",
"missingPropTypes": [
"error",
"timedOut",
"pastDelay"
],
"coverage": "25%"
}
Important Note
To get an accurate proptypes coverage, destructure the props.
Currently this syntax is not identified by the parser => {props.something}.
Instead use the following syntax
const {x,y,z} = props;