forge/
coverage.rs

1//! Coverage reports.
2
3use alloy_primitives::map::{HashMap, HashSet};
4use comfy_table::{
5    Attribute, Cell, Color, Row, Table, modifiers::UTF8_ROUND_CORNERS, presets::ASCII_MARKDOWN,
6};
7use evm_disassembler::disassemble_bytes;
8use foundry_common::{fs, shell};
9use semver::Version;
10use std::{
11    collections::hash_map,
12    io::Write,
13    path::{Path, PathBuf},
14};
15
16pub use foundry_evm::coverage::*;
17
18/// A coverage reporter.
19pub trait CoverageReporter {
20    /// Returns a debug string for the reporter.
21    fn name(&self) -> &'static str;
22
23    /// Returns `true` if the reporter needs source maps for the final report.
24    fn needs_source_maps(&self) -> bool {
25        false
26    }
27
28    /// Runs the reporter.
29    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()>;
30}
31
32/// A simple summary reporter that prints the coverage results in a table.
33pub struct CoverageSummaryReporter {
34    /// The summary table.
35    table: Table,
36    /// The total coverage of the entire project.
37    total: CoverageSummary,
38}
39
40impl Default for CoverageSummaryReporter {
41    fn default() -> Self {
42        let mut table = Table::new();
43        if shell::is_markdown() {
44            table.load_preset(ASCII_MARKDOWN);
45        } else {
46            table.apply_modifier(UTF8_ROUND_CORNERS);
47        }
48
49        table.set_header(vec![
50            Cell::new("File"),
51            Cell::new("% Lines"),
52            Cell::new("% Statements"),
53            Cell::new("% Branches"),
54            Cell::new("% Funcs"),
55        ]);
56
57        Self { table, total: CoverageSummary::default() }
58    }
59}
60
61impl CoverageSummaryReporter {
62    fn add_row(&mut self, name: impl Into<Cell>, summary: CoverageSummary) {
63        let mut row = Row::new();
64        row.add_cell(name.into())
65            .add_cell(format_cell(summary.line_hits, summary.line_count))
66            .add_cell(format_cell(summary.statement_hits, summary.statement_count))
67            .add_cell(format_cell(summary.branch_hits, summary.branch_count))
68            .add_cell(format_cell(summary.function_hits, summary.function_count));
69        self.table.add_row(row);
70    }
71}
72
73impl CoverageReporter for CoverageSummaryReporter {
74    fn name(&self) -> &'static str {
75        "summary"
76    }
77
78    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()> {
79        for (path, summary) in report.summary_by_file() {
80            self.total.merge(&summary);
81            self.add_row(path.display(), summary);
82        }
83
84        self.add_row("Total", self.total.clone());
85        sh_println!("\n{}", self.table)?;
86        Ok(())
87    }
88}
89
90fn format_cell(hits: usize, total: usize) -> Cell {
91    let percentage = if total == 0 { 1. } else { hits as f64 / total as f64 };
92
93    let mut cell =
94        Cell::new(format!("{:.2}% ({hits}/{total})", percentage * 100.)).fg(match percentage {
95            _ if total == 0 => Color::Grey,
96            _ if percentage < 0.5 => Color::Red,
97            _ if percentage < 0.75 => Color::Yellow,
98            _ => Color::Green,
99        });
100
101    if total == 0 {
102        cell = cell.add_attribute(Attribute::Dim);
103    }
104    cell
105}
106
107/// Writes the coverage report in [LCOV]'s [tracefile format].
108///
109/// [LCOV]: https://github.com/linux-test-project/lcov
110/// [tracefile format]: https://man.archlinux.org/man/geninfo.1.en#TRACEFILE_FORMAT
111pub struct LcovReporter {
112    path: PathBuf,
113    version: Version,
114}
115
116impl LcovReporter {
117    /// Create a new LCOV reporter.
118    pub fn new(path: PathBuf, version: Version) -> Self {
119        Self { path, version }
120    }
121}
122
123impl CoverageReporter for LcovReporter {
124    fn name(&self) -> &'static str {
125        "lcov"
126    }
127
128    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()> {
129        let mut out = std::io::BufWriter::new(fs::create_file(&self.path)?);
130
131        let mut fn_index = 0usize;
132        for (path, items) in report.items_by_file() {
133            let summary = CoverageSummary::from_items(items.iter().copied());
134
135            writeln!(out, "TN:")?;
136            writeln!(out, "SF:{}", path.display())?;
137
138            let mut recorded_lines = HashSet::new();
139
140            for item in items {
141                let line = item.loc.lines.start;
142                // `lines` is half-open, so we need to subtract 1 to get the last included line.
143                let end_line = item.loc.lines.end - 1;
144                let hits = item.hits;
145                match item.kind {
146                    CoverageItemKind::Function { ref name } => {
147                        let name = format!("{}.{name}", item.loc.contract_name);
148                        if self.version >= Version::new(2, 2, 0) {
149                            // v2.2 changed the FN format.
150                            writeln!(out, "FNL:{fn_index},{line},{end_line}")?;
151                            writeln!(out, "FNA:{fn_index},{hits},{name}")?;
152                            fn_index += 1;
153                        } else if self.version >= Version::new(2, 0, 0) {
154                            // v2.0 added end_line to FN.
155                            writeln!(out, "FN:{line},{end_line},{name}")?;
156                            writeln!(out, "FNDA:{hits},{name}")?;
157                        } else {
158                            writeln!(out, "FN:{line},{name}")?;
159                            writeln!(out, "FNDA:{hits},{name}")?;
160                        }
161                    }
162                    // Add lines / statement hits only once.
163                    CoverageItemKind::Line | CoverageItemKind::Statement => {
164                        if recorded_lines.insert(line) {
165                            writeln!(out, "DA:{line},{hits}")?;
166                        }
167                    }
168                    CoverageItemKind::Branch { branch_id, path_id, .. } => {
169                        writeln!(
170                            out,
171                            "BRDA:{line},{branch_id},{path_id},{}",
172                            if hits == 0 { "-".to_string() } else { hits.to_string() }
173                        )?;
174                    }
175                }
176            }
177
178            // Function summary
179            writeln!(out, "FNF:{}", summary.function_count)?;
180            writeln!(out, "FNH:{}", summary.function_hits)?;
181
182            // Line summary
183            writeln!(out, "LF:{}", summary.line_count)?;
184            writeln!(out, "LH:{}", summary.line_hits)?;
185
186            // Branch summary
187            writeln!(out, "BRF:{}", summary.branch_count)?;
188            writeln!(out, "BRH:{}", summary.branch_hits)?;
189
190            writeln!(out, "end_of_record")?;
191        }
192
193        out.flush()?;
194        sh_println!("Wrote LCOV report.")?;
195
196        Ok(())
197    }
198}
199
200/// A super verbose reporter for debugging coverage while it is still unstable.
201pub struct DebugReporter;
202
203impl CoverageReporter for DebugReporter {
204    fn name(&self) -> &'static str {
205        "debug"
206    }
207
208    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()> {
209        for (path, items) in report.items_by_file() {
210            let uncovered = items.iter().copied().filter(|item| item.hits == 0);
211            if uncovered.clone().count() == 0 {
212                continue;
213            }
214
215            sh_println!("Uncovered for {}:", path.display())?;
216            for item in uncovered {
217                sh_println!("- {item}")?;
218            }
219            sh_println!()?;
220        }
221
222        for (contract_id, (cta, rta)) in &report.anchors {
223            if cta.is_empty() && rta.is_empty() {
224                continue;
225            }
226
227            sh_println!("Anchors for {contract_id}:")?;
228            let anchors = cta
229                .iter()
230                .map(|anchor| (false, anchor))
231                .chain(rta.iter().map(|anchor| (true, anchor)));
232            for (is_runtime, anchor) in anchors {
233                let kind = if is_runtime { " runtime" } else { "creation" };
234                sh_println!(
235                    "- {kind} {anchor}: {}",
236                    report
237                        .analyses
238                        .get(&contract_id.version)
239                        .and_then(|items| items.get(anchor.item_id))
240                        .map_or_else(|| "None".to_owned(), |item| item.to_string())
241                )?;
242            }
243            sh_println!()?;
244        }
245
246        Ok(())
247    }
248}
249
250pub struct BytecodeReporter {
251    root: PathBuf,
252    destdir: PathBuf,
253}
254
255impl BytecodeReporter {
256    pub fn new(root: PathBuf, destdir: PathBuf) -> Self {
257        Self { root, destdir }
258    }
259}
260
261impl CoverageReporter for BytecodeReporter {
262    fn name(&self) -> &'static str {
263        "bytecode"
264    }
265
266    fn needs_source_maps(&self) -> bool {
267        true
268    }
269
270    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()> {
271        use std::fmt::Write;
272
273        fs::create_dir_all(&self.destdir)?;
274
275        let no_source_elements = Vec::new();
276        let mut line_number_cache = LineNumberCache::new(self.root.clone());
277
278        for (contract_id, hits) in &report.bytecode_hits {
279            let ops = disassemble_bytes(hits.bytecode().to_vec())?;
280            let mut formatted = String::new();
281
282            let source_elements =
283                report.source_maps.get(contract_id).map(|sm| &sm.1).unwrap_or(&no_source_elements);
284
285            for (code, source_element) in std::iter::zip(ops.iter(), source_elements) {
286                let hits = hits
287                    .get(code.offset)
288                    .map(|h| format!("[{h:03}]"))
289                    .unwrap_or("     ".to_owned());
290                let source_id = source_element.index();
291                let source_path = source_id.and_then(|i| {
292                    report.source_paths.get(&(contract_id.version.clone(), i as usize))
293                });
294
295                let code = format!("{code:?}");
296                let start = source_element.offset() as usize;
297                let end = (source_element.offset() + source_element.length()) as usize;
298
299                if let Some(source_path) = source_path {
300                    let (sline, spos) = line_number_cache.get_position(source_path, start)?;
301                    let (eline, epos) = line_number_cache.get_position(source_path, end)?;
302                    writeln!(
303                        formatted,
304                        "{} {:40} // {}: {}:{}-{}:{} ({}-{})",
305                        hits,
306                        code,
307                        source_path.display(),
308                        sline,
309                        spos,
310                        eline,
311                        epos,
312                        start,
313                        end
314                    )?;
315                } else if let Some(source_id) = source_id {
316                    writeln!(formatted, "{hits} {code:40} // SRCID{source_id}: ({start}-{end})")?;
317                } else {
318                    writeln!(formatted, "{hits} {code:40}")?;
319                }
320            }
321            fs::write(
322                self.destdir.join(&*contract_id.contract_name).with_extension("asm"),
323                formatted,
324            )?;
325        }
326
327        Ok(())
328    }
329}
330
331/// Cache line number offsets for source files
332struct LineNumberCache {
333    root: PathBuf,
334    line_offsets: HashMap<PathBuf, Vec<usize>>,
335}
336
337impl LineNumberCache {
338    pub fn new(root: PathBuf) -> Self {
339        Self { root, line_offsets: HashMap::default() }
340    }
341
342    pub fn get_position(&mut self, path: &Path, offset: usize) -> eyre::Result<(usize, usize)> {
343        let line_offsets = match self.line_offsets.entry(path.to_path_buf()) {
344            hash_map::Entry::Occupied(o) => o.into_mut(),
345            hash_map::Entry::Vacant(v) => {
346                let text = fs::read_to_string(self.root.join(path))?;
347                let mut line_offsets = vec![0];
348                for line in text.lines() {
349                    let line_offset = line.as_ptr() as usize - text.as_ptr() as usize;
350                    line_offsets.push(line_offset);
351                }
352                v.insert(line_offsets)
353            }
354        };
355        let lo = match line_offsets.binary_search(&offset) {
356            Ok(lo) => lo,
357            Err(lo) => lo - 1,
358        };
359        let pos = offset - line_offsets.get(lo).unwrap() + 1;
360        Ok((lo, pos))
361    }
362}
forge/coverage.rs

forge/
coverage.rs
