Developing the Client¶
This section documents how to setup a development environment for the client, how to run the client and its tests in a development environment, client coding standards and how to contribute code to the client.
Setting up a Client Development Environment¶
To build the client for development:
git clone 'https://github.com/hypothesis/client.git' cd client make
You now have a development client built. To run your development client in a browser you’ll need a local copy of either the Hypothesis Chrome extension or h. Follow either Running the Client from the Browser Extension or Running the Client From h below. If you’re only interested in making changes to the client (and not to h) then running the client from the browser extension is easiest.
Running the Client from the Browser Extension¶
This is the currently easiest way to get your development client running in a browser. It sets you up to make changes to the client and to the Chrome extension itself, but not to h.
Check out the browser extension and follow the steps in the browser extension’s documentation to build the extension and configure it to use your local version of the client and the production Hypothesis service.
Start the client’s development server to rebuild the client whenever it changes:
After making changes to the client, you will need to run
makein the browser extension repo and reload the extension in Chrome to see changes. You can use Extensions Reloader to make this easier.
Running the Client From h¶
This takes longer to setup than Running the Client from the Browser Extension. You should follow these steps if you want to make changes to h as well as to the client.
First follow the instructions for setting up a development install of h. Then run both h and the client at the same time in different shells. In the client repository, run:
Then in a different shell, in the h repository, run:
You can also load the client into your own web pages by adding:
<script async src="http://localhost:5000/embed.js"></script>
to the page’s HTML. Note that this will only work in pages served via plain HTTP. If you want to test out the client on pages served via HTTPS then building the client into a browser extension is the easiest option.
Running the Tests¶
Hypothesis uses Karma and mocha for testing. To run all the tests once, run:
You can filter the tests which are run by running
make test ARGS='--grep <pattern>',
yarn test --grep <pattern>. Only test files matching the regex
To run tests and automatically re-run them whenever any source files change, run:
make test ARGS='--watch'
yarn test --watch
This command will also serve the tests on localhost (typically http://localhost:9876) so that break points can be set and the browser’s console can be used for interactive debugging.
Hypothesis uses ESLint (a linter) and Prettier (an automated code formatter) to ensure style consistency and help prevent common mistakes. Plugins are available for most editors for these tools. We recommend that you set these up before making changes to the code.
To auto-format code and run lint checks locally using the CLI, run:
make format make lint