From 3f69de503615fd102b627fcd488f08b18a95d51c Mon Sep 17 00:00:00 2001 From: ylemkimon Date: Mon, 12 Feb 2018 06:11:59 +0900 Subject: [PATCH] Update NPM scripts and documentation (#1146) * Group more test npm scripts into `test:` * Update documentations on the development workflow * Update .travis.yml to match updated NPM scripts * Run npm install in Travis --- .travis.yml | 6 ++++-- CONTRIBUTING.md | 23 +++++++++++++++++++++-- dockers/Screenshotter/README.md | 16 ++++++++++++---- package.json | 14 +++++++------- 4 files changed, 44 insertions(+), 15 deletions(-) diff --git a/.travis.yml b/.travis.yml index e5c46123..896bb456 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,8 +12,10 @@ before_script: - docker pull selenium/standalone-chrome:2.48.2 - docker images --no-trunc install: + - npm install + - npm ls || true - npm install -g codecov script: - npm test - - npm run coverage && codecov - - dockers/Screenshotter/screenshotter.sh --verify + - npm run test:jest:coverage && codecov + - npm run test:screenshots diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b7e3f1f..a8e5eb2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ your symbol in TeX surrounded by other different kinds of symbols, and seeing whether your spacing matches the spacing that TeX produces. Once your symbol works, check the JavaScript console to make sure you don't get -a message like "Can't find character metrics for _" when you render your symbol. +a message like "Can't find character metrics for \_" when you render your symbol. If you do, check out [extract_ttfs.py](metrics/extract_ttfs.py). #### Adding new functions @@ -87,6 +87,12 @@ tests when you submit a pull request, in case you forget. If you make any changes to Parser.js, add Jest tests to ensure they work. +Some tests verify the structure of the output tree using [snapshot testing](https://facebook.github.io/jest/docs/en/snapshot-testing.html). +Those snapshots can be updated by running `npm run test:jest:update`. + +Also, test code coverage can be collected by `npm run test:jest:coverage`. +You can view the report in `coverage/lcov-report/index.html`. + #### Screenshot tests To ensure the final output looks good, we screenshot different expressions. @@ -117,6 +123,11 @@ is hard to test new changes in many browsers. If you can, please test your changes in as many browsers as possible. In particular, if you make CSS changes, try to test in IE 9, using [modern.ie](http://modern.ie) VMs. +## Building + +KaTeX is built using webpack with configuration `webpack.config.js`. Run +`npm run build` to build the project. + ## Style guide Code @@ -130,6 +141,13 @@ Code In general, try to make your code blend in with the surrounding code. +The code can be linted by running `npm run test:lint`, which lints JavaScript +files using ESLint and stylesheets using stylelint. They must pass to commit +the changes. + +Some files have flowtype annotations and can be checked for type errors using +Flow by running `npm run test:flow`. See [Flow](https://flow.org/) for more details. + ## Pull Requests - link back to the original issue(s) whenever possible @@ -137,7 +155,7 @@ In general, try to make your code blend in with the surrounding code. - commits should be squashed before merging - large pull requests should be broken into separate pull requests (or multiple logically cohesive commits), if possible - ## Working with submodules +## Working with submodules The fonts for KaTeX live in a submodule which appears in submodules/katex-fonts. Most of the time you won't have to worry about this unless you're making @@ -160,6 +178,7 @@ about how to use git submodules see https://chrisjean.com/git-submodules-adding- When submitting pull requests, that update katex-fonts, you'll need to submit two pull requests: one for [KaTeX/katex-fonts](https:/github.com/KaTeX/katex-fonts) and one for [Khan/KaTeX](https://github.com/Khan/KaTeX). + ## CLA In order to contribute to KaTeX, you must first sign the CLA, found at www.khanacademy.org/r/cla diff --git a/dockers/Screenshotter/README.md b/dockers/Screenshotter/README.md index a4de12b7..217c7e0a 100644 --- a/dockers/Screenshotter/README.md +++ b/dockers/Screenshotter/README.md @@ -1,15 +1,14 @@ # How to generate screenshotter images -## Automatic generation of screen shots +## Automatic generation of screenshots Now you too can generate screenshots from your own computer, and (hopefully) have them look mostly the same as the current ones! Make sure you have docker installed and running. If all you want is (re)create -all the snapshots for all the browsers, then you can do so by running the -`screenshotter.sh` script: +all the snapshots for all the browsers, then you can do so by: - dockers/Screenshotter/screenshotter.sh + npm run test:screenshots:update It will fetch all required selenium docker images, and use them to take screenshots. @@ -61,3 +60,12 @@ Examples: node dockers/Screenshotter/screenshotter.js -i Sqrt,SqrtRoot dockers/Screenshotter/screenshotter.sh --exclude=GreekLetters + +# How to run screenshotter tests + +You can verify screenshots by running: + + npm run test:screenshots + +or passing `--verify` option to `screenshotter.js` or `screenshotter.sh`. +See above for more details. diff --git a/package.json b/package.json index 82a4a514..439ef13d 100644 --- a/package.json +++ b/package.json @@ -60,21 +60,21 @@ "test:lint": "eslint katex.js katex.webpack.js cli.js webpack.common.js webpack.config.js webpack.dev.js src static test contrib dockers && stylelint src/katex.less", "test:flow": "flow", "test:jest": "jest", - "jest-update": "jest --updateSnapshot", - "coverage": "jest --coverage", + "test:jest:update": "jest --updateSnapshot", + "test:jest:coverage": "jest --coverage", + "test:screenshots": "npm run test:screenshots:update -- --verify", + "test:screenshots:update": "npm run prestart && dockers/Screenshotter/screenshotter.sh", + "test:perf": "npm run prestart && NODE_ENV=test node test/perf-test.js", "clean": "rm -rf build/* node_modules/", "clean-install": "npm run clean && npm i", - "screenshots": "npm run prestart && dockers/Screenshotter/screenshotter.sh", - "verify-screenshots": "npm run screenshots -- --verify", "prestart": "node check-node-version.js && check-dependencies && cd src && node unicodeMake.js >unicodeSymbols.js", "start": "webpack-dev-server --hot --config webpack.dev.js", "build": "npm run prestart && rimraf build/* && webpack", + "watch": "npm run build -- --watch", "dist": "npm test && npm run build && npm run dist:copy && npm run dist:zip && npm run dist:dist", "dist:copy": "cd build && mkdirp katex && cp -r katex.js katex.min.js katex.css katex.min.css contrib fonts ../README.md katex", "dist:zip": "cd build && tar czf katex.tar.gz katex/ && zip -rq katex.zip katex/", - "dist:dist": "rimraf dist/ && cp -r build/katex/ dist/", - "watch": "npm run build -- --watch", - "perf-test": "npm run prestart && NODE_ENV=test node test/perf-test.js" + "dist:dist": "rimraf dist/ && cp -r build/katex/ dist/" }, "pre-commit": [ "test:lint"