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                        let hits = if hits == 0 { "-" } else { &hits.to_string() };
170                        writeln!(out, "BRDA:{line},{branch_id},{path_id},{hits}")?;
171                    }
172                }
173            }
174
175            // Function summary
176            writeln!(out, "FNF:{}", summary.function_count)?;
177            writeln!(out, "FNH:{}", summary.function_hits)?;
178
179            // Line summary
180            writeln!(out, "LF:{}", summary.line_count)?;
181            writeln!(out, "LH:{}", summary.line_hits)?;
182
183            // Branch summary
184            writeln!(out, "BRF:{}", summary.branch_count)?;
185            writeln!(out, "BRH:{}", summary.branch_hits)?;
186
187            writeln!(out, "end_of_record")?;
188        }
189
190        out.flush()?;
191        sh_println!("Wrote LCOV report.")?;
192
193        Ok(())
194    }
195}
196
197/// A super verbose reporter for debugging coverage while it is still unstable.
198pub struct DebugReporter;
199
200impl CoverageReporter for DebugReporter {
201    fn name(&self) -> &'static str {
202        "debug"
203    }
204
205    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()> {
206        for (path, items) in report.items_by_file() {
207            let src = fs::read_to_string(path)?;
208            sh_println!("{}:", path.display())?;
209            for item in items {
210                sh_println!("- {}", item.fmt_with_source(Some(&src)))?;
211            }
212            sh_println!()?;
213        }
214
215        for (contract_id, (cta, rta)) in &report.anchors {
216            if cta.is_empty() && rta.is_empty() {
217                continue;
218            }
219
220            sh_println!("Anchors for {contract_id}:")?;
221            let anchors = cta
222                .iter()
223                .map(|anchor| (false, anchor))
224                .chain(rta.iter().map(|anchor| (true, anchor)));
225            for (is_runtime, anchor) in anchors {
226                let kind = if is_runtime { " runtime" } else { "creation" };
227                sh_println!(
228                    "- {kind} {anchor}: {}",
229                    report
230                        .analyses
231                        .get(&contract_id.version)
232                        .and_then(|items| items.get(anchor.item_id))
233                        .map_or_else(|| "None".to_owned(), |item| item.to_string())
234                )?;
235            }
236            sh_println!()?;
237        }
238
239        Ok(())
240    }
241}
242
243pub struct BytecodeReporter {
244    root: PathBuf,
245    destdir: PathBuf,
246}
247
248impl BytecodeReporter {
249    pub fn new(root: PathBuf, destdir: PathBuf) -> Self {
250        Self { root, destdir }
251    }
252}
253
254impl CoverageReporter for BytecodeReporter {
255    fn name(&self) -> &'static str {
256        "bytecode"
257    }
258
259    fn needs_source_maps(&self) -> bool {
260        true
261    }
262
263    fn report(&mut self, report: &CoverageReport) -> eyre::Result<()> {
264        use std::fmt::Write;
265
266        fs::create_dir_all(&self.destdir)?;
267
268        let no_source_elements = Vec::new();
269        let mut line_number_cache = LineNumberCache::new(self.root.clone());
270
271        for (contract_id, hits) in &report.bytecode_hits {
272            let ops = disassemble_bytes(hits.bytecode().to_vec())?;
273            let mut formatted = String::new();
274
275            let source_elements =
276                report.source_maps.get(contract_id).map(|sm| &sm.1).unwrap_or(&no_source_elements);
277
278            for (code, source_element) in std::iter::zip(ops.iter(), source_elements) {
279                let hits = hits
280                    .get(code.offset)
281                    .map(|h| format!("[{h:03}]"))
282                    .unwrap_or("     ".to_owned());
283                let source_id = source_element.index();
284                let source_path = source_id.and_then(|i| {
285                    report.source_paths.get(&(contract_id.version.clone(), i as usize))
286                });
287
288                let code = format!("{code:?}");
289                let start = source_element.offset() as usize;
290                let end = (source_element.offset() + source_element.length()) as usize;
291
292                if let Some(source_path) = source_path {
293                    let (sline, spos) = line_number_cache.get_position(source_path, start)?;
294                    let (eline, epos) = line_number_cache.get_position(source_path, end)?;
295                    writeln!(
296                        formatted,
297                        "{} {:40} // {}: {}:{}-{}:{} ({}-{})",
298                        hits,
299                        code,
300                        source_path.display(),
301                        sline,
302                        spos,
303                        eline,
304                        epos,
305                        start,
306                        end
307                    )?;
308                } else if let Some(source_id) = source_id {
309                    writeln!(formatted, "{hits} {code:40} // SRCID{source_id}: ({start}-{end})")?;
310                } else {
311                    writeln!(formatted, "{hits} {code:40}")?;
312                }
313            }
314            fs::write(
315                self.destdir.join(&*contract_id.contract_name).with_extension("asm"),
316                formatted,
317            )?;
318        }
319
320        Ok(())
321    }
322}
323
324/// Cache line number offsets for source files
325struct LineNumberCache {
326    root: PathBuf,
327    line_offsets: HashMap<PathBuf, Vec<usize>>,
328}
329
330impl LineNumberCache {
331    pub fn new(root: PathBuf) -> Self {
332        Self { root, line_offsets: HashMap::default() }
333    }
334
335    pub fn get_position(&mut self, path: &Path, offset: usize) -> eyre::Result<(usize, usize)> {
336        let line_offsets = match self.line_offsets.entry(path.to_path_buf()) {
337            hash_map::Entry::Occupied(o) => o.into_mut(),
338            hash_map::Entry::Vacant(v) => {
339                let text = fs::read_to_string(self.root.join(path))?;
340                let mut line_offsets = vec![0];
341                for line in text.lines() {
342                    let line_offset = line.as_ptr() as usize - text.as_ptr() as usize;
343                    line_offsets.push(line_offset);
344                }
345                v.insert(line_offsets)
346            }
347        };
348        let lo = match line_offsets.binary_search(&offset) {
349            Ok(lo) => lo,
350            Err(lo) => lo - 1,
351        };
352        let pos = offset - line_offsets.get(lo).unwrap() + 1;
353        Ok((lo, pos))
354    }
355}
forge/coverage.rs

forge/
coverage.rs
