forge/
coverage.rs

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

forge/
coverage.rs
