Skip to content

Latest commit

 

History

History
203 lines (140 loc) · 6.59 KB

02-developer-guide.adoc

File metadata and controls

203 lines (140 loc) · 6.59 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 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

For a babashka REPL

bb bb-dev

Checking Tools Versions

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

bb tools-versions

Runing tests

The test task provides a coarse grained facility to invoke tests. It was written to satisfy the use case of running tests in parallel on GitHub Actions.

bb test --help

We’ll likely add finer grained test selection to satisfy developer needs. For now, temporarily tweak ./script/test.clj if you need to.

WebDriver Processes

Sometimes WebDriver process 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, but don’t currently fail CI if there are lint issues.

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

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 [COMING SOON]

Users of Etaoin and clj-kondo benefit from our clj-kondo export configuration.

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.