nukadoko 0.1.0

data/lib/nukadoko/definition.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# What the TypeScript engine's defineStep refuses when a step file loads:
+# a claim or a poll that could only be judged one way, or that would let a
+# line fill the value a claim measures. The Ruby engine reads the same
+# declarations after loading, and check reports each as the TypeScript
+# engine does, as step-file-import-failed, so the step leaves the vocabulary.
+module Nukadoko
+  module Engine
+    class Definition
+      def initialize(step)
+        @step = step
+        @from = step.from.keys
+        @captures = step.pattern ? Pattern.new(step.pattern).keys : []
+        @args = step.args.fields.map { _1.name.to_s }
+        @observe = step.method_defined?(:observe)
+      end
+
+      def problems
+        return [] unless @step.claims
+
+        claim_problems + poll_problems
+      end
+
+      private
+
+      def claim_problems
+        @step.claims.each_with_index.flat_map do |claim, i|
+          label = "claims[#{i}]"
+          actual_problems(label, claim) + expected_problems(label, claim)
+        end
+      end
+
+      def actual_problems(label, claim)
+        head = claim[:actual].to_s.split(".").first
+        from = @from.include?(head)
+        if !from && !@observe
+          [%(#{label}.actual starts with "#{head}", which is not a key of this step's from, and the step has no observe to read it)]
+        elsif from && @captures.include?(head)
+          [%(#{label}.actual starts with "#{head}", which a pattern captures, so a line would fill the value the claim measures. Take it out of the pattern, so an earlier step fills it)]
+        elsif !from && @args.include?(head)
+          [%(#{label}.actual starts with "#{head}", an args key the sentence fills. A claim's actual is a value an earlier step returned (a from key) or one observe read)]
+        else []
+        end
+      end
+
+      def expected_problems(label, claim)
+        key = claim[:expected].is_a?(Hash) && claim[:expected][:from]&.to_s&.split(".")&.first
+        return [] unless key
+        return [%(#{label}.expected.from starts with "#{key}", which is not a key of this step's from)] unless @from.include?(key)
+        return [%(#{label}.expected.from starts with "#{key}", which a pattern captures, so a line fills it and no earlier step does)] if @captures.include?(key)
+
+        []
+      end
+
+      def poll_problems
+        poll = @step.poll
+        return [] if poll.nil? || poll == false
+        unless poll.is_a?(Hash) && (poll.keys - %i[timeout_ms settled]).empty? && poll[:timeout_ms].is_a?(Numeric) && poll[:timeout_ms].positive?
+          return ["poll must be false or { timeout_ms, settled? } with a number of milliseconds greater than 0; got #{poll.inspect}"]
+        end
+        return ["poll re-runs observe, and the step has no observe. Values from earlier steps do not change between readings"] unless @observe
+
+        []
+      end
+    end
+  end
+end

data/lib/nukadoko/features.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "gherkin"
+
+# Feature files become pickles through the official gherkin gem. A pickle
+# from an outline is named by its Examples row's line, and its steps by the
+# outline's step lines, as the TypeScript engine names them.
+module Nukadoko
+  module Engine
+    # `keyword_line` is the Scenario keyword's own line, the same for every
+    # row of an outline. A step from a Background has `background` set.
+    Scenario = Data.define(:uri, :line, :keyword_line, :name, :tags, :steps)
+    PickleStep = Data.define(:text, :line, :kind, :table, :doc_string, :background)
+
+    def self.load_features(dir)
+      paths = Dir.glob(File.join(dir, "**/*.feature")).sort
+      lines = {}
+      background = {}
+      scenarios = []
+      Gherkin.from_paths(paths, include_source: false, include_gherkin_document: true, include_pickles: true).each do |envelope|
+        if (doc = envelope.gherkin_document)
+          collect_lines(doc.feature, lines, background) if doc.feature
+        elsif (pickle = envelope.pickle)
+          steps = pickle.steps.map do |step|
+            table = step.argument&.data_table&.rows&.map { |row| row.cells.map(&:value) }
+            PickleStep.new(step.text, lines.fetch(step.ast_node_ids.first), step.type, table, step.argument&.doc_string&.content,
+                           background.key?(step.ast_node_ids.first))
+          end
+          scenarios << Scenario.new(pickle.uri, lines.fetch(pickle.ast_node_ids.last), lines.fetch(pickle.ast_node_ids.first),
+                                    pickle.name, pickle.tags.map(&:name), steps)
+        end
+      end
+      scenarios
+    end
+
+    def self.collect_lines(node, lines, background)
+      node.children.each do |child|
+        next collect_lines(child.rule, lines, background) if child.rule
+
+        scenario = child.scenario || child.background
+        next unless scenario
+
+        lines[scenario.id] = scenario.location.line if child.scenario
+        scenario.steps.each { |step| lines[step.id] = step.location.line }
+        child.background&.steps&.each { |step| background[step.id] = true }
+        child.scenario&.examples&.each { |examples| examples.table_body.each { |row| lines[row.id] = row.location.line } }
+      end
+    end
+  end
+end

data/lib/nukadoko/fixtures.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+# Fixtures are built by the engine, not the step, so what they record is
+# measured: every request a step sends goes through Request and lands in the
+# step's http.jsonl as it was sent and answered.
+module Nukadoko
+  module Engine
+    Response = Data.define(:status, :headers, :body) do
+      def json = JSON.parse(body)
+      def ok? = status.between?(200, 299)
+    end
+
+    class Request
+      attr_reader :log
+
+      def initialize(base_url)
+        @base = URI(base_url)
+        @log = []
+      end
+
+      %w[get post put patch delete].each do |verb|
+        # `data:` is sent as JSON; `body:` is sent as it is, for a request
+        # whose body is meant to be wrong.
+        define_method(verb) do |path, data: nil, body: nil, headers: {}|
+          uri = URI.join(@base, path)
+          klass = Net::HTTP.const_get(verb.capitalize)
+          req = klass.new(uri, headers)
+          if data
+            req["content-type"] = "application/json"
+            req.body = JSON.generate(data)
+          end
+          req.body = body if body
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          res = Net::HTTP.start(uri.host, uri.port) { _1.request(req) }
+          @log << { method: verb.upcase, url: uri.to_s, request_body: req.body, status: res.code.to_i,
+                    response_body: res.body, ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1) }
+          Response.new(res.code.to_i, res.to_hash, res.body.to_s)
+        end
+      end
+    end
+
+    # Opened only for a step whose body names page or context, as in the
+    # TypeScript engine. Requests the page sends are recorded by the engine's
+    # own listener, and each step gets a trace chunk.
+    class Browser
+      def initialize(base_url, launch_options = {})
+        @base_url = base_url
+        @launch_options = launch_options
+      end
+
+      def page_for(step_dir, log)
+        require "playwright"
+        @execution ||= Playwright.create(playwright_cli_executable_path: ENV.fetch("PLAYWRIGHT_CLI", "npx playwright"))
+        @browser ||= @execution.playwright.chromium.launch(**@launch_options)
+        @context ||= @browser.new_context(baseURL: @base_url).tap { _1.tracing.start(screenshots: true, snapshots: true) }
+        @page ||= @context.new_page
+        @context.tracing.start_chunk
+        listener = ->(req) { log << { method: req.method, url: req.url, from: "page" } }
+        @page.on("request", listener)
+        [@page, -> { @page.off("request", listener); @context.tracing.stop_chunk(path: File.join(step_dir, "trace.zip")) }]
+      end
+
+      # Each scenario gets a browser context of its own, so cookies and storage
+      # never carry from one scenario to the next.
+      def end_scenario
+        @context&.tracing&.stop
+        @context&.close
+        @context = @page = nil
+      end
+
+      def close
+        @browser&.close
+        @execution&.stop
+      end
+    end
+  end
+end

data/lib/nukadoko/parts.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "time"
+
+# The `call` fixture: a step runs one of the parts it declares, with args it
+# supplies itself (a call never reads `from`). The part's args and returns
+# are checked as a scenario line's are, and each call lands under `calls` in
+# the calling step's record, nested when a part calls a part of its own.
+module Nukadoko
+  module Engine
+    class Caller
+      # Raised for a call the declaration does not allow, so the step fails
+      # as broken rather than as a claim that did not hold.
+      class Refused < StandardError; end
+
+      attr_reader :calls
+
+      def initialize(step, fixtures)
+        @fixtures = fixtures
+        @stack = [step]
+        @calls = []
+        @into = [@calls]
+      end
+
+      def to_proc = method(:call).to_proc
+
+      def call(part, args = {}, **keywords)
+        caller = @stack.last
+        unless part.is_a?(Class) && part < Step && caller.parts.include?(part)
+          raise Refused, "#{caller.step_name} calls #{part.respond_to?(:step_name) ? part.step_name : part.inspect}, which its parts do not declare"
+        end
+
+        args = args.merge(keywords).transform_keys(&:to_s)
+        entry = { part: part.step_name, args: args, started_at: Time.now.utc.iso8601(3) }
+        @into.last << entry
+        run(part, args, entry)
+      ensure
+        entry[:finished_at] = Time.now.utc.iso8601(3) if entry
+      end
+
+      private
+
+      def run(part, args, entry)
+        problems = part.args.problems(args)
+        raise TypeError, "args of #{part.step_name}: #{problems.join("; ")}" if problems.any?
+
+        @stack << part
+        @into << (entry[:calls] = [])
+        value = part.new.run(**@fixtures.slice(*part.fixtures), args: part.inputs.load(args))
+        problems = part.returns ? part.returns.problems(value) : []
+        raise TypeError, "returns of #{part.step_name}: #{problems.join("; ")}" if problems.any?
+
+        value = part.returns.strip(value) if part.returns
+        entry[:result] = value
+        part.returns ? part.returns.load(value) : value
+      rescue StandardError => e
+        entry[:error] ||= "#{e.class}: #{e.message}"
+        raise
+      ensure
+        if @stack.last == part
+          @stack.pop
+          @into.pop
+          entry.delete(:calls) if entry[:calls]&.empty?
+        end
+      end
+    end
+  end
+end

data/lib/nukadoko/pattern.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "cucumber/cucumber_expressions/cucumber_expression"
+require "cucumber/cucumber_expressions/parameter_type_registry"
+
+# A pattern names every capture (`{title:string}`). The names are stripped and
+# the plain expression goes to the official cucumber-expressions gem, so the
+# syntax owner is the same one the TypeScript engine uses.
+module Nukadoko
+  module Engine
+    class Pattern
+      NAMED = /\{([A-Za-z_][\w-]*):([\w-]+)\}/
+      REGISTRY = Cucumber::CucumberExpressions::ParameterTypeRegistry.new
+
+      attr_reader :source, :keys
+
+      def initialize(source)
+        @source = source
+        @keys = source.scan(NAMED).map(&:first)
+        @expression = Cucumber::CucumberExpressions::CucumberExpression.new(source.gsub(NAMED, '{\2}'), REGISTRY)
+      end
+
+      def match(text)
+        found = @expression.match(text)
+        found && keys.zip(found.map { _1.value(nil) }).to_h
+      end
+    end
+  end
+end

data/lib/nukadoko/poll.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "time"
+
+# `poll timeout_ms: 3000` reads `observe` again, 100 ms apart, until every
+# claim holds on two consecutive readings or the timeout passes. One holding
+# reading is never enough: a page between two renders can show the expected
+# state for one frame. `settled:` names a state that cannot change once
+# reached, so two consecutive settled readings stop the wait for a claim
+# that broke on it. The last reading is what the step judges, and every
+# reading lands in the step record, because an observe that counts its
+# calls could walk toward the expected value.
+module Nukadoko
+  module Engine
+    class Poll
+      INTERVAL = 0.1
+
+      def initialize(options, claims, args)
+        @timeout = options.fetch(:timeout_ms) / 1000.0
+        @settled = options[:settled] || []
+        @claims = claims
+        @args = args
+      end
+
+      # A reading whose observe raised is kept with the first line of the
+      # error, and the poll reads again; only a last reading that raised
+      # fails the step with that error.
+      def call(record)
+        deadline = monotonic + @timeout
+        readings = []
+        stop = nil
+        begin
+          loop do
+            readings << read(readings.size + 1) { yield }
+            stop = stop_for(readings)
+            break if stop || monotonic + INTERVAL > deadline
+
+            sleep INTERVAL
+          end
+        ensure
+          record[:readings] = readings.map { _1.except(:value, :raised) }
+          record[:poll] = { readings: readings.size, stop: stop || "timeout" }
+        end
+        raise readings.last[:raised] if readings.last[:raised]
+
+        readings.last[:value]
+      end
+
+      private
+
+      def read(attempt)
+        judge(yield, attempt)
+      rescue StandardError => e
+        { attempt: attempt, at: Time.now.utc.iso8601(3), holds: false, error: "#{e.class}: #{e.message.lines.first&.chomp}", raised: e }
+      end
+
+      def judge(value, attempt)
+        judged = Claims.judge(@claims, value, @args)
+        reading = { attempt: attempt, at: Time.now.utc.iso8601(3), holds: judged.all? { _1[:holds] }, actuals: judged.map { _1[:actual] }, value: value }
+        reading[:settled] = @settled.all? { Claims.judge_one(_1, value, {})[:holds] } if @settled.any?
+        reading
+      end
+
+      def stop_for(readings)
+        last, before = readings.last(2).reverse
+        return nil unless before
+        return "held" if last[:holds] && before[:holds]
+
+        "settled" if last[:settled] && before[:settled]
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/nukadoko/program.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "socket"
+require "net/http"
+
+# How the program under test starts, once per environment: an environment
+# is a world of its own, with its own port, directory, and process, so one
+# environment's state never reaches another's scenarios.
+module Nukadoko
+  module Engine
+    Environment = Data.define(:name, :conditions, :env)
+
+    class Program
+      def initialize(options)
+        @options = options
+      end
+
+      def environments
+        declared = @options[:environments]
+        return [Environment.new("default", {}, {})] unless declared
+
+        declared.map { |name, e| Environment.new(name.to_s, (e[:conditions] || {}).transform_keys(&:to_s), e[:env] || {}) }
+      end
+
+      def start(environment, dir, project)
+        return World.new(@options[:base_url], nil, nil) unless @options[:serve]
+
+        port = TCPServer.open("127.0.0.1", 0) { _1.addr[1] }
+        fill = ->(text) { placeholders(text.to_s, port, dir, environment) }
+        env = (@options[:env] || {}).merge(environment.env).to_h { |k, v| [k.to_s, fill.(v)] }
+        log = File.open(File.join(dir, "program.log"), "w")
+        pid = Process.spawn(env, fill.(@options[:serve][:command]), out: log, err: log, pgroup: true, chdir: project)
+        world = World.new("http://127.0.0.1:#{port}", pid, log)
+        world.wait_ready(@options[:serve][:ready])
+        world
+      end
+
+      private
+
+      def placeholders(text, port, dir, environment)
+        text.gsub("{port}", port.to_s).gsub("{dir}", dir).gsub(/\{condition\.([\w.-]+)\}/) do
+          environment.conditions.fetch(Regexp.last_match(1), "").to_s
+        end
+      end
+    end
+
+    World = Data.define(:base_url, :pid, :log) do
+      def wait_ready(path)
+        uri = URI.join(base_url, path)
+        deadline = Time.now + 30
+        begin
+          Net::HTTP.get_response(uri)
+        rescue SystemCallError
+          raise "the program did not answer #{uri} within 30s" if Time.now > deadline
+
+          sleep 0.1
+          retry
+        end
+      end
+
+      def stop
+        Process.kill("TERM", -pid) if pid
+        Process.wait(pid) if pid
+        log&.close
+      rescue Errno::ESRCH, Errno::ECHILD
+        log&.close
+      end
+    end
+  end
+end

data/lib/nukadoko/project_fixtures.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Fixtures a project declares in nukadoko.config.rb. A fixture block gets
+# `use` and calls it with the value; whatever follows that call is the
+# teardown, as with Playwright's `use()`. The block runs in a Fiber, so the
+# teardown waits until the scope ends, and runs whether the steps passed.
+#
+#   Nukadoko.fixture(:store) { |use| use.(Signup::Store.new) }
+#   Nukadoko.fixture(:db, scope: :process) { |use, env:| db = connect(env); use.(db); db.close }
+module Nukadoko
+  Fixture = Data.define(:name, :scope, :block) do
+    def dependencies = block.parameters.filter_map { |kind, n| n if kind == :keyreq }
+  end
+
+  def self.fixture(name, scope: :scenario, &block)
+    raise ArgumentError, "scope is :scenario or :process, not #{scope.inspect}" unless %i[scenario process].include?(scope)
+
+    project_fixtures[name.to_sym] = Fixture.new(name.to_sym, scope, block)
+  end
+
+  def self.project_fixtures = (@project_fixtures ||= {})
+
+  module Engine
+    # One scope's built fixtures, torn down in reverse build order.
+    class FixtureCache
+      def initialize
+        @values = {}
+        @fibers = []
+      end
+
+      def key?(name) = @values.key?(name)
+      def [](name) = @values.fetch(name)
+
+      def build(fixture, deps)
+        fiber = Fiber.new do
+          fixture.block.call(->(value) { Fiber.yield(value) }, **deps)
+          :done
+        end
+        value = fiber.resume
+        raise "fixture #{fixture.name} returned without calling use" if value == :done && !fiber.alive?
+
+        @fibers << fiber
+        @values[fixture.name] = value
+      end
+
+      # Every teardown runs; the first failure is raised after the rest.
+      def teardown
+        failure = nil
+        @fibers.reverse_each do |fiber|
+          fiber.resume if fiber.alive?
+        rescue StandardError => e
+          failure ||= e
+        end
+        @fibers.clear
+        @values.clear
+        raise failure if failure
+      end
+    end
+  end
+end