Module: Mutineer::ReachProbe
- Defined in:
- lib/mutineer/reach_probe.rb
Overview
Records whether the expression that holds a mutation ran in the child.
Ruby counts one line of a statement. A mutant on another line is selected
as :maybe (#254, #289): the tests of the statement may not have reached
it. A kill is still a kill. A survivor used to stay no_coverage, because
the line count cannot tell "ran" from "did not run". The wrapper below
writes a sentinel when that expression runs, so a survivor that ran counts
as survived and one that did not stays no_coverage (#345).
The inserted text is stdlib only (File). The daemon loads it as source,
so the app process needs no Prism and no Mutineer constant.
Constant Summary collapse
- KEY_FORMAT =
A fiber-local key for one sentinel:
mutineer_rplus 16 hex digits.Thread.current[]is fiber-local, not one value for the whole thread. The generated source and forget_load use this key, not a fixed global, so an application variable of the same shape is not read or overwritten. The daemon checks the same pattern; it cannot load this file. /\Amutineer_r[0-9a-f]{16}\z/- CLIMB_STOP =
Nodes that must not be wrapped. Wrapping one records every run of the method or file, not the mutated expression.
[Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::ProgramNode, Prism::SingletonClassNode].freeze
Class Method Summary collapse
-
.climb_stops?(parent, child) ⇒ Boolean
private
True when wrapping
parentwould record a run of code that can run withoutchild: a conditional child, or a node that is a whole def, class, or file. -
.close_sentinel(sentinel) ⇒ void
Removes the sentinel file.
-
.forget_load(path, key) ⇒ void
Empties the sentinel after the mutant has loaded and before its tests run.
-
.parent_map(root) ⇒ Hash{Prism::Node => Prism::Node}
private
Parent of each node, by identity.
-
.reach_key ⇒ String
A new key for one mutant's sentinel.
-
.reached?(sentinel) ⇒ Boolean
Whether a test wrote the sentinel after ReachProbe.forget_load.
-
.sentinel ⇒ Tempfile
An empty sentinel file.
-
.smallest(node, start_offset, end_offset, best = nil) ⇒ Prism::Node?
private
The deepest node whose location holds the range.
-
.splice(source, node, path, key) ⇒ String
private
Replaces
nodewith an expression that writespathonly whennodereturns. -
.wrap(source, start_offset, end_offset, path, key) ⇒ String?
Wraps the smallest expression that holds the byte range
[start_offset, end_offset). -
.wrap_mutation(source, mutation, path, key) ⇒ String
The mutated source with a probe around the expression that holds the replacement, or
sourcewhenpathis nil.
Class Method Details
.climb_stops?(parent, child) ⇒ Boolean (private)
True when wrapping parent would record a run of code that can run
without child: a conditional child, or a node that is a whole def,
class, or file.
142 143 144 145 146 |
# File 'lib/mutineer/reach_probe.rb', line 142 def self.climb_stops?(parent, child) return true if CLIMB_STOP.any? { |klass| parent.is_a?(klass) } StatementLines.sometimes?(parent, child) end |
.close_sentinel(sentinel) ⇒ void
This method returns an undefined value.
Removes the sentinel file. A missing file is already gone.
73 74 75 76 77 78 79 80 |
# File 'lib/mutineer/reach_probe.rb', line 73 def self.close_sentinel(sentinel) return unless sentinel sentinel.close unless sentinel.closed? sentinel.unlink rescue Errno::ENOENT nil end |
.forget_load(path, key) ⇒ void
This method returns an undefined value.
Empties the sentinel after the mutant has loaded and before its tests run. A reload runs top-level calls, and those can reach the expression before any test does. That load is not a test reaching it (#345). The daemon does the same clear itself, because this file pulls in Prism and the daemon cannot.
62 63 64 65 66 67 |
# File 'lib/mutineer/reach_probe.rb', line 62 def self.forget_load(path, key) return unless path Thread.current[key.to_sym] = nil if key.to_s.match?(KEY_FORMAT) File.write(path, "") end |
.parent_map(root) ⇒ Hash{Prism::Node => Prism::Node} (private)
Parent of each node, by identity. A heredoc body is a child that lies outside its opener, so every child is recorded.
159 160 161 162 163 164 165 166 167 168 169 170 171 |
# File 'lib/mutineer/reach_probe.rb', line 159 def self.parent_map(root) map = {}.compare_by_identity walk = lambda do |node| return unless node.is_a?(Prism::Node) node.compact_child_nodes.each do |child| map[child] = node walk.call(child) end end walk.call(root) map end |
.reach_key ⇒ String
A new key for one mutant's sentinel.
31 32 33 |
# File 'lib/mutineer/reach_probe.rb', line 31 def self.reach_key "mutineer_r#{SecureRandom.hex(8)}" end |
.reached?(sentinel) ⇒ Boolean
Whether a test wrote the sentinel after forget_load. False when there is no sentinel, or the expression did not return during a test.
49 50 51 |
# File 'lib/mutineer/reach_probe.rb', line 49 def self.reached?(sentinel) !sentinel.nil? && File.size(sentinel.path).positive? end |
.sentinel ⇒ Tempfile
An empty sentinel file. The child writes "1" when the expression runs.
The caller checks reached? and then close_sentinel.
38 39 40 41 42 |
# File 'lib/mutineer/reach_probe.rb', line 38 def self.sentinel file = Tempfile.new(["mutineer-reach-", ".touch"]) file.close file end |
.smallest(node, start_offset, end_offset, best = nil) ⇒ Prism::Node? (private)
The deepest node whose location holds the range. A child replaces a parent of the same span, so a one-statement body wraps the statement and not the statement list around it. A heredoc body is a child that lies outside its opener, so every child is searched.
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 |
# File 'lib/mutineer/reach_probe.rb', line 184 def self.smallest(node, start_offset, end_offset, best = nil) return best unless node.is_a?(Prism::Node) loc = node.location span = loc.end_offset - loc.start_offset covers = if start_offset == end_offset loc.start_offset <= start_offset && start_offset < loc.end_offset else span.positive? && loc.start_offset <= start_offset && end_offset <= loc.end_offset end best = node if covers && (best.nil? || span <= (best.location.end_offset - best.location.start_offset)) node.compact_child_nodes.each do |child| best = smallest(child, start_offset, end_offset, best) end best end |
.splice(source, node, path, key) ⇒ String (private)
Replaces node with an expression that writes path only when node
returns. The mark is the second element of an array, so it does not run
when node raises. A one-line node stays one line. A node that spans
lines keeps its text and puts the array on the following lines, so the
indent warning stays quiet.
213 214 215 216 217 218 219 220 221 222 223 224 225 226 |
# File 'lib/mutineer/reach_probe.rb', line 213 def self.splice(source, node, path, key) loc = node.location inner = source.byteslice(loc.start_offset, loc.end_offset - loc.start_offset) quoted = path.dump # The fiber-local skips the write after the first return on this # fiber. A stat on every later pass would hit a loop. mark = "(Thread.current[:#{key}] ||= (::File.write(#{quoted}, \"1\"); true))" replacement = if inner.include?("\n") "\n[(#{inner}), #{mark}][0]" else "[(#{inner}), #{mark}][0]" end source.byteslice(0, loc.start_offset) + replacement + source.byteslice(loc.end_offset..) end |
.wrap(source, start_offset, end_offset, path, key) ⇒ String?
Wraps the smallest expression that holds the byte range [start_offset, end_offset). An empty range is the point where a deletion used to be.
Returns nil when no expression holds it, or the wrapped text does not
parse: a wrap that does not parse is not used.
The wrapper returns the expression's value. It writes the sentinel only after that value has come back, so a raise inside the expression — an operand that fails before a mutated operator runs — does not count as a run. Later returns on the same thread do not touch the file.
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 |
# File 'lib/mutineer/reach_probe.rb', line 116 def self.wrap(source, start_offset, end_offset, path, key) return nil unless key.to_s.match?(KEY_FORMAT) root = Parser.parse_string(source).value node = smallest(root, start_offset, end_offset) return nil unless node parents = parent_map(root) while node wrapped = splice(source, node, path, key) return wrapped unless Parser.invalid?(wrapped) parent = parents[node] break if parent.nil? || climb_stops?(parent, node) node = parent end nil end |
.wrap_mutation(source, mutation, path, key) ⇒ String
The mutated source with a probe around the expression that holds the
replacement, or source when path is nil. The original source when
the expression cannot be wrapped without changing how it parses: the
caller then has no evidence the expression ran, and a survivor stays
no_coverage.
93 94 95 96 97 98 |
# File 'lib/mutineer/reach_probe.rb', line 93 def self.wrap_mutation(source, mutation, path, key) return source if path.nil? || !key.to_s.match?(KEY_FORMAT) start = mutation.start_offset wrap(source, start, start + mutation.replacement.bytesize, path, key) || source end |