Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
joeldickson authored Nov 22, 2024
1 parent 0ff9a86 commit 4e35e46
Showing 1 changed file with 86 additions and 27 deletions.
113 changes: 86 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,88 @@
# Shouldly.FromAssert

Roslyn Code Fix library for migrating code from **NUnit** and **XUnit** assertions to **Shouldly Shoulds**.

### Supports the following list of assertions

- Assert.That
- Assert.True
- Assert.False
- Assert.Null
- Assert.NotNull
- Assert.IsEmpty
- Assert.IsNotEmpty
- Assert.AreEqual
- Assert.AreNotEqual
- Assert.AreSame
- Assert.AreNotSame
- Assert.Contains
- Assert.Zero
- Assert.NotZero
- Assert.IsNaN
- Assert.IsInstanceOf
- Assert.IsNotInstanceOf
- Assert.IsAssignableFrom
- Assert.Throws
- Assert.ThrowsAsync
- Assert.DoesNotThrow
- Assert.DoesNotThrowAsync

[![NuGet](https://img.shields.io/nuget/v/Shouldly.FromAssert.svg)](https://www.nuget.org/packages/Shouldly.FromAssert)
[![License](https://img.shields.io/github/license/agoda-com/Shouldly.FromAssert)](https://github.com/agoda-com/Shouldly.FromAssert/blob/main/LICENSE)

Because life's too short for hard-to-read assertions! πŸ”

## What is this?

Shouldly.FromAssert is a Roslyn analyzer that helps you migrate from traditional NUnit assertions to the more human-readable [Shouldly](https://github.com/shouldly/shouldly) library. It's like having a friendly code review buddy who's really into making tests more readable (but doesn't drink your coffee).

## Features

- Automatically detects NUnit assertions and suggests Shouldly alternatives
- Provides code fixes to transform assertions with a single click
- Supports a wide range of assertion types:
- Basic assertions (`Assert.AreEqual` β†’ `ShouldBe`)
- String assertions (`StringAssert.Contains` β†’ `ShouldContain`)
- Collection assertions (`CollectionAssert.Contains` β†’ `ShouldContain`)
- Type assertions (`Assert.IsInstanceOf` β†’ `ShouldBeOfType`)
- And many more!

## Installation

```shell
dotnet add package Shouldly.FromAssert
```

## Usage

1. Install the package
2. Write your tests as usual with NUnit
3. Look for the analyzer suggestions (they'll appear as warnings)
4. Click the lightbulb πŸ’‘ or press (Alt+Enter or Ctrl+. depending on the IDE religeon you practice)
5. Select "Convert to Shouldly"
6. Watch your assertions transform into beautiful, readable Shouldly statements

### Before and After

```csharp
// Before: πŸ˜•
Assert.That(contestant, Is.EqualTo(1337));
CollectionAssert.Contains(contestants, winner);
StringAssert.StartsWith("Hello", greeting);

// After: 😊
contestant.ShouldBe(1337);
contestants.ShouldContain(winner);
greeting.ShouldStartWith("Hello");
```

## Supported Conversions

Here are some examples of the transformations this analyzer can perform:

| NUnit | Shouldly |
|----------------------------------------------------|--------------------------------------------|
| `Assert.That(x, Is.EqualTo(y))` | `x.ShouldBe(y)` |
| `Assert.IsTrue(x > 10)` | `(x > 10).ShouldBeTrue()` |
| `Assert.IsNull(x)` | `x.ShouldBeNull()` |
| `CollectionAssert.Contains(list, item)` | `list.ShouldContain(item)` |
| `StringAssert.StartsWith("Hi", str)` | `str.ShouldStartWith("Hi")` |
| `Assert.Throws<ArgumentException>(() => method())` | `Should.Throw<ArgumentException>(() => method())` |

And many more! Check out the tests for a complete list of supported conversions.

## Contributing

Found a bug? Have a suggestion? Want to add support for more assertions? We'd love your help! Please feel free to:

1. Open an issue
2. Submit a pull request
3. Start a discussion
4. Share your success stories

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- The awesome [Shouldly](https://github.com/shouldly/shouldly) team for making assertions more human
- The [Roslyn](https://github.com/dotnet/roslyn) team for making this possible
- Coffee β˜•, for making developers possible

---

Made with πŸ’š by [Agoda](https://github.com/agoda-com)

0 comments on commit 4e35e46

Please sign in to comment.