Skip to content

Latest commit

 

History

History
66 lines (45 loc) · 6.21 KB

DEVELOPER.md

File metadata and controls

66 lines (45 loc) · 6.21 KB

Building, Testing, and Publishing Angular.io Documentation Utilities

Overview

The project is mainly written in TypeScript. Webpack is used for bundling. Jasmine is used for running the tests. Node.js/npm are used for managing dependencies and running scripts (for building, testing, publishing, etc.).

Since this is a VSCode extension, there are some VSCode tasks and launch configurations, that can be used for running tests and debugging.

Npm scripts

Here is a list of npm scripts, that can be used for building and testing the project locally:

  • npm run build: Compile the source code (including tests), using the Webpack.

  • npm run build-prod: Compile the source code (including tests) in production mode (producing more optimized code).

  • npm run build-watch: Watch the source code (including tests) and re-build whenever something changes.

  • npm run lint: Lint the source code (including tests, infrastructure, configs, etc.), using tools such as ESLint, the TypeScript compiler and custom Node.js scripts.

  • npm run test-unit: Run unit tests.

  • npm run test-e2e [-- <version>]: Run e2e tests against the specified VSCode version (or the minimum supported version, if <version> is not specified). Possible values for <version> are: insiders, min-supported, stable or <X>.<Y>.<Z>
    (Note about e2e testing and note about testing for the web.)

  • npm run test/npm test: Lint the source code and run unit and e2e tests.

  • npm run test-all-versions: Same as npm test, but runs e2e tests against both the minimum supported and the latest available version.

  • npm run dev: Watch the source code (including tests) and re-build and run unit tests whenever something changes. Useful during development.

The following npm scripts can be used for packaging and publishing a new version of the extension to the VSCode marketplace. Publishing can only be performed by project maintainers (with publish rights).

  • npm run release [-- <patch|minor|major>]: Run all tests, increment version to the next patch/minor/major version (defaults to patch), create and tag a commit, and push the changes to GitHub. (Beware of this e2e testing limitation.)
  • npm run vsce-package: Package the current code into a .vsix file. These files can be used for offline installation, privately sharing the extension, or manually publishing a new version.
  • npm run vsce-publish [-- --pat <PAT>]: Publish the current code of the extension as a new version. Publishing requires authentication, e.g. by passing a VSTS Personal Access Token (PAT). See here for more details.

Normally, the tasks of packaging, creating GitHub releases, and publishing to the marketplace are handled automatically on CI (see the Deploy stage in .azure-pipelines/config.yml for more info). Project maintainers only have to create and push a tagged commit, e.g. using the release npm script.

This extension is published under the gkalpak Azure DevOps organization as publisher gkalpak.

For a full list of available npm scripts, see package.json.

VSCode tasks

Here is a list of VSCode tasks (defined in tasks.json), that can be useful during local development:

  • npm: build: Run npm build.
  • npm: build-prod: Run npm build-prod.
  • npm: build-watch: Run npm build-watch.

VSCode launch configurations

Here is a list of VSCode launch configurations (defined in launch.json), that can be useful during local development:

  • Extension: Launch a new VSCode instance with the extension loaded.
  • Extension (web): Launch a new VSCode instance with the extension loaded but using a web extension host.
    (Note about testing for the web.)
  • Extension Tests (unit) - DEBUG: Run the unit tests in "debug" mode. Useful for debugging unexpectedly failing tests.
  • Extension Tests (e2e): Launch a new VSCode instance with the extension loaded and run the e2e tests against that.
    (Note about e2e testing.)

Note about e2e testing
Due to a VSCode limitation, depending on your VSCode version and/or installation mode (global vs per user), it might not be possible to run the extension e2e tests from the command line (via npm run test-e2e), if another instance of VSCode is already running. If that is the case, either close all instances of VSCode first, use the relevant launch configuration from an already running VSCode instance, or run the tests on a different VSCode version (via npm run test-e2e -- <some-version>).

Note about testing for the web
Due to the complexity of running in-browser tests and the low impact (given that there are currently no e2e tests), there are not automated tests that run in a browser environment. For the time being, the extension can be manually tested using the Extension (web) launch configuration.
(Also, keep in mind that there is currently an issue with contributed markdown-it plugins: microsoft/vscode#133399)