Skip to content

Commit

Permalink
Move from yarn to npm
Browse files Browse the repository at this point in the history
  • Loading branch information
domenic committed Nov 26, 2023
1 parent 9b354af commit 7027a3d
Show file tree
Hide file tree
Showing 6 changed files with 2,513 additions and 1,463 deletions.
12 changes: 6 additions & 6 deletions .github/workflows/jsdom-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ jobs:
with:
node-version: '20'
- name: Install dependencies
run: yarn --frozen-lockfile
run: npm ci
- name: Run syntax rules check with ESLint
run: yarn lint
run: npm run lint
build-with-canvas:
name: Tests with node-canvas
env:
Expand All @@ -41,9 +41,9 @@ jobs:
- name: Setup HOSTS file for Web Platform Test server
run: ./test/web-platform-tests/tests/wpt make-hosts-file | sudo tee -a /etc/hosts
- name: Install dependencies
run: yarn --frozen-lockfile
run: npm ci
- name: Run tests
run: yarn add canvas && yarn test --retries 1
run: npm install canvas && npm test -- --retries 1
build:
name: Tests
runs-on: ubuntu-latest
Expand All @@ -64,6 +64,6 @@ jobs:
- name: Setup HOSTS file for Web Platform Test server
run: ./test/web-platform-tests/tests/wpt make-hosts-file | sudo tee -a /etc/hosts
- name: Install dependencies
run: yarn --frozen-lockfile
run: npm ci
- name: Run tests
run: yarn test --retries 1
run: npm run test -- --retries 1
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
gmon.out
v8.log
node_modules
package-lock.json
test/worker-bundle.js
test/web-platform-tests/tuwpt-manifest.json
npm-debug.log*
Expand Down
34 changes: 14 additions & 20 deletions Contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,6 @@

jsdom is, as said in our tagline, “A JavaScript implementation of the DOM and HTML standards.” Anything that helps us be better at that is welcome.

## Yarn

We use the [Yarn](https://yarnpkg.com/) package manager to manage dependencies and run the scripts defined in `package.json`. It is similar to npm, but contains fewer bugs for our purposes. If you make changes which add or remove dependencies, make sure you commit the `yarn.lock` file which it generates.

You can probably get away with using npm for most contributions, as long as you are not adding or removing dependencies. You'll have to mentally translate the Yarn commands we give into npm ones, however.

## Architecture

jsdom is a blend of old and new code. Some of its older and less-touched corners may look different from newer work. Here we'll describe the modern setup, but you might encounter parts of the codebase that don't fit this model, or that seem unnecessarily baroque (like the directory structure in `lib/`).
Expand All @@ -20,7 +14,7 @@ As such, most web platform classes present in jsdom are implemented in two parts

- An implementation file, such as [`Attr-impl.js`](lib/jsdom/living/attributes/Attr-impl.js), containing the relevant implementation logic

Our build step (`yarn prepare`) then generates a public API file (e.g. `Attr.js`) which takes care of all the Web IDL-derived boilerplate, delegating to the implementation file for the important stuff. We then wire it together with a line in [`lib/jsdom/living/interfaces.js`](lib/jsdom/living/interfaces.js) that exposes the generated class on all jsdom windows.
Our build step (`npm run prepare`) then generates a public API file (e.g. `Attr.js`) which takes care of all the Web IDL-derived boilerplate, delegating to the implementation file for the important stuff. We then wire it together with a line in [`lib/jsdom/living/interfaces.js`](lib/jsdom/living/interfaces.js) that exposes the generated class on all jsdom windows.

## Contribution overview

Expand All @@ -40,49 +34,49 @@ Other specs might pop up from time to time, especially in regard to CSS stuff. I

### Running the tests

First you'll want to run `yarn` to install all dependencies. Then, configure your system to run the web platform tests as described in [their README](https://github.com/web-platform-tests/wpt/blob/master/README.md).
First you'll want to run `npm install` to install all dependencies. Then, configure your system to run the web platform tests as described in [their README](https://github.com/web-platform-tests/wpt/blob/master/README.md).

**To run all the tests:** `yarn test`
**To run all the tests:** `npm test`

In the following sections, we'll give commands for running a subset of the tests. If you do that, instead of running the whole suite with `yarn test`, then please run this command first:
In the following sections, we'll give commands for running a subset of the tests. If you do that, instead of running the whole suite with `npm test`, then please run this command first:

**Before running test subsets**: `yarn pretest`
**Before running test subsets**: `npm run pretest`

### Web platform feature tests

All tests for web platform features (as opposed to features of jsdom itself, such as the `JSDOM()` constructor) should be in [web-platform-tests](https://github.com/web-platform-tests/wpt) format. We have some infrastructure for running these directly against jsdom documents. So ideally, when contributing a bugfix or new feature, you can browse the web-platform-tests repository and find the test covering your work, and then just enable it in [the `to-run.yaml` file](https://github.com/jsdom/jsdom/blob/main/test/web-platform-tests/to-run.yaml). These tests are HTML files which use a special library called [testharness.js](https://web-platform-tests.org/writing-tests/testharness-api.html) to report their results.

However, the web-platform-tests project is not fully comprehensive. If you need to write your own test for a web platform feature, place it in our [to-upstream](https://github.com/jsdom/jsdom/tree/main/test/web-platform-tests/to-upstream) directory. (It's so named because, over time, we hope to upstream these tests back to the web-platform-tests repository, so all browsers can benefit from them.) Note that you may need to create new directory structure, paralleling that of the main [web-platform-tests](https://github.com/web-platform-tests/wpt) repository.

**To run all web-platform-tests:** `yarn test-wpt`
**To run all web-platform-tests:** `npm run test-wpt`

**To run the to-upstream web-platform-tests:** `yarn test-tuwpt`
**To run the to-upstream web-platform-tests:** `npm run test-tuwpt`

**To run specific web-platform-tests already enabled via `to-run.yaml`**: `yarn test-wpt --fgrep dom/events`
**To run specific web-platform-tests already enabled via `to-run.yaml`**: `npm run test-wpt -- --fgrep dom/events`

**To run specific to-upstream web-platform-tests**: `yarn test-tuwpt --fgrep domparsing`
**To run specific to-upstream web-platform-tests**: `npm run test-tuwpt -- --fgrep domparsing`

Also, to update web platform tests to their latest revision from the source repository: `yarn update-wpt`. (This can take a long time, like 10 minutes.)
Also, to update web platform tests to their latest revision from the source repository: `npm run update-wpt`. (This can take a long time, like 10 minutes.)

### jsdom API tests

If you are testing something that can only be accomplished through the jsdom API, and not inside a normal web browser, you'll want to write a different kind of test. Such tests are written using [Mocha](https://mochajs.org/) and [Chai](http://chaijs.com/).

To write such a test that, simply add a file in `test/api/`, following the surrounding conventions. Then, add it to the manifest at `test/index.js`.

**To run all API tests:** `yarn test-api`
**To run all API tests:** `npm run test-api`

**To run a specific API test:** `yarn test-mocha test/api/from-file.js`
**To run a specific API test:** `npm run test-mocha test/api/from-file.js`

### Older tests

Although ideally you should not need to worry about this, there are some tests that are for legacy reasons not in the right format; they use Mocha, but really should be web platform tests. We're keeping them around for coverage until we can convert them. If you run `yarn test`, you will get the full test suite, including such old tests.
Although ideally you should not need to worry about this, there are some tests that are for legacy reasons not in the right format; they use Mocha, but really should be web platform tests. We're keeping them around for coverage until we can convert them. If you run `npm test`, you will get the full test suite, including such old tests.

## Benchmarks

This project cares about performance. There are a number of benchmarks that you can run. If you suspect your contribution has an impact on the performance of existing functionality, make sure you run the benchmarks before and after your change so that you can compare.

**To run benchmarks:** `yarn benchmark`
**To run benchmarks:** `npm benchmark`

## Issues

Expand Down
Loading

0 comments on commit 7027a3d

Please sign in to comment.