with_clues 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e8a1a2ede55c2de31c9a7a7e53a576b4a52dd08001b87a9406e8b9a16fa5495
-  data.tar.gz: 7e75e12ebe1d192c74813521f4800d2e70dd2641e1c8e70f5cda563fea700100
+  metadata.gz: b17d4876d0162d52c3cf3e767c70b26cb2d18ff9ed144eda164ddf3afdbcd6f7
+  data.tar.gz: 6e605bc07cae10efaf1b3866987f31cc36bd4bf619b5414b8d43d0f8c7b0c76a
 SHA512:
-  metadata.gz: 2c3722af382010534c4020a70b17ff7c6907c101fc0f6159758193a8152b30850a0b208dcfd6a94d1128275b8026c524bad9a2e4cac55bd292cb4c4bc9dc0645
-  data.tar.gz: c90b2558520118f6617db83b2a3a48317ee51a03bfd01fc3eec9a726f6e4b5aea34fccc03cae5d74c03aed117eefdf8b39942084f59eed2ecadcb3784954907a
+  metadata.gz: 104eb1b602cd79c0dd3183daf5e47dff90e39bbeed82c06209b079902bc7e27d5a49631a22bc76c2a801a9193d3f8d8e0f026755962a2688fa135fb73aa9b426
+  data.tar.gz: 9c8bf899641fe07713725bd7ed7591ff85e59ad2e61c05b508ecddfc71f3a9c352132ed685e0f0cb3d16b304403c18f039626fa0a5e153d51002161ab66edab4

data/CHANGELOG.md

@@ -0,0 +1 @@
+See [https://github.com/sustainable-rails/with\_clues/releases](https://github.com/sustainable-rails/with_clues/releases)

data/Dockerfile.dx

@@ -0,0 +1,28 @@
+ARG RUBY_VERSION
+FROM ruby:${RUBY_VERSION}
+
+ENV DEBIAN_FRONTEND noninteractive
+RUN apt-get -y update
+
+
+# dx.snippet.start=templates/snippets/bundler/latest__bundler.dockerfile-snippet
+# Based on documentation at https://guides.rubygems.org/command-reference/#gem-update
+# based on the vendor's documentation
+RUN echo "gem: --no-document" >> ~/.gemrc && \
+    gem update --system && \
+    gem install bundler
+
+# dx.snippet.end=templates/snippets/bundler/latest__bundler.dockerfile-snippet
+
+
+# dx.snippet.start=templates/snippets/vim/bullseye_vim.dockerfile-snippet
+# Based on documentation at https://packages.debian.org/search?keywords=vim
+# based on the vendor's documentation
+ENV EDITOR=vim
+RUN apt-get install -y vim && \
+    echo "set -o vi" >> /root/.bashrc
+# dx.snippet.end=templates/snippets/vim/bullseye_vim.dockerfile-snippet
+
+# This entrypoint produces a nice help message and waits around for you to do
+# something with the container.
+COPY dx/show-help-in-app-container-then-wait.sh /root

data/README.md

@@ -6,8 +6,7 @@ Suppose you have this:
 expect(page).to have_content("My Awesome Site")
 ```
 
-And Capybara says that that content is not there and that is all it says.  You might slap in a `puts page.html` and try again.
-Instead, what if you could not do that and do this?
+And Capybara says that that content is not there and that is all it says.  You might slap in a `puts page.html` and try again. Instead, what if you could not do that and do this?
 
 ```ruby
 with_clues do
@@ -71,8 +70,7 @@ end
 
 ## Use
 
-In general, you would not want to wrap all tests with `with_clues`.  This is a diagnostic tool to allow you to get more
-information on a test that is failing.  As such, your workflow might be:
+In general, you would not want to wrap all tests with `with_clues`.  This is a diagnostic tool to allow you to get more information on a test that is failing.  As such, your workflow might be:
 
 1. Notice a test failing that you cannot easily diagnose
 1. Wrap the failing assertion in `with_clues`:
@@ -89,8 +87,10 @@ information on a test that is failing.  As such, your workflow might be:
 
 There are three clues included:
 
-* Dumping HTML - when `page` exists, it will dump the contents of `page.html` when the test fails
-* Dumping Browser logs - for a browser-based test, it will dump anything that was `console.log`'ed
+* Dumping HTML - when `page` exists, it will dump the contents of `page.html` (for Selenium) or `page.content`
+(for Playwright) when the test fails
+* Dumping Browser logs - for a browser-based test, it will dump anything that was `console.log`'ed. This should
+work with Selenium and Playwright
 * Arbitrary context you pass in, for example when testing an Active Record
 
   ```ruby
@@ -107,13 +107,16 @@ There are three clues included:
 `with_clues` is intended as a diagnostic tool you can develop and enhance over time.  As your team writes more code or develops
 more conventions, you can develop diagnostics as well.
 
-To add one, create a class that implements `dump(notifier, context:)`:
+To add one, create a class that implements `dump(notifier, context:)` or `dump(notifier, context:, page:)` or
+`dump(notifier, context:, page:, captured_logs)`:
 
-* `notifier` is a `WithClues::Notifier` that you should use to produce output:
-  * `notify` - output text, preceded with `[ with_clues ]` (this is so you can tell output from your code vs from `with_clues`)
-  * `blank_line` - a blank line (no prefix)
-  * `notify_raw` - output text without a prefix, useful for removing ambiguity about what is being output
+* `notifier` is a `WithClues::Notifier` that you should use to produce output via the following methods:
+  * `notifier.notify` - output text, preceded with `[ with_clues ]` (this is so you can tell output from your code vs from `with_clues`)
+  * `notifier.blank_line` - a blank line (no prefix)
+  * `notifier.notify_raw` - output text without a prefix, useful for removing ambiguity about what is being output
 * `context:` the context passed into `with_clues` (nil if it was omitted)
+* `page:` will be given the Selenium or Playwright page object
+* `captured_logs:` for Playwright, this will be the browser console logs captured inside the block
 
 For example, suppose you want to output information about an Active Record like so:
 
@@ -153,6 +156,9 @@ WithClues::Method.use_custom_clue ActiveRecordClues
 
 You can use multiple clues by repeatedly calling `use_custom_clue`
 
+Note that if your clue implements the three-arg version of `dump` ( `dump(notifier, context:, page:)` ), it will *only* be used when in
+a context where Capybara's `page` element in in play.
+
 ## Developing
 
 * Get set up with `bin/setup`

data/bin/matrix

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+. dx/docker-compose.env
+for version in ${RUBY_VERSIONS[@]}; do
+  dx/exec -v $version bin/setup && dx/exec -v $version bin/ci
+done

data/docker-compose.dx.yml

@@ -0,0 +1,33 @@
+# THIS IS GENERATED - DO NOT EDIT
+
+services:
+  with-clues-3.1:
+    image: sustainable-rails/with-clues-dev:ruby-3.1
+    init: true
+    volumes:
+      - type: bind
+        source: "./"
+        target: "/root/work"
+        consistency: "consistent"
+    entrypoint: /root/show-help-in-app-container-then-wait.sh
+    working_dir: /root/work
+  with-clues-3.2:
+    image: sustainable-rails/with-clues-dev:ruby-3.2
+    init: true
+    volumes:
+      - type: bind
+        source: "./"
+        target: "/root/work"
+        consistency: "consistent"
+    entrypoint: /root/show-help-in-app-container-then-wait.sh
+    working_dir: /root/work
+  with-clues-3.3:
+    image: sustainable-rails/with-clues-dev:ruby-3.3
+    init: true
+    volumes:
+      - type: bind
+        source: "./"
+        target: "/root/work"
+        consistency: "consistent"
+    entrypoint: /root/show-help-in-app-container-then-wait.sh
+    working_dir: /root/work

data/dx/build

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+
+require_command "docker"
+load_docker_compose_env
+
+usage_on_help "Builds the Docker image based on the Dockerfile" "" "build.pre" "build.post" "${@}"
+
+for ruby_version in ${RUBY_VERSIONS[@]}; do
+  dockerfile="Dockerfile.dx"
+  docker_image_name="${IMAGE}:ruby-${ruby_version}"
+
+  log "Building for Ruby '${ruby_version}' using Docker image name '${docker_image_name}'"
+
+  exec_hook_if_exists "build.pre" "${dockerfile}" "${docker_image_name}"
+
+  docker build \
+    --file "${dockerfile}" \
+    --build-arg="RUBY_VERSION=${ruby_version}" \
+    --tag "${docker_image_name}" \
+    ./
+
+  exec_hook_if_exists "build.post" "${dockerfile}" "${docker_image_name}"
+  log "🌈" "Your Docker image has been built tagged '${docker_image_name}'"
+done
+
+log "✅" "All images built"
+
+log "✨" "Creating docker-compose.dx.yml"
+compose_file="docker-compose.dx.yml"
+log "🗑️" "Deleting previous ${compose_file}"
+
+rm -f "${compose_file}"
+echo "# THIS IS GENERATED - DO NOT EDIT" > "${compose_file}"
+echo "" >> "${compose_file}"
+echo "services:" >> "${compose_file}"
+
+for ruby_version in ${RUBY_VERSIONS[@]}; do
+  log "Generating stanza for version '${ruby_version}'"
+  docker_image_name="${IMAGE}:ruby-${ruby_version}"
+  echo "  with-clues-${ruby_version}:" >> "${compose_file}"
+  echo "    image: ${docker_image_name}" >> "${compose_file}"
+  echo "    init: true" >> "${compose_file}"
+  echo "    volumes:" >> "${compose_file}"
+  echo "      - type: bind" >> "${compose_file}"
+  echo "        source: \"./\"" >> "${compose_file}"
+  echo "        target: \"/root/work\"" >> "${compose_file}"
+  echo "        consistency: \"consistent\"" >> "${compose_file}"
+  echo "    entrypoint: /root/show-help-in-app-container-then-wait.sh" >> "${compose_file}"
+  echo "    working_dir: /root/work" >> "${compose_file}"
+done
+log "🎼" "${compose_file} is now created"
+log "🔄" "You can run dx/start to start it up, though you may need to stop it first with Ctrl-C"
+
+# vim: ft=bash

data/dx/docker-compose.env

@@ -0,0 +1,5 @@
+# This array must include the oldest Ruby first!
+RUBY_VERSIONS=("3.1" "3.2" "3.3")
+IMAGE=sustainable-rails/with-clues-dev
+PROJECT_NAME=with-clues
+# vim: ft=bash

data/dx/dx.sh.lib

@@ -0,0 +1,24 @@
+# shellcheck shell=bash
+
+. "${SCRIPT_DIR}/setupkit.sh.lib"
+
+require_command "realpath"
+require_command "cat"
+
+ENV_FILE=$(realpath "${SCRIPT_DIR}")/docker-compose.env
+
+load_docker_compose_env() {
+  . "${ENV_FILE}"
+}
+
+exec_hook_if_exists() {
+  script_name=$1
+  shift
+  if [ -x "${SCRIPT_DIR}"/"${script_name}" ]; then
+    log "🪝" "${script_name} exists - executing"
+    "${SCRIPT_DIR}"/"${script_name}" "${@}"
+  else
+    debug "${script_name} does not exist"
+  fi
+}
+# vim: ft=bash

data/dx/exec

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+
+require_command "docker"
+load_docker_compose_env
+
+usage_description="Execute a command inside the app's container."
+usage_args="[-s service] [-v ruby_version] command"
+usage_pre="exec.pre"
+usage_on_help "${usage_description}" "${usage_args}" "${usage_pre}" "" "${@}"
+
+LATEST_RUBY=${RUBY_VERSIONS[0]}
+DEFAULT_SERVICE=with-clues-${LATEST_RUBY}
+SERVICE="${SERVICE_NAME:-${DEFAULT_SERVICE}}"
+while getopts "v:s:" opt "${@}"; do
+  case ${opt} in
+    v )
+      SERVICE="with-clues-${OPTARG}"
+      ;;
+    s )
+      SERVICE="${OPTARG}"
+      ;;
+    \? )
+      log "🛑" "Unknown option: ${opt}"
+      usage "${description}" "${usage_args}" "${usage_pre}"
+      ;;
+    : )
+      log "🛑" "Invalid option: ${opt} requires an argument"
+      usage "${description}" "${usage_args}" "${usage_pre}"
+      ;;
+  esac
+done
+shift $((OPTIND -1))
+
+if [ $# -eq 0 ]; then
+  log "🛑" "You must provide a command e.g. bash or ls -l"
+  usage "${description}" "${usage_args}" "${usage_pre}"
+fi
+
+
+exec_hook_if_exists "exec.pre"
+
+log "🚂" "Running '${*}' inside container with service name '${SERVICE}'"
+
+docker \
+  compose \
+    --file docker-compose.dx.yaml \
+    --project-name "${PROJECT_NAME}" \
+    --env-file "${ENV_FILE}" \
+  exec \
+    "${SERVICE}" \
+    "${@}"
+
+# vim: ft=bash

data/dx/prune

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+require_command "docker"
+load_docker_compose_env
+
+usage_on_help "Prune containers for this repo" "" "" "" "${@}"
+
+for container_id in $(docker container ls -a -f "name=^${PROJECT_NAME}-.*-1$" --format="{{.ID}}"); do
+  log "🗑" "Removing container with id '${container_id}'"
+  docker container rm "${container_id}"
+done
+echo "🧼" "Containers removed"
+
+# vim: ft=bash

data/dx/setupkit.sh.lib

@@ -0,0 +1,144 @@
+# shellcheck shell=bash
+
+fatal() {
+  remainder=${*:2}
+  if [ -z "$remainder" ]; then
+    log "🛑" "${@}"
+  else
+    log "${@}"
+  fi
+  exit 1
+}
+
+log() {
+  emoji=$1
+  remainder=${*:2}
+  if [ -z "${NO_EMOJI}" ]; then
+    echo "[ ${0} ] ${*}"
+  else
+    # if remainder is empty that means no emoji was passed
+    if [ -z "$remainder" ]; then
+      echo "[ ${0} ] ${*}"
+    else # emoji was passed, but we ignore it
+      echo "[ ${0} ] ${remainder}"
+    fi
+  fi
+}
+
+debug() {
+  message=$1
+  if [ -z "${DOCKBOX_DEBUG}" ]; then
+    return
+  fi
+  log "🐛" "${message}"
+}
+
+usage() {
+  description=$1
+  arg_names=$2
+  pre_hook=$3
+  post_hook=$4
+  echo "usage: ${0} [-h] ${arg_names}"
+  if [ -n "${description}" ]; then
+    echo
+    echo "DESCRIPTION"
+    echo "    ${description}"
+  fi
+  if [ -n "${pre_hook}" ] || [ -n "${post_hook}" ]; then
+    echo
+    echo "HOOKS"
+    if [ -n "${pre_hook}" ]; then
+      echo "    ${pre_hook} - if present, called before the main action"
+    fi
+    if [ -n "${post_hook}" ]; then
+      echo "    ${post_hook} - if present, called after the main action"
+    fi
+  fi
+  exit 0
+}
+
+usage_on_help() {
+  description=$1
+  arg_names=$2
+  pre_hook=$3
+  post_hook=$4
+  # These are the args passed to the invocation so this
+  # function can determine if the user requested help
+  cli_args=( "${@:5}" ) 
+
+  for arg in "${cli_args[@]}"; do
+    if [ "${arg}" = "-h" ] || [ "${arg}" = "--help" ]; then
+      usage "${description}" "${arg_names}" "${pre_hook}" "${post_hook}"
+    fi
+  done
+}
+
+# Read user input into the variable 'INPUT'
+#
+# Args:
+#
+# [1] - an emoji to use for messages
+# [2] - the message explaining what input is being requested
+# [3] - a default value to use if no value is provided
+#
+# Respects NO_EMOJI when outputing messages to the user
+user_input() {
+  emoji=$1
+  message=$2
+  default=$3
+  prompt=$4
+
+  if [ -z "$message" ]; then
+    echo "user_input requires a message"
+    exit 1
+  fi
+
+  INPUT=
+
+  if [ -z "${prompt}" ]; then
+    prompt=$(log "${emoji}" "Value: ")
+    if [ -n "${default}" ]; then
+      prompt=$(log "${emoji}" "Value (or hit return to use '${default}'): ")
+    fi
+  fi
+
+  while [ -z "${INPUT}" ]; do
+
+    log "$emoji" "$message"
+    read -r -p "${prompt}" INPUT
+    if [ -z "$INPUT" ]; then
+      INPUT=$default
+    fi
+    if [ -z "$INPUT" ]; then
+      log "😶", "You must provide a value"
+    fi
+  done
+}
+
+user_confirm() {
+  user_input "$1" "$2" "$3" "y/n> "
+}
+
+require_not_exist() {
+  file=$1
+  message=$2
+  if [ -e "${file}" ]; then
+    fatal "$message"
+  fi
+}
+require_exist() {
+  file=$1
+  message=$2
+  if [ ! -e "${file}" ]; then
+    fatal "$message"
+  fi
+}
+
+require_command() {
+  command_name=$1
+  if ! command -v "${command_name}" >/dev/null 2>&1; then
+    fatal "Command '${command_name}' not found - it is required for this script to run"
+  fi
+}
+
+# vim: ft=bash

data/dx/show-help-in-app-container-then-wait.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -e
+
+# Ideally, the message below is shown after everything starts up. We can't
+# achieve this using healtchecks because the interval for a healtcheck is
+# also an initial delay, and we don't really want to do healthchecks on 
+# our DB or Redis every 2 seconds.  So, we sleep just a bit to let
+# the other containers start up and vomit out their output first.
+sleep 2
+# Output some helpful messaging when invoking `dx/start` (which itself is
+# a convenience script for `docker compose up`.
+#
+# Adding this to work around the mild inconvenience of the `app` container's
+# entrypoint generating no output.
+#
+cat <<-'PROMPT'
+
+
+
+ 🎉  Dev Environment Initialized! 🎉
+
+ ℹ️   To use this environment, open a new terminal and run
+
+     dx/exec bash
+
+ 🕹  Use `ctrl-c` to exit.
+
+
+
+PROMPT
+
+# Using `sleep infinity` instead of `tail -f /dev/null`. This may be a 
+# performance improvement based on the conversation on a semi-related
+# StackOverflow page.
+#
+# @see https://stackoverflow.com/a/41655546
+sleep infinity

data/dx/start

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+require_command "docker"
+load_docker_compose_env
+
+usage_on_help "Starts all services, including a container in which to run your app" "" "" "" "${@}"
+
+log "🚀" "Starting docker-compose.dx.yml"
+
+BUILD=--build
+if [ "${1}" == "--no-build" ]; then
+    BUILD=
+fi
+
+docker \
+  compose \
+    --file docker-compose.dx.yml \
+    --project-name "${PROJECT_NAME}" \
+    --env-file "${ENV_FILE}" \
+  up \
+    "${BUILD}" \
+    --timestamps \
+    --force-recreate
+
+# vim: ft=bash

data/dx/stop

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${0}" )" > /dev/null 2>&1 && pwd )
+
+. "${SCRIPT_DIR}/dx.sh.lib"
+require_command "docker"
+load_docker_compose_env
+
+usage_on_help "Stops all services, the container in which to run your app and removes any volumes" "" "" "" "${@}"
+
+log "🚀" "Stopping docker-compose.dx.yml"
+
+docker \
+  compose \
+    --file docker-compose.dx.yml \
+    --project-name "${PROJECT_NAME}" \
+    --env-file "${ENV_FILE}" \
+  down \
+    --volumes
+
+# vim: ft=bash

data/lib/with_clues/browser_logs.rb

@@ -1,29 +1,40 @@
 module WithClues
   class BrowserLogs
-    def dump(notifier, page:, context:)
+    def dump(notifier, page:, context:, captured_logs: [])
       if !page.respond_to?(:driver)
         notifier.notify "Something may be wrong. page (#{page.class}) does not respond to #driver"
         return
       end
       if page.driver.respond_to?(:browser)
-        if page.driver.browser.respond_to?(:manage)
-          if page.driver.browser.manage.respond_to?(:logs)
-            logs = page.driver.browser.manage.logs
-            browser_logs = logs.get(:browser)
-            notifier.notify "BROWSER LOGS {"
-            browser_logs.each do |log|
-              notifier.notify_raw log.message
-            end
-            notifier.notify "} END BROWSER LOGS"
-          else
-            notifier.notify "NO BROWSER LOGS: page.driver.browser.manage #{page.driver.browser.manage.class} does not respond to #logs"
+        logs = locate_logs(page.driver.browser, notifier: notifier)
+        if !logs.nil?
+          browser_logs = logs.get(:browser)
+          notifier.notify "BROWSER LOGS {"
+          browser_logs.each do |log|
+            notifier.notify_raw log.message
           end
-        else
-          notifier.notify "NO BROWSER LOGS: page.driver.browser #{page.driver.browser.class} does not respond to #manage"
+          notifier.notify "} END BROWSER LOGS"
         end
       else
-        notifier.notify "NO BROWSER LOGS: page.driver #{page.driver.class} does not respond to #browser"
+        notifier.notify "[with_clues: #{self.class}] NO BROWSER LOGS: page.driver #{page.driver.class} does not respond to #browser"
       end
     end
+
+  private
+
+    def locate_logs(browser, notifier:)
+      if browser.respond_to?(:logs)
+        return browser.logs
+      elsif browser.respond_to?(:manage)
+        if browser.manage.respond_to?(:logs)
+          return browser.manage.logs
+        end
+        notifier.notify "[with_clues: #{self.class}] NO BROWSER LOGS: page.driver.browser.manage #{browser.manage.class} does not respond to #logs"
+      else
+        notifier.notify "[with_clues: #{self.class}] NO BROWSER LOGS: page.driver.browser #{browser.class} does not respond to #manage or #logs"
+      end
+      nil
+    end
+
   end
 end

data/lib/with_clues/html.rb

@@ -1,18 +1,31 @@
 module WithClues
   class Html
-    def dump(notifier, page:, context:)
+    def dump(notifier, page:, context:, captured_logs: [])
+      access_page_html = if page.respond_to?(:html)
+                           ->(page) { page.html }
+                         elsif page.respond_to?(:content)
+                           ->(page) { page.content }
+                         elsif page.respond_to?(:native)
+                           ->(page) { page.native }
+                         else
+                           notifier.notify "Something may be wrong. page (#{page.class}) does not respond to #html, #native, or #content"
+                           return
+                         end
       notifier.blank_line
       notifier.notify "HTML {"
       notifier.blank_line
-      if page.respond_to?(:html)
-        notifier.notify_raw page.html
-      elsif page.respond_to?(:native)
-        notifier.notify_raw page.native
-      else
-        notifier.notify "[!] Something may be wrong. page (#{page.class}) does not respond to #html or #native"
-      end
+      notifier.notify_raw access_page_html.(page)
       notifier.blank_line
       notifier.notify "} END HTML"
+      if captured_logs.any?
+        notifier.notify "LOGS {"
+        notifier.blank_line
+        captured_logs.each do |log|
+          notifier.notify_raw log
+        end
+        notifier.blank_line
+        notifier.notify "} END LOGS"
+      end
     end
   end
 end

data/lib/with_clues/method.rb

@@ -1,6 +1,7 @@
 require_relative "html"
 require_relative "browser_logs"
 require_relative "notifier"
+require_relative "private/custom_clue_method_analysis"
 
 module WithClues
   module Method
@@ -16,6 +17,15 @@ module WithClues
     # unexpectedly failing
     def with_clues(context=nil, &block)
       notifier = WithClues::Notifier.new($stdout)
+      captured_logs = []
+      if defined?(page) && page.respond_to?(:on)
+        begin
+          page.on("console", ->(msg) { captured_logs << msg.text })
+        rescue => ex
+          raise ex
+          notifier.notify "'page' was defined and responds to #on, however invoking it generated an exception: #{ex}"
+        end
+      end
       block.()
       notifier.notify "A passing test has been wrapped with `with_clues`. You should remove the call to `with_clues`"
     rescue Exception => ex
@@ -23,18 +33,25 @@ module WithClues
       @@clue_classes[:custom].each do |klass|
         klass.new.dump(notifier, context: context)
       end
-      if !defined?(page)
-        raise ex
-      end
-      notifier.notify "Test failed: #{ex.message}"
-      @@clue_classes[:require_page].each do |klass|
-        klass.new.dump(notifier, context: context, page: page)
+      if defined?(page)
+        notifier.notify "Test failed: #{ex.message}"
+        @@clue_classes[:require_page].each do |klass|
+          klass.new.dump(notifier, context: context, page: page, captured_logs: captured_logs)
+        end
       end
       raise ex
     end
 
     def self.use_custom_clue(klass)
-      @@clue_classes[:custom] << klass
+      dump_method = klass.instance_method(:dump)
+      analysis = WithClues::Private::CustomClueMethodAnalysis.from_method(dump_method)
+      if analysis.standard_implementation?
+        @@clue_classes[:custom] << klass
+      elsif analysis.requires_page_object?
+        @@clue_classes[:require_page] << klass
+      else
+        analysis.raise_exception!
+      end
     end
   end
 end

data/lib/with_clues/private/custom_clue_method_analysis.rb

@@ -0,0 +1,149 @@
+module WithClues
+  module Private
+    class CustomClueMethodAnalysis
+
+      def self.from_method(unbound_method)
+
+        params = unbound_method.parameters.map { |param_array| Param.new(param_array) }
+
+        if params.size == 2
+          two_arg_method = TwoArgMethod.new(params)
+          if two_arg_method.valid?
+            return StandardImplementation.new
+          end
+
+          return BadParams.new(two_arg_method.errors)
+
+        elsif params.size == 4
+          three_arg_method = FourArgMethod.new(params)
+          if three_arg_method.valid?
+            return RequiresPageObject.new
+          end
+          return BadParams.new(three_arg_method.errors)
+        end
+
+        BadParams.new([
+          "dump (#{unbound_method.owner}) accepted #{params.size} arguments, not 2 or 4. Got: #{params.map(&:to_s).join(", ")}, should be one positional and either one keyword arg named 'context:' or three keyword args named 'context:', 'page:', and 'captured_logs:'"
+        ])
+      end
+
+      def standard_implementation?
+        false
+      end
+
+      def requires_page_object?
+        false
+      end
+
+      def raise_exception!
+        raise StandardError.new("Unimplemented condition found inside #from_method")
+      end
+
+      class Param
+
+        def initialize(method_param_array)
+          @type = method_param_array[0]
+          @name = method_param_array[1]
+
+        end
+
+        def required?
+          @type == :req
+        end
+        def keyword_required?
+          @type == :keyreq
+        end
+
+        def named?(*allowed_names)
+          allowed_names.include?(@name)
+        end
+        def name
+          if self.keyword_required?
+            "#{@name}:"
+          else
+            @name
+          end
+        end
+        def to_s
+          "#<#{self.class} #{name}/#{@type}"
+        end
+      end
+
+      class TwoArgMethod
+        attr_reader :errors
+        def initialize(params)
+          @errors = []
+          if !params[0].required?
+            @errors << "Param 1, #{params[0].name}, is not required"
+          end
+          require_keyword(2,params[1])
+        end
+
+        def valid?
+          @errors.empty?
+        end
+      private
+
+        def require_keyword(param_number, param)
+          if !param.keyword_required?
+            @errors << "Param #{param_number}, #{param.name}, is not a required keyword param"
+          end
+          if !param.named?(*allowed_names)
+            @errors << "Param #{param_number}, #{param.name}, should be one of #{allowed_names.join(',')}"
+          end
+        end
+
+        def allowed_names
+          [ :context ]
+        end
+      end
+
+      class FourArgMethod < TwoArgMethod
+        def initialize(params)
+          super(params)
+          require_keyword(3,params[2])
+          require_keyword(4,params[3])
+        end
+      private
+        def allowed_names
+          [ :context, :page, :captured_logs ]
+        end
+      end
+
+    end
+
+    class GoodParams < CustomClueMethodAnalysis
+      def raise_exception!
+        raise StandardError.new("You should not have called .exception on a #{self.class.name}")
+      end
+    end
+
+    class RequiresPageObject < CustomClueMethodAnalysis
+      def requires_page_object?
+        true
+      end
+    end
+
+    class StandardImplementation < CustomClueMethodAnalysis
+      def standard_implementation?
+        true
+      end
+    end
+
+    class BadParams < CustomClueMethodAnalysis
+      def initialize(errors)
+        if errors.empty?
+          raise ArgumentError,"BadParams requires errors"
+        else
+          @message = errors.map(&:to_s).join(", ")
+        end
+      end
+
+      DEFAULT_ERROR = "dump must take one required param, one keyword param named context: and an optional keyword param named page:"
+
+      def raise_exception!
+        raise NameError.new(@message)
+      end
+    end
+  end
+end

data/lib/with_clues/version.rb

@@ -1,3 +1,3 @@
 module WithClues
-  VERSION="1.1.0"
+  VERSION="1.3.0"
 end

data/with_clues.gemspec

@@ -1,13 +1,11 @@
 require_relative "lib/with_clues/version"
 
-#require_relative "lib/«gem»/version"
-
 Gem::Specification.new do |spec|
   spec.name = "with_clues"
   spec.version = WithClues::VERSION
   spec.authors       = ["Dave Copeland"]
   spec.email         = ["davec@naildrivin5.com"]
-  spec.summary       = %q{WTF does this do?}
+  spec.summary       = %q{Temporarily add context to failing tests to get more information, such as what HTML was being examined when a browser-based test fails.}
   spec.homepage      = "https://sustainable-rails.com"
   spec.license       = "Hippocratic"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: with_clues
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Dave Copeland
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-04 00:00:00.000000000 Z
+date: 2024-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -73,28 +73,39 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".circleci/config.yml"
 - ".gitignore"
 - ".rspec"
 - ".tool-versions"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
+- Dockerfile.dx
 - Gemfile
 - LICENSE.md
 - README.md
 - Rakefile
 - bin/ci
 - bin/console
-- bin/mk_circle_config
-- bin/mk_gem
+- bin/matrix
 - bin/rake
 - bin/rspec
 - bin/setup
+- docker-compose.dx.yml
+- dx/build
+- dx/docker-compose.env
+- dx/dx.sh.lib
+- dx/exec
+- dx/prune
+- dx/setupkit.sh.lib
+- dx/show-help-in-app-container-then-wait.sh
+- dx/start
+- dx/stop
 - lib/with_clues.rb
 - lib/with_clues/browser_logs.rb
 - lib/with_clues/html.rb
 - lib/with_clues/method.rb
 - lib/with_clues/notifier.rb
+- lib/with_clues/private/custom_clue_method_analysis.rb
 - lib/with_clues/version.rb
 - with_clues.gemspec
 homepage: https://sustainable-rails.com
@@ -119,8 +130,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
-summary: WTF does this do?
+summary: Temporarily add context to failing tests to get more information, such as
+  what HTML was being examined when a browser-based test fails.
 test_files: []

data/.circleci/config.yml

@@ -1,98 +0,0 @@
-# THIS IS GENERATED - DO NOT EDIT
-# regenerate with bin/mk_circle_config
-# You are very welcome
----
-version: '2.1'
-jobs:
-  ruby__2_6:
-    docker:
-    - image: cimg/ruby:2.6
-    steps:
-    - checkout
-    - run:
-        name: Setup for build
-        command: bin/setup
-    - run:
-        name: Ensure bin/setup is idempotent
-        command: bin/setup
-    - run:
-        name: Create the test results dir
-        command: mkdir -p /tmp/test-results/2.6
-    - run:
-        name: Run all tests
-        command: bin/ci /tmp/test-results/2.6/rspec_results.xml
-    - store_test_results:
-        path: "/tmp/test-results/2.6"
-    - store_artifacts:
-        path: "/tmp/test-results/2.6"
-  ruby__2_7:
-    docker:
-    - image: cimg/ruby:2.7
-    steps:
-    - checkout
-    - run:
-        name: Setup for build
-        command: bin/setup
-    - run:
-        name: Ensure bin/setup is idempotent
-        command: bin/setup
-    - run:
-        name: Create the test results dir
-        command: mkdir -p /tmp/test-results/2.7
-    - run:
-        name: Run all tests
-        command: bin/ci /tmp/test-results/2.7/rspec_results.xml
-    - store_test_results:
-        path: "/tmp/test-results/2.7"
-    - store_artifacts:
-        path: "/tmp/test-results/2.7"
-  ruby__3_0:
-    docker:
-    - image: cimg/ruby:3.0
-    steps:
-    - checkout
-    - run:
-        name: Setup for build
-        command: bin/setup
-    - run:
-        name: Ensure bin/setup is idempotent
-        command: bin/setup
-    - run:
-        name: Create the test results dir
-        command: mkdir -p /tmp/test-results/3.0
-    - run:
-        name: Run all tests
-        command: bin/ci /tmp/test-results/3.0/rspec_results.xml
-    - store_test_results:
-        path: "/tmp/test-results/3.0"
-    - store_artifacts:
-        path: "/tmp/test-results/3.0"
-  ruby__3_1:
-    docker:
-    - image: cimg/ruby:3.1
-    steps:
-    - checkout
-    - run:
-        name: Setup for build
-        command: bin/setup
-    - run:
-        name: Ensure bin/setup is idempotent
-        command: bin/setup
-    - run:
-        name: Create the test results dir
-        command: mkdir -p /tmp/test-results/3.1
-    - run:
-        name: Run all tests
-        command: bin/ci /tmp/test-results/3.1/rspec_results.xml
-    - store_test_results:
-        path: "/tmp/test-results/3.1"
-    - store_artifacts:
-        path: "/tmp/test-results/3.1"
-workflows:
-  version: 2
-  all_rubies:
-    jobs:
-    - ruby__2_6
-    - ruby__2_7
-    - ruby__3_0
-    - ruby__3_1

data/bin/mk_circle_config

@@ -1,84 +0,0 @@
-#!/usr/bin/env ruby
-
-require "yaml"
-require "pathname"
-
-circle_config = {
-  "version" => "2.1",
-  "jobs" => {},
-  "workflows" => {
-    "version" => 2,
-    "all_rubies" => {
-      "jobs" => [
-      ],
-    },
-  }
-}
-
-supported_rubies = [
-  "2.6",
-  "2.7",
-  "3.0",
-  "3.1",
-]
-
-supported_rubies.each do |ruby_verison|
-
-  test_results_dir = "/tmp/test-results/#{ruby_verison}"
-  job_name = "ruby__#{ruby_verison.gsub(/\./,"_")}"
-
-  job = {
-    "docker" => [
-      {
-        "image" => "cimg/ruby:#{ruby_verison}",
-      }
-    ],
-    "steps" => [
-      "checkout",
-      {
-        "run" => {
-          "name" => "Setup for build",
-          "command" => "bin/setup",
-        }
-      },
-      {
-        "run" => {
-          "name" => "Ensure bin/setup is idempotent",
-          "command" => "bin/setup",
-        }
-      },
-      {
-        "run" => {
-          "name" => "Create the test results dir",
-          "command" => "mkdir -p #{test_results_dir}",
-        }
-      },
-      {
-        "run" => {
-          "name" => "Run all tests",
-          "command" => "bin/ci #{test_results_dir}/rspec_results.xml",
-        }
-      },
-      {
-        "store_test_results" => {
-          "path" => test_results_dir,
-        }
-      },
-      {
-        "store_artifacts" => {
-          "path" => test_results_dir,
-        }
-      },
-    ]
-  }
-  circle_config["jobs"][job_name] = job
-  circle_config["workflows"]["all_rubies"]["jobs"] << job_name
-end
-
-circle_config_file = (Pathname(__FILE__).dirname / ".." / ".circleci" / "config.yml").expand_path
-File.open(circle_config_file,"w") do |file|
-  file.puts "# THIS IS GENERATED - DO NOT EDIT"
-  file.puts "# regenerate with bin/mk_circle_config"
-  file.puts "# You are very welcome"
-  file.puts circle_config.to_yaml
-end

data/bin/mk_gem

@@ -1,73 +0,0 @@
-#!/usr/bin/env ruby
-
-require "fileutils"
-require "pathname"
-
-include FileUtils
-
-gem_name = ARGV[0]
-
-if gem_name.nil?
-  puts "usage: #{$0} gem_name"
-  exit 1
-end
-
-root = Pathname(__FILE__).dirname / ".."
-
-module_name = gem_name.split(/_/).map { |part|
-  part.capitalize
-}.join
-
-mkdir_p root / "lib"
-
-File.open(root / "lib" / "#{gem_name}.rb", "w") do |file|
-  file.puts "module #{module_name}"
-  file.puts "end"
-end
-
-mkdir_p root / "lib" / gem_name
-
-File.open(root / "lib" / gem_name / "version.rb", "w") do |file|
-  file.puts "module #{module_name}"
-  file.puts "  VERSION=\"1.0.0\""
-  file.puts "end"
-end
-
-gemspec = File.read("rubygem.gemspec")
-File.open(root / "#{gem_name}.gemspec","w") do |file|
-  file.puts "require_relative \"lib/#{gem_name}/version\""
-  file.puts
-  gemspec.split(/\n/).each do |line|
-    if line =~ /^\s*spec.name/
-      file.puts "  spec.name = \"#{gem_name}\""
-    elsif line =~ /^\s*spec.version/
-      file.puts "  spec.version = #{module_name}::VERSION"
-    elsif line.include?("«gem_name»")
-      file.puts line.gsub(/«gem_name»/,gem_name)
-    else
-      file.puts line
-    end
-  end
-end
-
-license = File.read(root / "LICENSE.md")
-File.open(root / "LICENSE.md","w") do |file|
-  license.split(/\n/).each_with_index do |line,index|
-    if index == 0
-      file.puts "[#{gem_name}] Copyright (2021) (David Copeland)(“Licensor”)"
-    else
-      file.puts line
-    end
-  end
-end
-
-readme = File.read(root / "README.md")
-File.open(root / "README.md","w") do |file|
-  license.split(/\n/).each_with_index do |line,index|
-    if index == 0
-      file.puts "# #{gem_name} - does a thing"
-    else
-      file.puts line
-    end
-  end
-end