Browse Source

Updated the documentation

tags/v1.0.0
Cédric Belin 1 month ago
parent
commit
13e267cc5f
7 changed files with 399 additions and 46 deletions
  1. +4
    -2
      README.md
  2. +35
    -0
      doc/css/mkdocs.css
  3. +15
    -11
      doc/index.md
  4. +111
    -0
      doc/installation.md
  5. +193
    -0
      doc/usage.md
  6. +38
    -30
      etc/mkdocs.yaml
  7. +3
    -3
      readthedocs.yaml

+ 4
- 2
README.md View File

@@ -1,6 +1,8 @@
# LCOV Reports
![Release](https://img.shields.io/badge/release-v0.1.0-brightgreen.svg) ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Coverage](https://coveralls.io/repos/github/cedx/lcov.hx/badge.svg) ![Build](https://github.com/cedx/lcov.hx/workflows/build/badge.svg)
![Haxe](https://img.shields.io/badge/haxe-%3E%3D4.0.0-brightgreen.svg) ![Node.js](https://img.shields.io/node/v/@cedx/lcov.hx.svg) ![PHP](https://img.shields.io/packagist/php-v/cedx/lcov.hx.svg)
![Haxe](https://badgen.net/badge/haxe/%3E%3D4.1.0/green) ![Haxelib](https://badgen.net/haxelib/v/lcov) ![Downloads](https://badgen.net/haxelib/d/lcov)
![Node.js](https://badgen.net/npm/node/@cedx/lcov.hx) ![npm](https://badgen.net/npm/v/@cedx/lcov.hx) ![Types](https://badgen.net/npm/types/@cedx/lcov.hx) ![Downloads](https://badgen.net/npm/dt/@cedx/lcov.hx)
![PHP](https://badgen.net/packagist/php/cedx/lcov.hx) ![Packagist](https://badgen.net/packagist/v/cedx/lcov.hx) ![Downloads](https://badgen.net/packagist/dt/cedx/lcov.hx)
![License](https://badgen.net/badge/license/MIT/blue) ![Coverage](https://badgen.net/coveralls/c/github/cedx/lcov.hx) ![Build](https://badgen.net/github/checks/cedx/lcov.hx)

Parse and format [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) coverage reports, in [Haxe](https://haxe.org), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [PHP](https://www.php.net).



+ 35
- 0
doc/css/mkdocs.css View File

@@ -0,0 +1,35 @@
/* Variables */
:root {
--link-color: darkorange;
--link-hover-color: orange;
}

/* Main content */
.md-typeset a {
color: var(--link-color);
}

.md-typeset a > code {
background-color: transparent;
}

.md-typeset a:focus,
.md-typeset a:hover {
color: var(--link-hover-color);
}

/* Navigation */
.md-nav__item .md-nav__link--active {
color: var(--link-color);
}

@media screen and (max-width: 76.1875em) {
.md-nav--primary .md-nav__item--active > .md-nav__link {
color: var(--link-color);
}
}

.md-nav__item .md-nav__link--active:focus,
.md-nav__item .md-nav__link--active:hover {
color: var(--link-hover-color);
}

+ 15
- 11
doc/index.md View File

@@ -1,21 +1,25 @@
# LCOV Reports
![Release](https://img.shields.io/badge/release-v0.1.0-brightgreen.svg) ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Coverage](https://coveralls.io/repos/github/cedx/lcov.hx/badge.svg) ![Build](https://github.com/cedx/lcov.hx/workflows/build/badge.svg)
![Haxe](https://img.shields.io/badge/haxe-%3E%3D4.0.0-brightgreen.svg) ![Node.js](https://img.shields.io/node/v/@cedx/lcov.hx.svg) ![PHP](https://img.shields.io/packagist/php-v/cedx/lcov.hx.svg)
![Haxe](https://badgen.net/badge/haxe/%3E%3D4.1.0/green) ![Haxelib](https://badgen.net/haxelib/v/lcov) ![Downloads](https://badgen.net/haxelib/d/lcov)
![Node.js](https://badgen.net/npm/node/@cedx/lcov.hx) ![npm](https://badgen.net/npm/v/@cedx/lcov.hx) ![Types](https://badgen.net/npm/types/@cedx/lcov.hx) ![Downloads](https://badgen.net/npm/dt/@cedx/lcov.hx)
![PHP](https://badgen.net/packagist/php/cedx/lcov.hx) ![Packagist](https://badgen.net/packagist/v/cedx/lcov.hx) ![Downloads](https://badgen.net/packagist/dt/cedx/lcov.hx)
![License](https://badgen.net/badge/license/MIT/blue) ![Coverage](https://badgen.net/coveralls/c/github/cedx/lcov.hx) ![Build](https://badgen.net/github/checks/cedx/lcov.hx)

Parse and format [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) coverage reports in [Haxe](https://haxe.org), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [PHP](https://www.php.net).
Parse and format [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) coverage reports,
in [Haxe](https://haxe.org), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [PHP](https://www.php.net).

## Quick start
Install the latest version of **LCOV Reports** with your favorite package manager:

```shell
# Haxe
haxelib install lcov
=== "Haxe"
:::shell
haxelib install lcov

# JavaScript/Node.js
npm install @cedx/lcov.hx
=== "JavaScript"
:::shell
npm install @cedx/lcov.hx

# PHP
composer require cedx/lcov.hx
```
=== "PHP"
:::shell
composer require cedx/lcov.hx

For detailed instructions, see the [installation guide](installation.md).

+ 111
- 0
doc/installation.md View File

@@ -0,0 +1,111 @@
# Installation

## Requirements
Before installing **WebStorage.hx**, you need to make sure you have either
[Haxe](https://haxe.org), [Node.js](https://nodejs.org) or [PHP](https://www.php.net) up and running.
You can verify if you're already good to go with the following commands:

=== "Haxe"
:::shell
haxe --version
# 4.1.0

haxelib version
# 4.0.2

=== "JavaScript"
:::shell
node --version
# v14.3.0

npm --version
# 6.14.5

=== "PHP"
:::shell
php --version
# PHP 7.4.6 (cli) (built: May 12 2020 11:38:52) ( NTS Visual C++ 2017 x64 )

composer --version
# Composer version 1.10.6 2020-05-06 10:28:10

!!! info
If you plan to play with the package sources, you will also need
[PowerShell](https://docs.microsoft.com/en-us/powershell) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material).

## Installing with a package manager

=== "Haxe"
### 1. Install it
From a command prompt, run:

:::shell
haxelib install lcov

### 2. Import it
Now in your [Haxe](https://haxe.org) code, you can use:

:::haxe
import lcov.*;

=== "JavaScript"
### 1. Install it
From a command prompt, run:

:::shell
npm install @cedx/lcov.hx

### 2. Import it
Now in your [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) code, you can use:

:::js
// CommonJS module.
const lcov = require("@cedx/lcov.hx");

// ECMAScript module.
import * as lcov from "@cedx/lcov.hx";

=== "PHP"
### 1. Install it
From a command prompt, run:

:::shell
composer require cedx/lcov.hx

### 2. Import it
Now in your [PHP](https://www.php.net) code, you can use:

:::php
<?php
use lcov\{
BranchCoverage, BranchData,
FunctionCoverage, FunctionData,
LineCoverage, LineData,
LcovException, Record, Report
};

## Installing from a content delivery network
This library is also available as a ready-made JavaScript bundle.
To install it, add one of these code snippets to the `<head>` of your HTML document:

``` html
<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@cedx/lcov.hx/build/lcov.min.js"></script>

<!-- UNPKG -->
<script src="https://unpkg.com/@cedx/lcov.hx/build/lcov.min.js"></script>
```

The classes of this library are exposed as `lcov` property on the `window` global object:

``` html
<script>
const {
BranchCoverage, BranchData,
FunctionCoverage, FunctionData,
LineCoverage, LineData,
LcovException, Record, Report
} = window.lcov;
</script>
```

+ 193
- 0
doc/usage.md View File

@@ -0,0 +1,193 @@
---
path: src/branch/master
source: src/lcov/Report.hx
---

# Usage
**LCOV Reports** provides a set of classes representing a [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) coverage report and its data.
The `Report` class, the main one, provides the parsing and formatting features.

## Parse coverage data from a LCOV file
The `Report.fromCoverage()` static method parses a [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) coverage report provided as string, and creates a `Report` instance giving detailed information about this coverage report:

=== "Haxe"
:::haxe
import haxe.Json;
import lcov.LcovException;
import lcov.Report;

class Main {
static function main(): Void {
try {
final coverage = await readFile("/path/to/lcov.info", "utf8");
final report = Report.fromCoverage(coverage);

final count = report.records.length;
Sys.println('The coverage report contains $count records:');
Sys.println(Json.stringify(report.toJson(), null, " "));
}

catch (LcovException exception) {
Sys.println('An error occurred: ${exception.message}');
}
}
}

=== "JavaScript"
:::js
import {Report} from "@cedx/lcov.hx";
import {readFile} from "fs/promises";

async function main() {
try {
const coverage = await readFile("/path/to/lcov.info", "utf8");
const report = Report.fromCoverage(coverage);

const count = report.records.length;
console.log(`The coverage report contains ${count} records:`);
console.log(JSON.stringify(report, null, 2));
}

catch (error) {
console.log(`An error occurred: ${error.message}`);
}
}

=== "PHP"
:::php
<?php
use lcov\{LcovException, Report};

function main(): void {
try {
$coverage = file_get_contents("/path/to/lcov.info");
$report = Report::fromCoverage($coverage);
$count = count($report->getRecords());
echo "The coverage report contains $count records:", PHP_EOL;
echo json_encode($report, JSON_PRETTY_PRINT);
}

catch (LcovException $exception) {
echo "An error occurred: ", $exception->getMessage();
}
}

!!! info
A `LcovException` is thrown if any error occurred while parsing the coverage report.

The `Report.toJson()` instance method will return a [JSON](https://www.json.org) map like this:

``` json
{
"testName": "Example",
"records": [
{
"sourceFile": "/home/cedx/lcov.hx/fixture.js",
"branches": {
"found": 0,
"hit": 0,
"data": []
},
"functions": {
"found": 1,
"hit": 1,
"data": [
{"functionName": "main", "lineNumber": 4, "executionCount": 2}
]
},
"lines": {
"found": 2,
"hit": 2,
"data": [
{"lineNumber": 6, "executionCount": 2, "checksum": "PF4Rz2r7RTliO9u6bZ7h6g"},
{"lineNumber": 9, "executionCount": 2, "checksum": "y7GE3Y4FyXCeXcrtqgSVzw"}
]
}
}
]
}
```

!!! tip
See the [API reference](https://api.belin.io/lcov.hx) of this library for more information on the `Report` class.

## Format coverage data to the LCOV format
Each class provided by this library has a dedicated `toString()` instance method returning the corresponding data formatted as [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) string.
All you have to do is to create the adequate structure using these different classes, and to export the final result:

=== "Haxe"
:::haxe
import lcov.*;

class Main {
static function main(): Void {
final lineCoverage = new LineCoverage(2, 2, [
new LineData(6, 2, "PF4Rz2r7RTliO9u6bZ7h6g"),
new LineData(7, 2, "yGMB6FhEEAd8OyASe3Ni1w")
]);

final record = new Record("/home/cedx/lcov.hx/fixture.hx", {
functions: new FunctionCoverage(1, 1),
lines: lineCoverage
});

final report = new Report("Example", [record]);
Sys.println(report.toString());
}
}

=== "JavaScript"
:::js
import {FunctionCoverage, LineCoverage, LineData, Record, Report} from "@cedx/lcov.hx";

function main() {
const lineCoverage = new LineCoverage(2, 2, [
new LineData(6, 2, "PF4Rz2r7RTliO9u6bZ7h6g"),
new LineData(7, 2, "yGMB6FhEEAd8OyASe3Ni1w")
]);

const record = new Record("/home/cedx/lcov.hx/fixture.js", {
functions: new FunctionCoverage(1, 1),
lines: lineCoverage
});

const report = new Report("Example", [record]);
console.log(report.toString());
}

=== "PHP"
:::php
<?php
use lcov\{FunctionCoverage, LineCoverage, LineData, Record, Report};

function main(): void {
$lineCoverage = new LineCoverage(2, 2, [
new LineData(6, 2, "PF4Rz2r7RTliO9u6bZ7h6g"),
new LineData(7, 2, "yGMB6FhEEAd8OyASe3Ni1w")
]);

$record = (new Record("/home/cedx/lcov.hx/fixture.php"))
->setFunctions(new FunctionCoverage(1, 1))
->setLines($lineCoverage);

$report = new Report("Example", [$record]);
echo $report;
}

The `Report.toString()` method will return a [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) report formatted like this:

```
TN:Example
SF:/home/cedx/lcov.hx/fixture.js
FNF:1
FNH:1
DA:6,2,PF4Rz2r7RTliO9u6bZ7h6g
DA:7,2,yGMB6FhEEAd8OyASe3Ni1w
LF:2
LH:2
end_of_record
```

!!! tip
See the [API reference](https://api.belin.io/lcov.hx) of this library for detailed information on the available classes.

+ 38
- 30
etc/mkdocs.yaml View File

@@ -12,39 +12,47 @@ edit_uri: ""

copyright: Copyright &copy; 2020 Cédric Belin
extra:
social:
- icon: fontawesome/solid/globe
link: "https://belin.io"
- icon: fontawesome/brands/github
link: "https://github.com/cedx"
- icon: fontawesome/brands/twitter
link: "https://twitter.com/cedxbelin"
- icon: fontawesome/brands/linkedin
link: "https://linkedin.com/in/cedxbelin"
social:
- icon: fontawesome/solid/globe
link: "https://belin.io"
name: Belin.io
- icon: fontawesome/brands/github
link: "https://github.com/cedx"
name: GitHub
- icon: fontawesome/brands/twitter
link: "https://twitter.com/cedxbelin"
name: Twitter
- icon: fontawesome/brands/linkedin
link: "https://linkedin.com/in/cedxbelin"
name: LinkedIn

extra_css:
- css/mkdocs.css

markdown_extensions:
- admonition
- codehilite
- meta
- toc:
permalink: true
- admonition
- codehilite
- meta
- pymdownx.tabbed
- toc:
permalink: true

nav:
- Overview: index.md
- Installation: installation.md
- Usage: usage.md
- About:
- License: about/license.md
- See also: about/see_also.md
- Overview: index.md
- Installation: installation.md
- Usage: usage.md
- About:
- License: about/license.md
- See also: about/see_also.md

theme:
favicon: img/favicon.ico
features:
- instant
icon:
logo: fontawesome/solid/book-reader
repo: fontawesome/brands/git-alt
name: material
palette:
accent: amber
primary: amber
favicon: img/favicon.ico
features:
- instant
icon:
logo: fontawesome/solid/book-reader
repo: fontawesome/brands/git-alt
name: material
palette:
accent: amber
primary: amber

+ 3
- 3
readthedocs.yaml View File

@@ -1,6 +1,6 @@
version: 2
mkdocs:
configuration: etc/mkdocs.yaml
configuration: etc/mkdocs.yaml
python:
install:
- requirements: etc/requirements.txt
install:
- requirements: etc/requirements.txt

Loading…
Cancel
Save