zcy
/
svgedit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
svgedit/docs/Development.md

10 KiB
Raw Blame History

Development

Note that this document goes roughly in order of increasing importance. This is done so you can see what is available and also see what scripts may be automatically run as part of the later-mentioned items.

Installing/Updating releases

In order to allow old versions to be available along with the master version on our Github Pages-hosted repository, we have added old versions as submodules.

Most users will therefore not want to clone recursively, but for developing, at least publishing, this may be necessary.

  • npm run submodules
    • npm run submodules-init- This is a non-recursive init as we don't want the submodules themselves to have their own releases! (They will have releases with subfolders for versions, but no contents.)
    • npm run submodules-update - Fetches and merges non-recursively and merges any changes into master (e.g., if an unreleased version branch was first added but needed more added to it).

Building docs

Though the building of docs is automatically run before publishing, this may also be useful for reference during testing. Build through npm run build-docs.

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).

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
  2. 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.)
      2. 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.)

The above are run before publishing, but they should be checked whenever updating dependencies (npm-check-updates is recommended, especially as our repo is configured to ignore updating those packages which shouldn't be updated (see .ncurc.js)).

(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, and the license badges are updated before publishing.)

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.
  2. npm run remark - For linting Markdown. Not of high enough priority currently to put into an automated routine.
  3. npm run lint and npm run eslint-fix - For linting (or fixing) linting errors. The non-fix version will be run automatically during testing.
  4. 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 lint (see above)
      2. npm run build-html - Copies ESM HTML pages, replacing references to ESM scripts to compiled/rolled up scripts.
      3. 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).
    2. 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
    2. npm run open-no-start if you already have a start process running in another terminal tab.
  2. Opening the ESM editor with all extensions (no automated tests currently):
    1. npm run open-all-ext OR
    2. npm run open-all-ext-no-start if you already have a start process running in another terminal tab.
  3. 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
    2. npm run open-embedded-no-start if you already have a start process running in another terminal tab.
  4. 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
    2. 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 and coverage"), 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
    2. npm run report-summary (no line numbers--only a summary)
  2. Opening HTML-based test coverage report (indicating coverage status for all lines)
    1. npm run open-cov OR
    2. npm run open-cov-no-start if you already have a start process running in another terminal tab.

Testing and coverage

For ensuring tests are passing and checking coverage.

You will most likely just need to use one of these three top-level routines along with npm run test-only, but the other components are explained here for reference. The most useful for regular development testing will probably be npm run open-tests.

Note that you can configure Cypress through its environmental variables. We recommend this approach of adding to your own cypress.env.json at project root. You can set your own configuration options. Of particular interest may be setting "video": false if you wish to speed up the tests and are not concerned with being able to check this after running the headless tests (or during the running of headed tests in the case of open-tests/cypress:open).

  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.
    2. 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)
      2. npm run test-only - 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). Also should be useful if tests are only against the ESM builds (as is currently the case), and you therefore don't need prep (and you are not concerned at the moment with accurate coverage, so you can skip instrument). This script includes a separate report step or otherwise the tests will not show the results visibly on the command line. 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
          2. 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.
        2. npm run report (see above)
  2. 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)
    2. npm run test-no-cov-no-core-rollup. As with test-no-cov but no npm run rollup routine (part of prep).
  3. open-tests
    1. instrument (see above)
    2. cypress:open - Useful without instrument if you are not concerned at the moment with coverage. Note that the hot-reloading does not currently reinstrument even if you ran through open-tests.
      1. npm start
      2. cypress:open-no-start. Runs cypress open, the headed mode. Useful for testing single files with hot reloading.