# PDF/PNG Export Regression Runner

This project automates **export generation** (PDF/PNG) from DHTMLX Gantt/Scheduler export demo pages and then **compares** the generated files between two folders:

- `base/` — the baseline (golden) exports
- `compare/` — the newly generated exports to be compared against the baseline

It is designed for a workflow like:

1) Generate baseline exports into `base/`
2) Generate new exports into `compare/`
3) Compare `base/` vs `compare/` and produce diffs / reports

---

## Requirements

- Node.js (CommonJS project)
- `npm install` (installs Puppeteer, pdfjs, pixelmatch, etc.)

---

## Installation

```bash
npm install
```

---

## Commands

### 1) Generate exports (PDF or PNG depending on the selected test profile)

```bash
npm run generate_files <component> <profile>
```

```bash
# Gantt (explicit)
npm run generate_files gantt minimal

# Scheduler
npm run generate_files scheduler minimal
npm run generate_files scheduler full
```

If the component is not specified, it will run Gantt-related tests:
```
npm run generate_files minimal
```

Examples for Gantt:

```bash
npm run generate_files gantt minimal // the bare minimum that covers most failures
npm run generate_files gantt additional // additional tests that don't need to be checked often
npm run generate_files gantt full // run all tests, generates around 500 files and takes a lot of time
npm run generate_files gantt png // create PNG files for all scenarios
npm run generate_files gantt png_archives // create only archives with PNG slices for each scenario
```

**How output folder is chosen:**

- If `base/` is empty → downloads go to `base/`
- If `base/` already has files → downloads go to `compare/`
- If downloads go to `compare/` and `compare/` is not empty → `compare/` is cleared before the run

### 2) Compare exports

```bash
npm run compare_files
```

This compares:

- PDF files: `base/*.pdf` vs `compare/*.pdf`
- PNG files: `base/*.png` vs `compare/*.png`

If any differences are found, the process exits with code **2** (useful for CI).

---

## Profiles (test suites)

`generate_files` loads test modules from subfolders of `tests/`.

### Folder mapping

**Gantt** profiles:

| Profile | Folder |
|---|---|
| `minimal` | `tests/00_minimal/` |
| `additional` | `tests/01_additional/` |
| `png` | `tests/02_png/` |
| `png_archives` | `tests/03_png_archives/` |
| `full` | `tests/04_full/` |

**Scheduler** profiles use the same names, but are located under `tests/scheduler/`:

| Profile | Folder |
|---|---|
| `minimal` | `tests/scheduler/00_minimal/` |
| `additional` | `tests/scheduler/01_additional/` |
| `png` | `tests/scheduler/02_png/` |
| `png_archives` | `tests/scheduler/03_png_archives/` |
| `full` | `tests/scheduler/04_full/` |

You can also pass a folder name directly (it will try `tests/<component>/<profile>`).

Each test file represents an **app scenario** (what the page loads via `switchConfig(...)`), and then runs multiple **export configs** (what is passed into `exportPDFandPNG(...)`).

---

## HTML page location

By default, `generate_files` opens:

- Gantt: `../gantt_export_scenarios.html`
- Scheduler: `../scheduler_export_scenarios.html`

If your HTML file is elsewhere, set `HTML_PATH`:

```bash
HTML_PATH=/absolute/path/to/gantt_export_scenarios.html npm run generate_files gantt minimal
HTML_PATH=/absolute/path/to/scheduler_export_scenarios.html npm run generate_files scheduler minimal
```

---

## Outputs

### Generation
- Files are downloaded into either `base/` or `compare/` (root of the folder, no subfolders).

### Comparison
Reports and screenshots are written into `results/`:

- PDF:
  - `results/diff-files.json`
  - `results/diff-files.txt`
  - `results/screenshots/<file-stem>/page-XXX.png` (+ optional `page-XXX-diff.png`)
- PNG:
  - `results/diff-png-files.json`
  - `results/diff-png-files.txt`
  - `results/png_screenshots/<file-stem>/image.png` (+ optional `image-diff.png`)

---

## Typical workflow

> Use the same **component** and **profile** for both baseline and compare runs (e.g. `gantt full` or `scheduler full`).

### Create / refresh baseline
1) Ensure `base/` is empty (or delete its contents)
2) Run:
   ```bash
   npm run generate_files full
   ```
3) Baseline exports will appear in `base/`

### Compare a new run against baseline
1) Run generation again (with the same profile):
   ```bash
   npm run generate_files full
   ```
   Since `base/` already contains files, outputs will go to `compare/` (and `compare/` will be cleared first).
2) Compare:
   ```bash
   npm run compare_files
   ```
3) Open `results/` to inspect differences.

---

## Adding a new test (scenario)

1) Create a new file in one of the `tests/<profile-folder>/` directories.
2) Export a `run(page)` function.
3) In `run`, call the helper from `tests/helpers.js` and return a `string[]` of expected filenames.

Example skeleton:

```js
const { runConfigPdfExports, ALL_PDF_CONFIGS } = require("../../helpers");

module.exports.run = async (page) => {
  return runConfigPdfExports(page, {
    scenarioName: "my_scenario",        // value passed to switchConfig(...)
    exportConfigs: ALL_PDF_CONFIGS,     // exportPDFandPNG configs to run
    includeSimple: true,                // or false to drop "simple"
  });
};
```

---

## Troubleshooting

- **Nothing downloads:** make sure the export server configured in the HTML page is reachable.
- **Weird runtime errors after code changes:** run `npm install` again (or remove `node_modules` and reinstall).
- **Compare reports show missing files:** ensure you generated into `compare/` before running `compare_files`, and that filenames match (some “invalid name” exports may be sanitized by the server).

---