Skip to content

Commit

Permalink
docs: update API and README
Browse files Browse the repository at this point in the history
  • Loading branch information
@noomorph
noomorph committed Dec 7, 2024
1 parent 360c055 commit 06bb16e
Show file tree
Hide file tree
Showing 2 changed files with 148 additions and 59 deletions.
105 changes: 105 additions & 0 deletions API.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# API Overview

`allure-store` is built around a central `AllureStore` class that abstracts reading, writing, and transforming Allure data. It uses pluggable `AllureReader` and `AllureWriter` interfaces to allow custom data sources and destinations.

## High-Level Architecture

The core components are:

- **AllureStore**: A single interface for reading and writing Allure data. It delegates low-level operations to `AllureReader` and `AllureWriter` implementations.
- **AllureReader**: Responsible for fetching Allure data (containers, results, categories, environment, executor) from a source (e.g., filesystem, database).
- **AllureWriter**: Responsible for persisting Allure data back to some storage medium (e.g., writing JSON files, updating a database, etc.).

By default, `allure-store` provides:

- `FileAllureReader`: Reads Allure data from a directory containing `*-result.json`, `*-container.json`, `categories.json`, `environment.properties`, and optionally `executor.json`.
- `FileAllureWriter`: Writes data back to a directory using the Allure standard file formats.

## `AllureStore` Lifecycle

1. **Initialization**:
Use `fromDirectory` or `fromConfig` to create and initialize an `AllureStore` instance.
- `fromDirectory(resultsDir, options?)`:
- Creates a `FileAllureReader` and `FileAllureWriter` based on the provided directory.
- Optional `overwrite` parameter to clear the directory before writing new data.
- Optional `onError` parameter controlling error handling (`'throw' | 'ignore' | (err: Error) => void`).
- `fromConfig({ reader, writer })`:
- Use a custom reader/writer combination.

2. **Reading Data**:
Once you have an `AllureStore` instance:
- `getAllResults()`: Returns all results, including merged steps from ancestor containers.
- `getLatestResults()`: Returns only the most recent result per `historyId`.
- `getCategories()`: Fetches categories defined for the test results.
- `getEnvironment()`: Fetches environment properties.
- `getExecutor()`: Fetches executor info (CI system, etc.).
- `getContainer(id: string)`: Fetches a specific container.
- `getResult(id: string)`: Fetches a specific test result.

3. **Writing Data**:
`AllureStore` also provides methods to write data back to your storage:
- `writeCategories(categories: Category[])`: Updates the categories file.
- `writeEnvironmentInfo(info: Record<string, string>)`: Writes environment properties.
- `writeExecutorInfo(info: ExecutorInfo)`: Writes executor information.
- `writeContainer(container: Container)`: Writes an `*-container.json` file.
- `writeResult(result: Result)`: Writes a `*-result.json` file.

4. **Customization & Extensibility**:
- Create custom `AllureReader` and `AllureWriter` classes to support non-file-based stores:
```typescript
class MyDatabaseReader implements AllureReader {
async getContainerIds() { /* query DB */ }
async getResultIds() { /* query DB */ }
async readContainer(id: string) { /* fetch container from DB */ }
async readResult(id: string) { /* fetch result from DB */ }
async readCategories() { /* fetch categories */ }
async readEnvironmentInfo() { /* fetch environment info */ }
async readExecutorInfo() { /* fetch executor info */ }
}
```

- Similarly, implement `AllureWriter` to save data to a desired location.

## Data Structures

The core Allure data types follow the Allure data model:

- **Result**: Represents a single test’s execution data: `uuid`, `historyId`, `name`, `status`, `steps`, etc.
- **Container**: Groups related tests (results) and includes `befores` and `afters` steps.
- **Category**: Defines a set of conditions (e.g., regex-based) to group tests into categories.
- **Environment Info**: Key-value pairs describing the environment (e.g., `NODE_ENV=production`).
- **Executor Info**: Metadata about the system that ran the tests (e.g., CI pipeline details).

For full type definitions, see the TypeScript declarations in [src/types.ts](./src/types.ts).

## Error Handling

Both `FileAllureReader` and `FileAllureWriter` accept an `onError` parameter. This can be:

- `'throw'` (default): Throw an error to be handled by your application.
- `'ignore'`: Suppress errors silently.
- A custom function `(error: Error) => void`: Log or track errors according to your needs.
## Practical Examples
- **Merging Historical Results**:
You might have multiple runs of the same test (differentiated by `historyId`). `getLatestResults()` returns only the most recent result per test, useful for building a stable, final Allure report.
- **Adding Custom Metadata**:
Before generating a final Allure report, you can:
1. Read environment info: `const env = await store.getEnvironment();`
2. Update it with new data: `env['BUILD_ID'] = process.env.BUILD_ID;`
3. Write it back: `await store.writeEnvironmentInfo(env);`
- **Integrating with CI**:
In a CI pipeline, you might:
1. Download `allure-results` from a previous step.
2. Initialize `AllureStore` with `fromDirectory`.
3. Add categories or environment info.
4. Generate or update an Allure report with the enriched data.
## Next Steps
- Explore the source to understand how `FileAllureReader` and `FileAllureWriter` are implemented.
- Implement your own `AllureReader` and `AllureWriter` if your data isn’t file-based.
- Read the test suite to see practical usage scenarios.
102 changes: 43 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,48 @@
<div align="center">
<img src=".idea/icon.svg" width="64" height="64" alt="Allure Store logo" />

<img src=".idea/icon.svg" width=64 height=64 />
# allure-store

# allure-store
A flexible and extensible store for reading, writing, and transforming [Allure](https://docs.qameta.io/allure/) test results [^1].

A flexible and extensible store for reading, writing, and transforming [Allure](https://docs.qameta.io/allure/) test results [^1].
[![npm version](https://img.shields.io/npm/v/allure-store.svg)](https://www.npmjs.com/package/allure-store)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI Status](https://github.com/wix-incubator/allure-store/actions/workflows/ci.yml/badge.svg)](https://github.com/wix-incubator/allure-store/actions)
</div>

[![npm version](https://img.shields.io/npm/v/allure-store.svg)](https://www.npmjs.com/package/allure-store)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI Status](https://github.com/wix-incubator/allure-store/actions/workflows/ci.yml/badge.svg)](https://github.com/wix-incubator/allure-store/actions)
## Introduction

</div>
`allure-store` provides a standardized interface (the **AllureStore**) to:

## 🌟 Features
- Read existing Allure test results from a variety of sources (e.g., local filesystem, remote storage).
- Write new Allure data (results, categories, environment info, etc.) for downstream consumers or tools.
- Transform, aggregate, or customize Allure test data before generating a final Allure report.

- **Unified API**: Interact with Allure test results, containers, categories, environment, and executor info using a single, simple interface.
- **Filesystem Integration**: Easily read from and write Allure results in the familiar `allure-results` directory structure.
- **Custom Readers/Writers**: Inject your own `AllureReader` and `AllureWriter` implementations to integrate with your preferred storage backends.
- **Result Aggregation**: Merge test containers and results to produce enriched test data for Allure-compatible tools.
- **Flexible Composition**: Combine multiple data sources or transform results before generating your final Allure report.
By abstracting the data access behind `AllureReader` and `AllureWriter` interfaces, `allure-store` makes it simple to plug in custom storage backends, apply custom transformations, or integrate seamlessly into your CI/CD pipeline.

## 🚀 Installation
## 🌟 Key Features

```bash
npm install allure-store
```
- **Unified API**: Interact with Allure test results, containers, categories, environment, and executor info using a single, simple API (`AllureStore`).
- **Filesystem Integration**: Use built-in utilities to read from/write to a traditional `allure-results` directory.
- **Custom Integration Points**: Implement `AllureReader` and `AllureWriter` interfaces to read from or write to any storage backend—databases, cloud storage, etc.
- **Result Aggregation**: Merge parent test containers and child results to produce enriched test data for Allure-compatible tools.
- **Flexible Composition**: Combine multiple data sources or transform results before finalizing your Allure report.

## 🚀 Installation

or
Install with your preferred package manager:

```bash
npm install allure-store
# or
yarn add allure-store
```

## 📖 Usage
## 📖 Quick Start

### Initializing from a Directory
### Reading Results from a Directory

If you already have generated Allure results in a directory (e.g. `allure-results`), you can create a store directly:
If you have an existing `allure-results` directory (produced by Allure or a tool that supports it):

```typescript
import { fromDirectory } from 'allure-store';
Expand All @@ -52,43 +58,37 @@ import { fromDirectory } from 'allure-store';

const categories = await store.getCategories();
console.log('Categories:', categories);

const environment = await store.getEnvironment();
console.log('Environment info:', environment);
})();
```

### Writing Data
### Writing Data Back

You can also write data back to the Allure results directory (or another destination) using the store’s writer:
You can also write categories, environment info, or even individual test results:

```typescript
import { fromDirectory } from 'allure-store';

(async () => {
// You can pass optional 'overwrite' parameter to delete the directory before writing anything
const store = await fromDirectory('allure-results', { overwrite: true });

// Add/update environment info
await store.writeEnvironmentInfo({
NODE_ENV: 'production',
SERVICE_URL: 'https://api.example.com',
});

// Add new categories
await store.writeCategories([
{ name: 'Product defects', matchedStatuses: ['failed'] },
{ name: 'Test defects', matchedStatuses: ['broken'] },
]);
})();
```

### Using a Custom Configuration
### Using Custom Readers/Writers

If you have a custom `AllureReader` or `AllureWriter`:
If your results are stored in a different system, implement the `AllureReader` and `AllureWriter` interfaces and provide them to `fromConfig`:

```typescript
import { fromConfig, AllureStore, AllureReader, AllureWriter } from 'allure-store';
import { fromConfig, AllureReader, AllureWriter } from 'allure-store';

const customReader: AllureReader = {
async getContainerIds() { /* ... */ },
Expand All @@ -111,44 +111,28 @@ const customWriter: AllureWriter = {
(async () => {
const store = await fromConfig({ reader: customReader, writer: customWriter });
const results = await store.getAllResults();
// ...do something with results...
console.log('Custom source results:', results);
})();
```

## API Overview

**Core Exports:**

- **Classes:**
- `AllureStore`: Main class managing both reading and writing of Allure data.
## When to Use `allure-store`

- **Factory Functions:**
- `fromConfig(options: AllureStoreConfig): Promise<AllureStore>`
- `fromDirectory(options: FileSystemAllureWriterConfig): Promise<AllureStore>`
- **Custom CI Integrations**: Integrate Allure data from multiple pipelines or artifact stores, then produce a final Allure report.
- **Data Transformation**: Filter, enrich, or modify Allure results before final reporting.
- **Non-File Storage**: If your Allure data isn’t file-based, `allure-store` provides an abstraction to still leverage Allure’s ecosystem.

- **Types & Interfaces:**
- `AllureReader`, `AllureWriter`: Protocols for custom readers/writers.
- `AllureResult`, `AllureContainer`, `AllureStep`, `AllureParameter`, `Category`, `ExecutorInfo` and other core Allure data types.
## Additional Documentation

## Use Cases

- **Custom CI Integrations**: Use `allure-store` to load Allure results from your CI artifacts and produce a final enriched Allure report.
- **Data Transformation**: Before generating the final report, read and manipulate test results (e.g., filter out certain tests, add environment details, or group tests differently).
- **Storage Abstraction**: If your results are stored in a database or remote object storage, implement a custom `AllureReader` and `AllureWriter` to integrate seamlessly.
- **[API Documentation](./API.md)**: Detailed information on the store design, available methods, and data types.
- **[CONTRIBUTING.md](./CONTRIBUTING.md)**: Guidelines for contributing to this project.
- **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)**: Our expectations for community interactions.

## 🌐 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

1. Fork the repository
2. Create a new branch for your feature or fix
3. Submit a PR once you’re ready
Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to get started.

## 📃 License

> [!NOTE]
> `allure-store` is not affiliated with the official Allure framework, but it aims to provide a compatible and convenient way to handle Allure data.
This project is licensed under the [MIT License](LICENSE).

[^1]: **Note:** `allure-store` is not affiliated with the official Allure framework, but it aims to provide a compatible and convenient way to handle Allure data.
[^1]: **Note:** `allure-store` is not affiliated with the official Allure framework. It aims to provide a compatible and convenient way to handle Allure data.

0 comments on commit 06bb16e

Please sign in to comment.