<commit_before>[![Build Status](https://travis-ci.org/AlKass/polish.svg?branch=master)](https://travis-ci.org/AlKass/polish)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<div align="center">
  <img src="https://cloud.githubusercontent.com/assets/17054134/25564962/b9f27b44-2dbe-11e7-9ab2-d5bb25b8de27.png" />
</div>

# Polish

`Polish` is a mini testing framework for the `Rust` system programming language meant to allow the writing of test-driven applications in a unified and expressive manner.

## Getting Started

Add the following under `[dependencies]` inside your project's `Cargo.toml` file:

```yaml
polish = "*"
```

Or use the following if you'd like to use nightly releases:

```yaml
polish = { git = "https://github.com/alkass/polish", branch = "master" }
```

At minimum, you'll need the following:

```rust
extern crate polish;

use polish::test_case::{TestCase, TestCaseStatus};
use polish::logger::Logger;
```

> `TestCase` is the object you'll use to instantiate your test case(s)

> `TestCaseStatus` is an enum of 4 possible options (`PASSED`, `FAILED`, `SKIPPED`, and `UNKNOWN`). One of these options will need to be returned from each test case, and therefore, `TestCaseStatus` must be the return type of every test case you write.

The bare minimum for a syntactically valid test case would look like this:

```rust
TestCase::new("Test Case Title", "Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
    // TODO: Implement your test case here
    TestCaseStatus::PASSED // This is the return value
}));
```

if you want to log some formatted output, you can use the logger object that's passed to your test case.

Logger has 4 logging functions you can use (`pass`, `fail`, `info`, `warn`). These functions take a `message` of type `String` which means you can pass formatted text to it using the `format!` macro, e.g.:

```rust
logger.info(format!("{} + {} = {}", 1, 2, 1 + 2));
```

These logging statements are counted by the logger object, and the final statistics are shown to you at the end of the execution of each test case.

> Note that the `fail` function doesn't cause your application to halt.

> You can use the built-in `print!` and `println!` macros to log your output just fine, but `Logger` will better format your logs.

### Putting it All Together

To run a single test case, include the `run_test` function from `polish::test_case` as follows:

```rust
use polish::test_case::run_test;
```

Implement your test case as follows:

```rust
let my_test_case = TestCase::new("Test Case Title", "Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
    logger.pass(format!("Good to go"));
    TestCaseStatus::PASSED
}))
```

And then pass your test case to the `run_test` function:

```rust
run_test(my_test_case);
```

And that's it! Your test case is ready to roll ^_^

This test case produces the following output:

![alt text](screenshots/run_test.png "")

> `run_test` has a return value, but we'll get back to that later.

> This single test case demo is available [here](examples/run_test.rs)

### Working with Multiple Test Cases

If you have multiple test cases to work with, you can store them in a vector and pass them to `run_tests` instead of `run_test`, e.g.:

```rust
let my_test_cases = vec![
    TestCase::new("1st Test Case Title", "1st Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
      logger.pass(format!("Good to go"));
      TestCaseStatus::PASSED
    })),
    TestCase::new("2nd Test Case Title", "2nd Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
      logger.warn(format!("This is a warning"));
      TestCaseStatus::UNKNOWN
    })),
TestCase::new("3rd Test Case Title", "3rd Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
  logger.fail(format!("this is a failure"));
  TestCaseStatus::FAILED
}))
];
  run_tests(my_test_cases);
```

This produces the following output:

![alt text](screenshots/run_tests.png "")

This test case demo is available [here](examples/run_tests.rs)

### Writing Tests as Part of an Object<commit_msg>Fixed Indentations<commit_after>[![Build Status](https://travis-ci.org/AlKass/polish.svg?branch=master)](https://travis-ci.org/AlKass/polish)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<div align="center">
  <img src="https://cloud.githubusercontent.com/assets/17054134/25564962/b9f27b44-2dbe-11e7-9ab2-d5bb25b8de27.png" />
</div>

# Polish

`Polish` is a mini testing framework for the `Rust` system programming language meant to allow the writing of test-driven applications in a unified and expressive manner.

## Getting Started

Add the following under `[dependencies]` inside your project's `Cargo.toml` file:

```yaml
polish = "*"
```

Or use the following if you'd like to use nightly releases:

```yaml
polish = { git = "https://github.com/alkass/polish", branch = "master" }
```

At minimum, you'll need the following:

```rust
extern crate polish;

use polish::test_case::{TestCase, TestCaseStatus};
use polish::logger::Logger;
```

> `TestCase` is the object you'll use to instantiate your test case(s)

> `TestCaseStatus` is an enum of 4 possible options (`PASSED`, `FAILED`, `SKIPPED`, and `UNKNOWN`). One of these options will need to be returned from each test case, and therefore, `TestCaseStatus` must be the return type of every test case you write.

The bare minimum for a syntactically valid test case would look like this:

```rust
TestCase::new("Test Case Title", "Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
    // TODO: Implement your test case here
    TestCaseStatus::PASSED // This is the return value
}));
```

if you want to log some formatted output, you can use the logger object that's passed to your test case.

Logger has 4 logging functions you can use (`pass`, `fail`, `info`, `warn`). These functions take a `message` of type `String` which means you can pass formatted text to it using the `format!` macro, e.g.:

```rust
logger.info(format!("{} + {} = {}", 1, 2, 1 + 2));
```

These logging statements are counted by the logger object, and the final statistics are shown to you at the end of the execution of each test case.

> Note that the `fail` function doesn't cause your application to halt.

> You can use the built-in `print!` and `println!` macros to log your output just fine, but `Logger` will better format your logs.

### Putting it All Together

To run a single test case, include the `run_test` function from `polish::test_case` as follows:

```rust
use polish::test_case::run_test;
```

Implement your test case as follows:

```rust
let my_test_case = TestCase::new("Test Case Title", "Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
    logger.pass(format!("Good to go"));
    TestCaseStatus::PASSED
}))
```

And then pass your test case to the `run_test` function:

```rust
run_test(my_test_case);
```

And that's it! Your test case is ready to roll ^_^

This test case produces the following output:

![alt text](screenshots/run_test.png "")

> `run_test` has a return value, but we'll get back to that later.

> This single test case demo is available [here](examples/run_test.rs)

### Working with Multiple Test Cases

If you have multiple test cases to work with, you can store them in a vector and pass them to `run_tests` instead of `run_test`, e.g.:

```rust
let my_test_cases = vec![
    TestCase::new("1st Test Case Title", "1st Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
      logger.pass(format!("Good to go"));
      TestCaseStatus::PASSED
    })),
    TestCase::new("2nd Test Case Title", "2nd Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
      logger.warn(format!("This is a warning"));
      TestCaseStatus::UNKNOWN
    })),
    TestCase::new("3rd Test Case Title", "3rd Test Case Criteria", Box::new(|logger: &mut Logger| -> TestCaseStatus {
      logger.fail(format!("this is a failure"));
      TestCaseStatus::FAILED
    }))
];
  run_tests(my_test_cases);
```

This produces the following output:

![alt text](screenshots/run_tests.png "")

This test case demo is available [here](examples/run_tests.rs)

### Writing Tests as Part of an Object
{'fraction_non_alphanumeric': 0.13027369427512847, 'fraction_numerical': 0.010756543564001434, 'mean_word_length': 4.631224764468372, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 31, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1388301', 'n_tokens_mistral': 2648, 'n_tokens_neox': 2507, 'n_words': 980}