From 08bf6f63b8b3d4ad5c2790e1b8f41b4fd390f34b Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Thu, 20 Feb 2020 12:31:06 +0800 Subject: [PATCH] - Docs: Update testing info; update CHANGES - `editorconfig`: Use 4 spaces for Markdown - npm: Rename and group various development scripts --- .editorconfig | 3 + CHANGES.md | 12 +++- badges/tests-badge.svg | 2 +- docs/Contributing.md | 1 + docs/Testing.md | 154 +++++++++++++++++++++++++++++++++++++++-- package.json | 92 ++++++++++++++---------- 6 files changed, 220 insertions(+), 44 deletions(-) diff --git a/.editorconfig b/.editorconfig index ee4e61cb..0e0dc57d 100644 --- a/.editorconfig +++ b/.editorconfig @@ -14,3 +14,6 @@ trim_trailing_whitespace = true ; [app/public/css/**.styl] ; indent_style = tab ; indent_size = 2 + +[*.md] +indent_size = 4 diff --git a/CHANGES.md b/CHANGES.md index 1b0f3a3e..750ff4b3 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -29,6 +29,13 @@ - Fix: Redirect paths for imagelib redirect checks - Fix: Ensure `setupCurPrefs` is run (including when `source` or `url` is set within the URL) +- Fix: Pressing 'Ctrl+A' causes js error when canvas is empty (@cuixiping) +- Fix: Path element cannot be exported to PDF; export path with + holes to PDF; export path element to PDF, support more path + commands; #269 (@cuixiping) +- Fix: remove "null" attributes in svg source #76 (@cuixiping) +- Fix: A bug of `convertPath` function when converting H and V to + relative (@cuixiping) - Optimization: Remove unused `jquery-ui-1.8.custom.min.js` file - Optimization: Remove old build/tools closure/yuicompressor code - Optimization: Remove unmaintained chrome-app, firefox-extension, @@ -43,6 +50,7 @@ dev. packages are being bundled (added by `npm run copy`) for determining summary of all licenses including bundled). - Docs: Reprioritize `docs` in commit lists (prioritize user-facing) +- Docs: Update Pavol's email address (@prusnak) - Refactoring: Switch from `$.param.querystring` to `URL` - Refactoring: Ensure file-global jsdoc tags are at beginning of file - Refactoring: Move `build-html` to `build` directory @@ -61,7 +69,7 @@ approving storage - Testing: Produce mochawesome report - Testing: Cypress with multiple reporters in case we need -- Build: Update underscore copy +- Build: Update underscore and core-js-bundle copies - npm: Add `underscore` to copy script - npm: Make `copy`, `compress-images`, `start-embedded`, `build-docs-remove` scripts cross-platform; add `start-allow-origin` script @@ -72,7 +80,7 @@ building docs and instrumenting) - npm: Update scripts to reflect removal of `all_tests.html`; remove `browser-test` script -- npm: Rename `test-prep` to `prep` +- npm: Rename `test-prep` to `prep` and other misc. script naming changes - npm: Update `package-lock.json` - npm: Update devDeps, peerDeps diff --git a/badges/tests-badge.svg b/badges/tests-badge.svg index 8abe9ee8..e3f3172d 100644 --- a/badges/tests-badge.svg +++ b/badges/tests-badge.svg @@ -1 +1 @@ -TestsTests125/127125/127 \ No newline at end of file +TestsTests126/127126/127 \ No newline at end of file diff --git a/docs/Contributing.md b/docs/Contributing.md index 2c6cece0..3c4e9759 100644 --- a/docs/Contributing.md +++ b/docs/Contributing.md @@ -21,3 +21,4 @@ - `Testing:` - `Build: ` - `npm` - Updates to dependencies, npm version, etc. +1. See [`Testing.md`](./Testing.md) for other information helpful for contributing. diff --git a/docs/Testing.md b/docs/Testing.md index 54c0000d..2b687d47 100644 --- a/docs/Testing.md +++ b/docs/Testing.md @@ -1,11 +1,153 @@ # Testing -1. Ensure tests are passing via `npm test`. This will lint and build -files and run `/test/all_tests.html`. +## Building docs -1. Spot check extensions (until we have tests). The following URL includes all: +This may be useful during testing. Build through `npm run build-docs`. -http://localhost:8000/editor/svg-editor-es.html?extensions=ext-arrows.js,ext-closepath.js,ext-connector.js,ext-eyedropper.js,ext-foreignobject.js,ext-grid.js,ext-helloworld.js,ext-imagelib.js,ext-markers.js,ext-mathjax.js,ext-overview_window.js,ext-panning.js,ext-php_savefile.js,ext-polygon.js,ext-server_moinsave.js,ext-server_opensave.js,ext-shapes.js,ext-star.js,ext-storage.js,ext-webappfind.js,ext-xdomain-messaging.js +To start a server and open already built docs, use `npm run open-docs` (or +`npm run open-docs-no-start` if you already have a `start` process +running in another terminal tab). -1. Ensure both the ES6 Modules HTML file (`svg-editor-es.html`) and - regular file (`svg-editor.html`) are working. +Or to build *and* open the docs, use `npm run build-and-open-docs` (or +`npm run build-and-open-docs-no-start` if you already have a `start` process +running in another terminal tab). + +## Scripts for running after dependency changes + +1. Copying files. Some `devDependencies` are incorporated into the svgedit + repository (and npm package) so that Github or npm hosting services + can run (without needing to take the much heavier step of bundling all of + `node_modules`). + 1. `npm run copy` +1. Checking licenses - If updating a dependency or devDependency, + the project's aggregate license information might change. To get + this information updated, run: + 1. `npm run license-badges` (Which runs the following commands) + 1. `npm run license-badge` (Only build the license badge containing + info on this project's license(s) and those of any `dependencies`, + and the `devDependencies` which are being bundled into the + repository/npm package.) + 1. `npm run license-badge-dev` (Only build the license badge for this + project's `devDependencies`. This is probably not of great concern + unless a project is restrictive in terms of usage--i.e., if a + dependency is not what is typically considered "open" source.) + +(Note that the test and coverage badges are generated automatically during +testing to ensure they are up to date, so you should not need to call those +scripts directly.) + +## Miscellaneous scripts + +1. `npm run compress-images` - Compressing images is not part of other + preparation routines, as it is time-consuming and should not need + to be done frequently. +1. `npm run remark` - For linting Markdown. Not of high enough priority + currently to put into an automated routine. +1. `npm run eslint` and `npm run eslint-fix` - For linting (or fixing) + linting errors. The non-fix version will be run automatically during + testing. +1. `npm run prep` - Run during `npm test` but may be useful to run + `npm run prep` as needed if normally testing through + `npm run test-only` which doesn't do the preparation. Composed of: + 1. `npm run prep-no-core-rollup` + 1. `npm run eslint` (see above) + 1. `npm run build-html` - Copies ESM HTML pages, replacing references + to ESM scripts to compiled/rolled up scripts. + 1. `npm run build-by-config` - Runs the Rollup routines for + compiling just the ESM-based config files (since the user + config files are responsible for importing svgedit, one must + compile these to get a non-ESM build, but with the advantage + of avoiding globals and extra script tags). + 1. `npm run rollup` - Runs the rollup routine for compiling the ESM-based + svgedit source files. + +## Opening SVG editor from command line + +It can be helpful to experiment with an editor by opening it from the command +line, even when automated tests already exist for a type of editor. + +1. Opening the ESM editor with only the default extensions: + 1. `npm run open` OR + 1. `npm run open-no-start` if you already have a `start` + process running in another terminal tab. +1. Opening the ESM editor with all extensions (no automated tests currently): + 1. `npm run open-all-ext` OR + 1. `npm run open-all-ext-no-start` if you already have a `start` + process running in another terminal tab. +1. Opening an embedded (ESM) editor (no automated tests currently) (Note + that there is currently no build process for creating a non-ESM + embedded editor). + 1. `npm run open-embedded` (This runs the normal `start` and also + `start-allow-origin` for running a separate server on a different + origin (a different port) so the embedded API can be tested + across origins.) OR + 1. `npm run open-embedded-no-start` if you already have a `start` + process running in another terminal tab. +1. Opening an editor which is already pre-compiled (rolled up) and safe + for older non-ESM browsers (or for better performance in ESM browsers + as well, due to its use of fewer HTTP requests). This is the version + most likely to be used in production environments. However, this is + less convenient during normal debugging, as it requires that the + lengthier `prep` script be run first (these scripts do not do so + for you in case you are directly working on the compiled files, + though this is not recommended). + 1. `npm run open-compiled` OR + 1. `npm run open-compiled-no-start` if you already have a `start` + process running in another terminal tab. + +## Reading/Opening test coverage reports + +For testing coverage reports (see "Testing"), you can open the HTML-based +reports that are generated during the testing process (or when running +`npm run instrument` directly) from the command line into your +browser by the following commands: + +1. Reading reports from the command line + 1. `npm run report` (with some line numbers but not all lines as + with the HTML report) OR + 1. `npm run report-summary` (no line numbers--only a summary) +1. Opening HTML-based test coverage report (indicating coverage status + for all lines) + 1. `npm run open-cov` OR + 1. `npm run open-cov-no-start` if you already have a `start` + process running in another terminal tab. + +## Testing + +For ensuring tests are passing (and optionally checking coverage). + +You will most likely just need to use the top-level routines, but +the components are explained here for reference. + +1. `npm test`. Headless testing comprised of: + 1. `npm run instrument` - You can call this alone if you don't + actually wish to test but wish to get the files instrumented. + Should normally not be needed alone. + 1. `npm run test-no-cov` - You can run this alone if you have already + run `npm run instrument` upon making changes. Should normally + not be run alone. + 1. `npm run prep` (see above) + 1. `npm run test-only` - Includes a separate `report` step or + otherwise the tests will not show the results visibly on the + command line. This may be useful if you've instrumented and + run preparation steps after any code modifications, but just + need to re-run tests (e.g., if one did not complete them for + some reason). See also `test-no-cov-no-core-rollup`. + 1. `npm run test-only-no-report` - Should not be needed alone. + 1. `npm start` - Starts the server + 1. `npm run cypress:run` - Runs Cypress tests (`cypress run`). + `cypress:run` is made of subroutines which also merge + Mocha results (since Cypress produces separate files) + and updates the testing and coverage badges. + 1. `npm run report` (see above) +1. `npm run test-no-core-rollup` - This applies the same headless testing + steps as `npm test` minus the time-consuming `npm run rollup`. This + script may be useful if you are only modifying config files but not + svgedit core. + 1. `instrument` (see above) + 1. `npm run test-no-cov-no-core-rollup`. As with `test-no-cov` but no + `npm run rollup` routine (part of `prep`). +1. `open-tests` (also as `cypress:open`) + 1. `npm start` + 1. `cypress:open-no-start`. Runs `cypress open`, the headed mode. Useful + for testing single files with hot reloading. diff --git a/package.json b/package.json index 629318d2..197851b7 100644 --- a/package.json +++ b/package.json @@ -13,52 +13,74 @@ "node": ">=8.5.0" }, "scripts": { - "prepublishOnly": "npm run prep", - "open-allext-no-start": "open-cli http://localhost:8000/editor/svg-editor-es.html?extensions=ext-arrows.js,ext-closepath.js,ext-foreignobject.js,ext-helloworld.js,ext-mathjax.js,ext-php_savefile.js,ext-server_moinsave.js,ext-server_opensave.js,ext-webappfind.js,ext-xdomain-messaging.js", - "open-allext": "run-p start open-allext-no-start", - "open-no-start": "open-cli http://localhost:8000/editor/svg-editor-es.html", - "open": "run-p start open-no-start", + "start-allow-origin": "static -p 8001 -H '{\"Access-Control-Allow-Origin\": \"*\"}'", + "start-embedded": "run-p start start-allow-origin", + "start": "echo \"Open file, e.g., to http://localhost:8000/editor/svg-editor-es.html\" && static -p 8000", + + "open-docs-no-start": "open-cli http://localhost:8000/docs/jsdoc/", + "open-docs": "run-p start open-docs-no-start", + "build-docs-remove": "rimraf \"docs/jsdoc/*\"", "build-docs-create": "jsdoc --pedantic -c docs/jsdoc-config.js editor", "build-docs": "run-s -c build-docs-remove build-docs-create", - "open-docs-no-start": "open-cli http://localhost:8000/docs/jsdoc/", - "open-docs": "run-p start open-docs-no-start", - "build-html": "npx babel-node --plugins @babel/plugin-transform-modules-commonjs build/build-html.js", - "compress-images": "imageoptim \"editor/extensions/*.png\" \"editor/spinbtn/*.png\" \"editor/jgraduate/images/*.{png,gif}\" \"editor/images/*.png\"", - "copy": "copyfiles -f node_modules/load-stylesheets/dist/index-es.js editor/external/load-stylesheets && copyfiles -f node_modules/jamilih/dist/jml-es.js editor/external/jamilih && copyfiles -f node_modules/query-result/esm/index.js editor/external/query-result/esm && copyfiles -f node_modules/qr-manipulation/dist/index-es.js editor/external/qr-manipulation/dist && copyfiles -f node_modules/stackblur-canvas/dist/stackblur-es.js editor/external/stackblur-canvas/dist && copyfiles -f node_modules/regenerator-runtime/runtime.js editor/external/regenerator-runtime && copyfiles -f \"node_modules/core-js-bundle//minified*\" editor/external/core-js-bundle && copyfiles -f \"node_modules/underscore/underscore-*\" editor/jspdf && copyfiles -f \"node_modules/deparam/dist/deparam.esm.js\" editor/external/deparam", - "remark": "remark -q -f .", - "eslint-fix": "eslint --fix --ext js,md,html .", - "eslint": "eslint --ext js,md,html .", - "rollup": "rollup -c", - "start-allow-origin": "static -p 8001 -H '{\"Access-Control-Allow-Origin\": \"*\"}'", - "start-embedded": "echo \"Open file to http://localhost:8000/editor/embedapi.html\" && run-p start start-allow-origin", - "start": "echo \"Open file, e.g., to http://localhost:8000/editor/svg-editor-es.html\" && static -p 8000", - "cypress:open": "cypress open", - "cypress:merge": "mochawesome-merge \"cypress/results/mochaw*.json\" > mochawesome.json && marge mochawesome.json && mbg --file ./mochawesome.json --badge_output badges/tests-badge.svg", - "cypress:run-only": "rimraf \"cypress/results/mochaw*.json\" && rimraf \".nyc_output/*\" && cypress run", - "cypress:run-no-badge": "run-s -c cypress:run-only cypress:merge", - "cypress:run": "run-s -c cypress:run-no-badge coverage-badge", - "open-report-no-start": "open-cli http://localhost:8000/coverage/", - "open-report": "run-p start open-report-no-start", - "start-open-report": "run-p start open-report", + "build-and-open-docs-no-start": "run-s build-docs open-docs-no-start", + "build-and-open-docs": "run-s build-docs open-docs", + + "open-embedded-no-start": "open-cli http://localhost:8000/editor/embedapi.html", + "open-embedded": "run-p start-embedded open-embedded-no-start", + "open-all-ext-no-start": "open-cli http://localhost:8000/editor/svg-editor-es.html?extensions=ext-arrows.js,ext-closepath.js,ext-foreignobject.js,ext-helloworld.js,ext-mathjax.js,ext-php_savefile.js,ext-server_moinsave.js,ext-server_opensave.js,ext-webappfind.js,ext-xdomain-messaging.js", + "open-all-ext": "run-p start open-all-ext-no-start", + "open-compiled-no-start": "open-cli http://localhost:8000/editor/svg-editor.html", + "open-compiled": "run-p start open-compiled-no-start", + "open-no-start": "open-cli http://localhost:8000/editor/svg-editor-es.html", + "open": "run-p start open-no-start", + + "open-cov-no-start": "open-cli http://localhost:8000/coverage/", + "open-cov": "run-p start open-cov-no-start", + "instrument:replace-html": "frs-replace \"../svgedit-config-es.js\" \"svgedit-config-es.js\" -i instrumented/svg-editor-es.html -o instrumented/svg-editor-es.html", "instrument:replace-js": "frs-replace \"editor/svg-editor.js\" \"svg-editor.js\" -i svgedit-config-es.js -o instrumented/svgedit-config-es.js", "instrument:copy-excluded": "node cypress/support/copy.js", "copy-instrumented": "copyfiles -e \"**/*.js\" -u 1 \"editor/**/*\" instrumented && npm run instrument:replace-html && npm run instrument:replace-js && npm run instrument:copy-excluded", - "instrument": "rimraf instrumented && npx nyc instrument editor instrumented && npm run copy-instrumented", + "instrument": "rimraf instrumented && nyc instrument editor instrumented && npm run copy-instrumented", + + "report": "nyc report", + "report-summary": "nyc report --reporter=text-summary", + "license-badge": "license-badger --uncategorizedLicenseTemplate \"\\${license} (\\${name} (\\${version}))\" --filteredTypes=nonempty --textTemplate \"License types\n(project, deps, and bundled devDeps)\" --packageJson --production badges/licenses-badge.svg", "license-badge-dev": "license-badger --corrections --filteredTypes=nonempty --textTemplate \"License types\n(all devDeps)\" --allDevelopment badges/licenses-badge-dev.svg", + "license-badges": "run-p license-badge license-badge-dev", "coverage-badge": "coveradge badges/coverage-badge", - "open-cov": "run-p --race start cypress:open", - "open-tests": "run-p start cypress:open", - "report": "npx nyc report", - "report-summary": "npx nyc report --reporter=text-summary", + + "compress-images": "imageoptim \"editor/extensions/*.png\" \"editor/spinbtn/*.png\" \"editor/jgraduate/images/*.{png,gif}\" \"editor/images/*.png\"", + "copy": "copyfiles -f node_modules/load-stylesheets/dist/index-es.js editor/external/load-stylesheets && copyfiles -f node_modules/jamilih/dist/jml-es.js editor/external/jamilih && copyfiles -f node_modules/query-result/esm/index.js editor/external/query-result/esm && copyfiles -f node_modules/qr-manipulation/dist/index-es.js editor/external/qr-manipulation/dist && copyfiles -f node_modules/stackblur-canvas/dist/stackblur-es.js editor/external/stackblur-canvas/dist && copyfiles -f node_modules/regenerator-runtime/runtime.js editor/external/regenerator-runtime && copyfiles -f \"node_modules/core-js-bundle//minified*\" editor/external/core-js-bundle && copyfiles -f \"node_modules/underscore/underscore-*\" editor/jspdf && copyfiles -f \"node_modules/deparam/dist/deparam.esm.js\" editor/external/deparam", + "remark": "remark -q -f .", + + "build-html": "babel-node --plugins @babel/plugin-transform-modules-commonjs build/build-html.js", + "eslint-fix": "eslint --fix --ext js,md,html .", + "eslint": "eslint --ext js,md,html .", + "rollup": "rollup -c", + "build-by-config": "rollup -c rollup-config.config.js", - "test-cov-open": "run-p --race start cypress:run", - "test-cov": "run-s -c instrument test-cov-open report-summary", - "test-no-build": "run-s eslint build-html build-by-config && npm test", - "prep": "run-s eslint build-html rollup build-by-config", - "test": "run-p start cypress:run" + "prep-no-core-rollup": "run-s eslint build-html build-by-config", + "prep": "run-s prep-no-core-rollup rollup", + "prepublishOnly": "npm run prep", + + "cypress:open-no-start": "cypress open", + "cypress:open": "run-p start cypress:open-no-start", + "open-tests": "npm run cypress:open", + + "cypress:merge": "mochawesome-merge \"cypress/results/mochaw*.json\" > mochawesome.json && marge mochawesome.json && mbg --file ./mochawesome.json --badge_output badges/tests-badge.svg", + "cypress:run-only": "rimraf \"cypress/results/mochaw*.json\" && rimraf \".nyc_output/*\" && cypress run", + "cypress:run-no-badge": "run-s -c cypress:run-only cypress:merge", + "cypress:run": "run-s -c cypress:run-no-badge coverage-badge", + "test-only-no-report": "run-p start cypress:run", + + "test-only": "run-s -c test-only-no-report report", + "test-no-cov-no-core-rollup": "run-s prep-no-core-rollup test-only", + "test-no-cov": "run-s prep test-only", + "test-no-core-rollup": "run-s instrument test-no-cov-no-core-rollup", + "test": "run-s instrument test-no-cov" }, "nyc": { "exclude": [