Skip to content

Latest commit

 

History

History
288 lines (203 loc) · 9.22 KB

02-developer-guide.adoc

File metadata and controls

288 lines (203 loc) · 9.22 KB
Raw

Developer Guide

Table of Contents

Contributing

We very much appreciate contributions from the community.

Issue First Please

If you have an idea or a fix, please 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 finding a problem you didn’t anticipate. Given the nature of CI, 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 for 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 11 or above

  • Current version of Clojure cli for clojure command

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

  • Current version of Babashka

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

    • We currently test against what 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 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. Switch to babashka/http-client

Nothing earth-shattering there, but it gives you an 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

By default you can only connect to the REPL from localhost. If you need to connect to a REPL running on a different host, launch your REPL with --host. For example, to allow anyone to connect to your REPL:

bb dev:jvm --host 0.0.0.0

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 is preferable that your code blocks are run through test-doc-blocks. But if this is impractical, 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
Tip
 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
Note
 docker-run copies etaoin project files into /home/etaoin-user/etaoin which will be your work dir.

The docker image is catered to running Etaoin tests.

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 helps us to ensure our clj-kondo export config is working as expected.

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

Note

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

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

Test Coverage

Sometimes, it’s nice to get an idea of what parts of Etaoin’s unit and doc tests (or more importantly, don’t) cover.

bb test-coverage

The intent is not to strive for some percentage of coverage, just information on what is not covered.

When possible, run from macOS, the only OS where we hit all supported browsers (you’ll need all browsers and WebDrivers installed and up to date).

It will take a while, but after tests are complete, crack open ./target/clofidence/index.html for results.

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.

Note

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.