Merge pull request #443 from lread/lread-dev-guide-and-some-tasks

Flesh out developer guide and add some bb tasks

.clj-kondo/config.edn

@@ -3,9 +3,8 @@
  :hooks
  ;; for now we'll use the simple macroexpand, can move to hooks for finer grained errors later
  {:macroexpand
-  {etaoin.util/defmethods etaoin.util/defmethods
-   etaoin.util/with-tmp-dir etaoin.util/with-tmp-dir
-   etaoin.util/with-tmp-file etaoin.util/with-tmp-file
+  {etaoin.impl.util/defmethods etaoin.impl.util/defmethods
+   etaoin.impl.util/with-tmp-file etaoin.impl.util/with-tmp-file
 
    etaoin.api/with-key-down etaoin.api/with-key-down
    etaoin.api/with-pointer-btn-down etaoin.api/with-pointer-btn-down

.clj-kondo/etaoin/util.clj → .clj-kondo/etaoin/impl/util.clj

@@ -1,4 +1,4 @@
-(ns etaoin.util)
+(ns etaoin.impl.util)
 
 (defmacro defmethods
   "Declares multimethods in batch. For each dispatch value from
@@ -11,8 +11,3 @@
 (defmacro with-tmp-file [prefix suffix bind & body]
   `(let [~bind "somepath"]
      ~@body))
-
-;; essence only for linting
-(defmacro with-tmp-dir [prefix bind & body]
-  `(let [~bind "somepath"]
-     ~@body))

Makefile

@@ -1,10 +1,3 @@
-.PHONY: kill
-kill:
-	pkill chromedriver || true
-	pkill geckodriver || true
-	pkill safaridriver || true
-	pkill phantomjs || true
-
 IMAGE := etaoin
 
 .PHONY: docker-build

README.adoc

@@ -14,7 +14,7 @@ https://clojars.org/{project-mvn-coords}[image:https://img.shields.io/clojars/v/
 https://babashka.org[image:https://raw.githubusercontent.com/babashka/babashka/master/logo/badge.svg[bb compatible]]
 https://clojurians.slack.com/archives/C7KDM0EKW[image:https://img.shields.io/badge/slack-join_chat-brightgreen.svg[Join chat]]
 
-A pure Clojure implementation of the link:{url-webdriver}[Webdriver] protocol named after link:{url-wiki}[Etaoin Shrdlu] -- a typing machine that became alive after a mysterious note was produced on it.
+A pure Clojure implementation of the link:{url-webdriver}[Webdriver] protocol named after link:{url-wiki}[Etaoin Shrdlu] -- a typing machine that came to life after a mysterious note was produced on it.
 
 Use the Etaoin library to automate a browser, test your frontend behaviour, simulate human actions or whatever you want.
 
@@ -62,6 +62,16 @@ Ivan's blog-post about pitfalls that can occur when testing UI.
 
 You are welcome to submit your company to this list.
 
+== Versioning
+
+Eatoin uses: `major`.`minor`.`patch`-`test-qualifier`
+
+* `major` increments when a non alpha release API has been broken - something, as a rule, we'd like to avoid.
+* `minor` increments to convey significant new features have been added.
+* `patch` indicates bug fixes or minor changes - it is the total number of releases to date.
+* `test-qualifier` is absent for stable releases.
+Can be `alpha`, `beta`, `rc1`, etc.
+
 == People
 
 === Contributors

bb.edn

@@ -5,12 +5,36 @@
         dev.nubank/docopt {:mvn/version "0.6.1-fix7"}}
  :tasks
  {;; setup
-  :requires ([clojure.string :as string]
+  :requires ([babashka.classpath :as cp]
+             [babashka.fs :as fs]
+             [clojure.string :as string]
+             [helper.shell :as shell]
              [lread.status-line :as status])
   :enter (let [{:keys [name]} (current-task)] (status/line :head "TASK %s %s" name (string/join " " *command-line-args*)))
   :leave (let [{:keys [name]} (current-task)] (status/line :detail "\nTASK %s done." name))
 
   ;; commands
-  download-deps  {:task download-deps/-main  :doc "download all deps (useful for CI prep)"}
-  tools-versions {:task tools-versions/-main :doc "report on tools versions"}
-  test           {:task test/-main           :doc "run all or a subset of tests, use --help for args"}}}
+
+  dev            {:doc "start a Clojure nrepl server/prompt"
+                  :task (shell/command "clj" "-M:test:repl/cider")}
+  bb-dev         {:doc "start a Babashka nrepl server"
+                  :task (let [cp (-> (shell/clojure "-Spath -M:test:bb-spec:bb-test")
+                                     with-out-str)
+                              bbcp (cp/get-classpath)]
+                          (shell/command "bb"
+                                         "--classpath" (str cp fs/path-separator bbcp)
+                                         "--nrepl-server"))}
+  test           {:doc "run all or a subset of tests, use --help for args"
+                  :task test/-main}
+  drivers        {:doc "[list|kill] any running WebDrivers"
+                  :task drivers/-main}
+  lint           {:doc "[--rebuild] lint source code"
+                  :task lint/-main}
+  cljdoc-preview {:doc "preview what docs will look like on cljdoc, use --help for args"
+                  :task cljdoc-preview/-main}
+  tools-versions {:doc "report on tools versions"
+                  :task tools-versions/-main}
+  download-deps  {:doc "download all deps (useful for CI prep)"
+                  :task download-deps/-main}
+  outdated       {:task (shell/clojure {:continue true} "-M:outdated")
+                  :doc "report on outdated dependencies"}}}

build.clj

@@ -0,0 +1,63 @@
+(ns build
+  (:require [clojure.tools.build.api :as b]
+            [clojure.string :as string]))
+
+(defn- num-releases
+  "We'll assume num tags = num releases"
+  []
+  (-> (b/git-process {:git-args "tags"})
+      (string/split-lines)
+      count))
+
+(def lib 'etaoin/etaoin)
+(def version (format "1.0.%d" (inc (num-releases))))
+(def class-dir "target/classes")
+(def basis (b/create-basis {:project "deps.edn"}))
+(def jar-file (format "target/%s-%s.jar" (name lib) version))
+(def built-jar-version-file "target/built-jar-version.txt")
+
+(defn clean [_]
+  (b/delete {:path "target"}))
+
+(defn jar
+  "Build library jar file.
+  Also writes built version to target/built-jar-version.txt for easy peasy pickup by any interested downstream operation.
+
+  We use the optional :version-suffix to optionally distinguish local installs from productin releases.
+  For example, when installing for a cljdoc preview suffix is: cljdoc-preview."
+  [{:keys [version-suffix] :as opts}]
+  (let [version (if version-suffix
+                  (format "%s-%s" version version-suffix)
+                  version)]
+
+    (b/write-pom {:class-dir class-dir
+                  :lib lib
+                  :version version
+                  :scm {:tag version}
+                  :basis basis
+                  :src-dirs ["src"]})
+    (b/copy-dir {:src-dirs ["src" "resources"]
+                 :target-dir class-dir})
+    (b/jar {:class-dir class-dir
+            :jar-file jar-file})
+    (spit built-jar-version-file version)
+    (assoc opts :built-jar-version version)))
+
+(defn install [opts]
+  (clean opts)
+  (let [{:keys [built-jar-version]} (jar opts)]
+    (b/install {:class-dir class-dir
+                :lib lib
+                :version built-jar-version
+                :basis basis
+                :jar-file jar-file})))
+
+(defn publish [opts]
+  (clean opts)
+  (jar opts)
+  ((requiring-resolve 'deps-deploy.deps-deploy/deploy)
+    (merge {:installer :remote
+                       :artifact jar-file
+                       :pom-file (b/pom-path {:lib lib :class-dir class-dir})}
+                    opts))
+  opts)

deps.edn

@@ -21,4 +21,25 @@
                                                   :sha "644a7fc216e43d5da87b07471b0f87d874107d1a"}}}
   ;; for babashka testing, allows us to use cognitect test-runner
   :bb-test {:extra-deps {org.clojure/tools.namespace {:git/url "https://github.com/babashka/tools.namespace"
-                                                      :git/sha "a13b037215e21a2e71aa34b27e1dd52c801a2a7b"}}}}}
+                                                      :git/sha "a13b037215e21a2e71aa34b27e1dd52c801a2a7b"}}}
+  ;; for consistent linting we use a specific version of clj-kondo through the jvm
+  :clj-kondo {:extra-deps {clj-kondo/clj-kondo {:mvn/version "2022.04.25"}}
+              :main-opts ["-m" "clj-kondo.main"]}
+
+  :build {:deps {io.github.clojure/tools.build {:git/tag "v0.8.2" :git/sha "ba1a2bf"}
+                 slipset/deps-deploy {:mvn/version "0.2.0"}}
+          :ns-default build}
+
+  :outdated {:extra-deps {com.github.liquidz/antq {:mvn/version "1.6.774"}
+                          org.slf4j/slf4j-simple {:mvn/version "1.7.36"} ;; to rid ourselves of logger warnings
+                          }
+             :main-opts ["-m" "antq.core"]}
+
+  :repl/cider
+  {:extra-deps {nrepl/nrepl                {:mvn/version "0.9.0"}
+                cider/cider-nrepl          {:mvn/version "0.28.4"}
+                refactor-nrepl/refactor-nrepl {:mvn/version "3.5.2"}}
+   :jvm-opts ["-XX:-OmitStackTraceInFastThrow"]
+   :main-opts  ["-m" "nrepl.cmdline"
+                "--middleware" "[refactor-nrepl.middleware/wrap-refactor,cider.nrepl/cider-middleware]"
+                "-i"]}}}

doc/01-user-guide.adoc

@@ -22,6 +22,7 @@ If Etaoin is not your cup of tea, you might also consider:
 
 * https://github.com/tatut/clj-chrome-devtools[clj-chrome-devtools]
 
+[[supported-os-browser]]
 === Supported OSes & Browsers
 
 Etaoin's test suite covers the following OSes and browsers run with both regular Clojure and Babashka:
@@ -107,6 +108,7 @@ See https://github.com/babashka/spec.alpha[babashka/spec.alpha] for current docs
 :url-webkit: https://webkit.org/blog/6900/webdriver-support-in-safari-10/
 :url-edge-dl: https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/
 
+[[install-webdrivers]]
 === Installing the Browser WebDrivers
 
 Etaoin controls web browsers via their WebDrivers.