Skip to content

Commit

Permalink
readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
@expectto
expectto committed Jan 14, 2024
1 parent e1ad776 commit b3af208
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 59 deletions.
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
### Contributing
Feel free to open issues.

### TODO: stabilize with contributing guidelines
127 changes: 68 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,76 +31,85 @@ import "github.com/expectto/be"

Be provides a set of core matchers for common testing scenarios:

| Matcher | Description | Example Usage |
|------------------------------|--------------------------------------------------------|----------------------------------------|
| `be.Always()` | Always succeeds | `be.Always()` |
| `be.Never(err)` | Never succeeds and always fails with a specified error | `be.Never(errors.New("custom error"))` |
| `be.All(ms ...any)` | Logical AND for multiple matchers | `be.All(matcher1, matcher2, ...)` |
| `be.Any(ms ...any)` | Logical OR for multiple matchers | `be.Any(matcher1, matcher2, ...)` |
| `be.Eq(expected)` | Checks for equality | `be.Eq(expectedValue)` |
| `be.Not(matcher)` | Negates the result of another matcher | `be.Not(anotherMatcher)` |
| `be.HaveLength(args ...any)` | Matches the length of slices, arrays, strings, or maps | `be.HaveLength(lengthMatcher)` |

| Matcher | Example Usage | Description |
|------------------------------|---------------------------------------------------------------|---------------------------------------------------------------------------------------|
| `be.Always()` | `Expect(anything()).To(be.Always())` | Always succeeds (passes). |
| `be.Never(err)` | `Expect(anything()).To(be.Never(errors.New("custom error")))` | Never succeeds and always fails with a specified error |
| `be.All(ms ...any)` | `Expect(m).To(be.All(HaveKey("foo"), HaveKey("bar"), ...))` | Logical AND for multiple matchers. _Similar to Ginkgo's`And()`_ |
| `be.Any(ms ...any)` | `Expect(m).To(be.Any(HaveKey("foo"), HaveKey("bar"), ...)` | Logical OR for multiple matchers. _Similar to Ginkgo's `Or()`_ |
| `be.Eq(expected)` | `Expect(v).To(be.Eq(expectedValue))` | Checks for equality. _Similar to Ginkgo's `Equal` _ |
| `be.Not(matcher)` | `Expect(v).To(be.Not(anotherMatcher))` | Negates the result of another matcher. _Similar to Ginkgo's `Not()`_ |
| `be.HaveLength(args ...any)` | `Expect(collection).To(be.HaveLength(lengthMatcher))` | Matches the length of slices, arrays, strings, or maps. Supports matchers as argument |

# Matchers for HTTP Requests

Be provides powerful matchers specifically designed for testing HTTP requests, offering detailed and structured request validation. These matchers seamlessly integrate with both Gomega and Gomock, providing a flexible and expressive way to verify various aspects of your HTTP requests.
Be provides powerful matchers specifically designed for testing HTTP requests, offering detailed and structured request
validation. These matchers seamlessly integrate with both Gomega and Gomock, providing a flexible and expressive way to
verify various aspects of your HTTP requests.

## Example

Consider the following example demonstrating the usage of Be's HTTP request matchers:

```go
// Matching an HTTP request
Expect(req).To(be_http.Request(
// Matching the URL
be_http.HavingURL(be_url.URL(
be_url.WithHttps(),
be_url.HavingHost("example.com"),
be_url.HavingPath("/path"),
be_url.HavingSearchParam("status", "active"),
be_url.HavingSearchParam("v", be_reflected.AsNumericString()),
be_url.HavingSearchParam("q", "Hello World"),
)),

// Matching the HTTP method
be_http.HavingMethod("POST"),

// Matching the request body using JSON matchers
be_http.HavingBody(
be_json.Matcher(
be_json.JsonAsReader,
be_json.HaveKeyValue("hello", "world"),
be_json.HaveKeyValue("n", be_reflected.AsIntish()),
be_json.HaveKeyValue("ids", be_reflected.AsSliceOf[string]),
be_json.HaveKeyValue("details", And(
be_reflected.AsObjects(),
be.HaveLength(2),
ContainElements(
be_json.HaveKeyValue("key", "foo"),
be_json.HaveKeyValue("key", "bar"),
),
)),
),

// Matching HTTP headers
be_http.HavingHeader("X-Custom", "Hey-There"),
be_http.HavingHeader("Authorization",
be_strings.Template("Bearer {{jwt}}",
be_strings.MatchingPart("jwt",
be_jwt.Token(
be_jwt.BeingValid(),
be_jwt.HavingClaims("name", "John Doe"),
),
),
),
),
),
))
// Matching an HTTP request
Expect(req).To(be_http.Request(
// Matching the URL
be_http.HavingURL(be_url.URL(
be_url.WithHttps(),
be_url.HavingHost("example.com"),
be_url.HavingPath("/path"),
be_url.HavingSearchParam("status", "active"),
be_url.HavingSearchParam("v", be_reflected.AsNumericString()),
be_url.HavingSearchParam("q", "Hello World"),
)),

// Matching the HTTP method
be_http.HavingMethod("POST"),

// Matching request's context
be_http.HavingCtx(be_ctx.Ctx(
be_ctx.WithDeadline(be_time.LaterThan(time.Now().Add(30*time.Minute))),
be_ctx.WithValue("foobar", 100),
))

// Matching the request body using JSON matchers
be_http.HavingBody(
be_json.Matcher(
be_json.JsonAsReader,
be_json.HaveKeyValue("hello", "world"),
be_json.HaveKeyValue("n", be_reflected.AsIntish()),
be_json.HaveKeyValue("ids", be_reflected.AsSliceOf[string]),
be_json.HaveKeyValue("details", And(
be_reflected.AsObjects(),
be.HaveLength(2),
ContainElements(
be_json.HaveKeyValue("key", "foo"),
be_json.HaveKeyValue("key", "bar"),
),
)),
),

// Matching HTTP headers
be_http.HavingHeader("X-Custom", "Hey-There"),
be_http.HavingHeader("Authorization",
be_strings.Template("Bearer {{jwt}}",
be_strings.MatchingPart("jwt",
be_jwt.Token(
be_jwt.BeingValid(),
be_jwt.HavingClaims("name", "John Doe"),
),
),
),
),
),
))
```

# Contributing
Be welcomes contributions! Feel free to open issues, suggest improvements, or submit pull requests. See CONTRIBUTING.md for more details.

`Be` welcomes contributions! Feel free to open issues, suggest improvements, or submit pull requests. [Contribution guidelines for this project](CONTRIBUTING.md)

# License
This project is licensed under the MIT License.

This project is [licensed under the MIT License](LICENSE).

0 comments on commit b3af208

Please sign in to comment.