Liking cljdoc? Tell your friends :D

Developer Guide

Contributing

We very much appreciate contributions from the community.

Issue First Please

If you have an idea or a fix, please do raise a GitHub issue before investing in any coding effort. That way we can discuss first. Writing code is the easy part, maintaining it forever is the hard part.

That said, if you notice a simple typo, a PR without an issue is fine.

Submitting a Pull Request

The entire test suite can take several minutes to run. Depending on your change, you might choose to sanity test with a subset of tests or browsers.

When you submit a PR, GitHub Actions will kick in and test across all supported browsers, OSes, Babashka and Clojure. There’s no shame in it finding a problem you didn’t anticipate. Given the nature of WebDrivers and browsers, it is not entirely unusual for a job or two to fail. You can request GitHub Actions to rerun the failed jobs. If they fail a second time you might have an issue to solve.

Environmental Overview

Supported Environments

Etaoin is tested on macOS, Ubuntu and Windows via GitHub Actions on each commit to the master branch. All tests are run under Clojure and Babashka. We test against against Chrome, Firefox, Edge and Safari depending on the OS.

Developer Prerequisites

  • Java Development Kit 1.8 or above

  • Current version of Clojure cli for clojure command

    • Note: the Etaoin library itself supports Clojure v1.9 and above

  • Current vesion of Babashka

  • Browsers and WebDrivers, see installation tips instructions in user guide

    • We currently test against is installed by GitHub Actions on their virtual environments. They seem to keep browsers and drivers up to date. If we find we need to, we’ll invest in tweaking these defaults, but we don’t see a need as of this writing.

  • ImageMagick - used by tests to verify that screenshots produce valid PNG files

It is also useful to have access to the variety of OSes that Etaoin supports to diagnose and fix any OS-specific issues that may arise.

Babashka Compatibility

Etaoin is babashka compatible.

Babashka supports everything that Etaoin needs, but when making changes, be aware that your code must also work under Babashka. For example, to make Etaoin Babashka compatible we made the following changes:

  1. Turf unused reference to java.lang.IllegalThreadStateException

  2. Replace use of org.clojure/data.codec with JDK’s Base64

  3. Replace use of ImageIO in tests with a callout to ImageMagick instead.

  4. Replace some JDK file related class references with babashka/fs abstractions

  5. Use http-client-lite in place of http-client when running under Babashka

  6. Run existing tests with cognitect test runner by including babashka/tools.namespace

Nothing earth shattering there, but gives you and idea.

Docs

All documentation is written in AsciiDoc. @lread likes to follow AsciiDoc best practice of one sentence per line but won’t be entirely pedantic about that.

We host our docs on cljdoc and have support for previewing

Babashka Tasks

We use Babashka tasks, to see all available tasks run:

bb tasks

Launching a REPL

For a Clojure REPL

bb dev:jvm

For a babashka REPL

bb dev:bb

Checking Tools Versions

Used by GitHub Actions, but also an interesting way to check your prerequisites:

bb tools-versions

Runing tests

Use the test:jvm and test:bb tasks to invoke tests.

bb test:jvm --help
bb test:bb --help

You can choose to invoke a test suite or individual tests.

Testing User Guide Code Blocks

There are many code examples in the user guide. In an attempt to ensure they are in working order, we run a selection of them through test-doc-blocks.

bb test-doc

If you are updating the user guide, it preferable if your code block can be run through test-doc-blocks. But if this is impractal, you can also have test-doc-blocks skip a code block.

Testing within Docker

If you wish, you can build a local docker image for testing on Linux. You may want to try this because:

  • you are developing on macOS and want to run a sanity test on Linux

  • or maybe you’d like to isolate a test run without windows popping up hither and thither (on docker we use a virtual display)

To build a local docker image with Chrome and Firefox support:

bb docker-build
This will build a docker image with current releases of Chrome, Firefox and their respective WebDrivers. Rerun the command as necessary.

You can run a single command and exit:

bb docker-run bb test:bb --suites unit

Or use the docker image interactively:

bb docker-run

And then at the interactive prompt:

bb test:jvm --suites ide --browsers firefox
docker-run plunks you automatically into /etaoin which maps to the etaoin project root

There is nothing magic about the babashka docker tasks. They are here for our convenience. Feel free to run docker commands directly if that is more your thing.

WebDriver Processes

Sometimes WebDriver processes might hang around longer than you’d like.

To list them:

bb drivers

To terminate them:

bb drivers kill

Linting

We use clj-kondo to lint Etaoin source code.

To lint Etaoin sources:

bb lint

We like to keep our code free of lint warnings and fail CI if there are any lint issues. This keeps our code tidy and also helps us to ensure our clj-kondo export config is working as expected.

Integrate clj-kondo into your editor to catch mistakes as you type them.

Outdated dependencies

To run check Etaoin dependencies:

bb outdated

Cljdoc Preview

Before a release, it can be comforting to preview what docs will look like on cljdoc.

This task should be considered experimental, I have only tested running on macOS, but am fairly confident it will work on Linux. Not sure about Windows at this time.

You have to push your changes to GitHub to preview them. This allows for a full preview that includes any links (source, images, etc) to GitHub. This works fine from branches and forks.

Run bb cljdoc-preview --help for help.

  • bb cljdoc-preview start downloads (if necessary) and starts the cljdoc docker image

  • bb cljdoc-preview ingest installs etaoin to your local maven repo and imports it into locally running cljdoc

  • bb cljdoc-preview view opens a view to your imported docs in your default web browser

  • bb cljdoc-preview stop stops the docker image

Other Notes

Logging

When running tests under the JVM, info level logging is configured via env/test/resources/logback.xml. This is automatically selected via the :test alias. You can prefix the :debug alias for debug level logging. See script/test.clj and tweak if necessary.

For Babashka, logging levels are controlled via the built-in timbre library. See script/bb_test_runner.clj and tweak if necessary.

Sometimes tools like WireShark can also be helpful. @lread personally used a combination of RawCap and WireShark on Windows to successfully diagnose an issue.

Clj-kondo Export Config

Users of Etaoin and clj-kondo benefit from our clj-kondo export configuration. As is the convention, you’ll find it under ./resources/clj-kondo.exports/. We keep any clj-kondo config containing our local linting preferences, and pertinent to only our internal code, in .clj-kondo/config.edn.

This configuration is included in the Etaoin release jar and available when folks reference Etaoin from their deps.edn form a git dependency.

Etaoin contains a fair number of macros. Clj-kondo can need special configuration (including hooks) to understand the effects of these macros. So, when adding any new macros, think also about our Etaoin users and our clj-kondo export configuration.

Useful References

❮User GuideContributing❯

Can you improve this documentation? These fine people already did:
Lee Read & lreadEdit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcutsReport a problemcljdoc on GitHub
× close