pax_global_header 0000666 0000000 0000000 00000000064 14462163431 0014516 g ustar 00root root 0000000 0000000 52 comment=c74ddd1c7d1296ee3e192d89a2f9e477341c3ac3
golang-gomega-1.27.10/ 0000775 0000000 0000000 00000000000 14462163431 0014372 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/.github/ 0000775 0000000 0000000 00000000000 14462163431 0015732 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/.github/FUNDING.yml 0000664 0000000 0000000 00000000017 14462163431 0017545 0 ustar 00root root 0000000 0000000 github: [onsi]
golang-gomega-1.27.10/.github/dependabot.yml 0000664 0000000 0000000 00000000627 14462163431 0020567 0 ustar 00root root 0000000 0000000 version: 2
updates:
- package-ecosystem: bundler
directory: "/docs"
schedule:
interval: daily
time: '01:00'
open-pull-requests-limit: 5
- package-ecosystem: gomod
directory: "/"
schedule:
interval: daily
time: '01:00'
open-pull-requests-limit: 5
- package-ecosystem: github-actions
directory: "/"
schedule:
interval: daily
time: '01:00'
open-pull-requests-limit: 5
golang-gomega-1.27.10/.github/workflows/ 0000775 0000000 0000000 00000000000 14462163431 0017767 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/.github/workflows/codeql-analysis.yml 0000664 0000000 0000000 00000004475 14462163431 0023614 0 ustar 00root root 0000000 0000000 # For most projects, this workflow file will not need changing; you simply need
# to commit it to your repository.
#
# You may wish to alter this file to override the set of languages analyzed,
# or to provide custom queries or build logic.
#
# ******** NOTE ********
# We have attempted to detect the languages in your repository. Please check
# the `language` matrix defined below to confirm you have the correct set of
# supported CodeQL languages.
#
name: "CodeQL"
on:
push:
branches: [ master ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ master ]
schedule:
- cron: '39 17 * * 3'
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
language: [ 'go', 'ruby' ]
# CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
# Learn more:
# https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
steps:
- name: Checkout repository
uses: actions/checkout@v3
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: ${{ matrix.language }}
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# queries: ./path/to/local/query, your-org/your-repo/queries@main
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
# If this step fails, then you should remove it and run the build manually (see below)
- name: Autobuild
uses: github/codeql-action/autobuild@v2
# ℹ️ Command-line programs to run using the OS shell.
# 📚 https://git.io/JvXDl
# ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
# and modify them (or add more) to build your code if your project
# uses a compiled language
#- run: |
# make bootstrap
# make release
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2
golang-gomega-1.27.10/.github/workflows/test.yml 0000664 0000000 0000000 00000001326 14462163431 0021473 0 ustar 00root root 0000000 0000000 name: test
on: [push, pull_request]
jobs:
mod:
runs-on: ubuntu-latest
name: Check modules
steps:
- uses: actions/setup-go@v4
with:
go-version: '1.19'
- uses: actions/checkout@v3
- run: go mod tidy && git diff --exit-code go.mod go.sum
build:
runs-on: ubuntu-latest
strategy:
matrix:
version: [ '1.19', '1.20' ]
name: Go ${{ matrix.version }}
steps:
- uses: actions/setup-go@v4
with:
go-version: ${{ matrix.version }}
- uses: actions/checkout@v3
- run: go vet ./...
- run: go run github.com/onsi/ginkgo/v2/ginkgo -r --randomize-all --randomize-suites --race --trace --fail-on-pending --keep-going --label-filter="!network"
golang-gomega-1.27.10/.gitignore 0000664 0000000 0000000 00000000060 14462163431 0016356 0 ustar 00root root 0000000 0000000 .DS_Store
*.test
.
.idea
gomega.iml
TODO
.vscode golang-gomega-1.27.10/CHANGELOG.md 0000664 0000000 0000000 00000060662 14462163431 0016215 0 ustar 00root root 0000000 0000000 ## 1.27.10
### Fixes
- fix: go 1.21 adding goroutine ID to creator+location (#685) [bdc7803]
## 1.27.9
### Fixes
- Prevent nil-dereference in format.Object for boxed nil error (#681) [3b31fc3]
### Maintenance
- Bump golang.org/x/net from 0.11.0 to 0.12.0 (#679) [360849b]
- chore: use String() instead of fmt.Sprintf (#678) [86f3659]
- Bump golang.org/x/net from 0.10.0 to 0.11.0 (#674) [642ead0]
- chore: unnecessary use of fmt.Sprintf (#677) [ceb9ca6]
- Bump github.com/onsi/ginkgo/v2 from 2.10.0 to 2.11.0 (#675) [a2087d8]
- docs: fix ContainSubstring references (#673) [fc9a89f]
- Bump github.com/onsi/ginkgo/v2 from 2.9.7 to 2.10.0 (#671) [9076019]
## 1.27.8
### Fixes
- HaveExactElement should not call FailureMessage if a submatcher returned an error [096f392]
### Maintenance
- Bump github.com/onsi/ginkgo/v2 from 2.9.5 to 2.9.7 (#669) [8884bee]
## 1.27.7
### Fixes
- fix: gcustom.MakeMatcher accepts nil as actual value (#666) [57054d5]
### Maintenance
- update gitignore [05c1bc6]
- Bump github.com/onsi/ginkgo/v2 from 2.9.4 to 2.9.5 (#663) [7cadcf6]
- Bump golang.org/x/net from 0.9.0 to 0.10.0 (#662) [b524839]
- Bump github.com/onsi/ginkgo/v2 from 2.9.2 to 2.9.4 (#661) [5f44694]
- Bump commonmarker from 0.23.8 to 0.23.9 in /docs (#657) [05dc99a]
- Bump nokogiri from 1.14.1 to 1.14.3 in /docs (#658) [3a033d1]
- Replace deprecated NewGomegaWithT with NewWithT (#659) [a19238f]
- Bump golang.org/x/net from 0.8.0 to 0.9.0 (#656) [29ed041]
- Bump actions/setup-go from 3 to 4 (#651) [11b2080]
## 1.27.6
### Fixes
- Allow collections matchers to work correctly when expected has nil elements [60e7cf3]
### Maintenance
- updates MatchError godoc comment to also accept a Gomega matcher (#654) [67b869d]
## 1.27.5
### Maintenance
- Bump github.com/onsi/ginkgo/v2 from 2.9.1 to 2.9.2 (#653) [a215021]
- Bump github.com/go-task/slim-sprig (#652) [a26fed8]
## 1.27.4
### Fixes
- improve error formatting and remove duplication of error message in Eventually/Consistently [854f075]
### Maintenance
- Bump github.com/onsi/ginkgo/v2 from 2.9.0 to 2.9.1 (#650) [ccebd9b]
## 1.27.3
### Fixes
- format.Object now always includes err.Error() when passed an error [86d97ef]
- Fix HaveExactElements to work inside ContainElement or other collection matchers (#648) [636757e]
### Maintenance
- Bump github.com/golang/protobuf from 1.5.2 to 1.5.3 (#649) [cc16689]
- Bump github.com/onsi/ginkgo/v2 from 2.8.4 to 2.9.0 (#646) [e783366]
## 1.27.2
### Fixes
- improve poll progress message when polling a consistently that has been passing [28a319b]
### Maintenance
- bump ginkgo
- remove tools.go hack as Ginkgo 2.8.2 automatically pulls in the cli dependencies [81443b3]
## 1.27.1
### Maintenance
- Bump golang.org/x/net from 0.6.0 to 0.7.0 (#640) [bc686cd]
## 1.27.0
### Features
- Add HaveExactElements matcher (#634) [9d50783]
- update Gomega docs to discuss GinkgoHelper() [be32774]
### Maintenance
- Bump github.com/onsi/ginkgo/v2 from 2.8.0 to 2.8.1 (#639) [296a68b]
- Bump golang.org/x/net from 0.5.0 to 0.6.0 (#638) [c2b098b]
- Bump github-pages from 227 to 228 in /docs (#636) [a9069ab]
- test: update matrix for Go 1.20 (#635) [6bd25c8]
- Bump github.com/onsi/ginkgo/v2 from 2.7.0 to 2.8.0 (#631) [5445f8b]
- Bump webrick from 1.7.0 to 1.8.1 in /docs (#630) [03e93bb]
- codeql: add ruby language (#626) [63c7d21]
- dependabot: add bundler package-ecosystem for docs (#625) [d92f963]
## 1.26.0
### Features
- When a polled function returns an error, keep track of the actual and report on the matcher state of the last non-errored actual [21f3090]
- improve eventually failure message output [c530fb3]
### Fixes
- fix several documentation spelling issues [e2eff1f]
## 1.25.0
### Features
- add `MustPassRepeatedly(int)` to asyncAssertion (#619) [4509f72]
- compare unwrapped errors using DeepEqual (#617) [aaeaa5d]
### Maintenance
- Bump golang.org/x/net from 0.4.0 to 0.5.0 (#614) [c7cfea4]
- Bump github.com/onsi/ginkgo/v2 from 2.6.1 to 2.7.0 (#615) [71b8adb]
- Docs: Fix typo "MUltiple" -> "Multiple" (#616) [9351dda]
- clean up go.sum [cd1dc1d]
## 1.24.2
### Fixes
- Correctly handle assertion failure panics for eventually/consistnetly "g Gomega"s in a goroutine [78f1660]
- docs:Fix typo "you an" -> "you can" (#607) [3187c1f]
- fixes issue #600 (#606) [808d192]
### Maintenance
- Bump golang.org/x/net from 0.2.0 to 0.4.0 (#611) [6ebc0bf]
- Bump nokogiri from 1.13.9 to 1.13.10 in /docs (#612) [258cfc8]
- Bump github.com/onsi/ginkgo/v2 from 2.5.0 to 2.5.1 (#609) [e6c3eb9]
## 1.24.1
### Fixes
- maintain backward compatibility for Eventually and Consisntetly's signatures [4c7df5e]
- fix small typo (#601) [ea0ebe6]
### Maintenance
- Bump golang.org/x/net from 0.1.0 to 0.2.0 (#603) [1ba8372]
- Bump github.com/onsi/ginkgo/v2 from 2.4.0 to 2.5.0 (#602) [f9426cb]
- fix label-filter in test.yml [d795db6]
- stop running flakey tests and rely on external network dependencies in CI [7133290]
## 1.24.0
### Features
Introducting [gcustom](https://onsi.github.io/gomega/#gcustom-a-convenient-mechanism-for-buildling-custom-matchers) - a convenient mechanism for building custom matchers.
This is an RC release for `gcustom`. The external API may be tweaked in response to feedback however it is expected to remain mostly stable.
### Maintenance
- Update BeComparableTo documentation [756eaa0]
## 1.23.0
### Features
- Custom formatting on a per-type basis can be provided using `format.RegisterCustomFormatter()` -- see the docs [here](https://onsi.github.io/gomega/#adjusting-output)
- Substantial improvement have been made to `StopTrying()`:
- Users can now use `StopTrying().Wrap(err)` to wrap errors and `StopTrying().Attach(description, object)` to attach arbitrary objects to the `StopTrying()` error
- `StopTrying()` is now always interpreted as a failure. If you are an early adopter of `StopTrying()` you may need to change your code as the prior version would match against the returned value even if `StopTrying()` was returned. Going forward the `StopTrying()` api should remain stable.
- `StopTrying()` and `StopTrying().Now()` can both be used in matchers - not just polled functions.
- `TryAgainAfter(duration)` is used like `StopTrying()` but instructs `Eventually` and `Consistently` that the poll should be tried again after the specified duration. This allows you to dynamically adjust the polling duration.
- `ctx` can now be passed-in as the first argument to `Eventually` and `Consistently`.
## Maintenance
- Bump github.com/onsi/ginkgo/v2 from 2.3.0 to 2.3.1 (#597) [afed901]
- Bump nokogiri from 1.13.8 to 1.13.9 in /docs (#599) [7c691b3]
- Bump github.com/google/go-cmp from 0.5.8 to 0.5.9 (#587) [ff22665]
## 1.22.1
## Fixes
- When passed a context and no explicit timeout, Eventually will only timeout when the context is cancelled [e5105cf]
- Allow StopTrying() to be wrapped [bf3cba9]
## Maintenance
- bump to ginkgo v2.3.0 [c5d5c39]
## 1.22.0
### Features
Several improvements have been made to `Eventually` and `Consistently` in this and the most recent releases:
- Eventually and Consistently can take a context.Context [65c01bc]
This enables integration with Ginkgo 2.3.0's interruptible nodes and node timeouts.
- Eventually and Consistently that are passed a SpecContext can provide reports when an interrupt occurs [0d063c9]
- Eventually/Consistently will forward an attached context to functions that ask for one [e2091c5]
- Eventually/Consistently supports passing arguments to functions via WithArguments() [a2dc7c3]
- Eventually and Consistently can now be stopped early with StopTrying(message) and StopTrying(message).Now() [52976bb]
These improvements are all documented in [Gomega's docs](https://onsi.github.io/gomega/#making-asynchronous-assertions)
## Fixes
## Maintenance
## 1.21.1
### Features
- Eventually and Consistently that are passed a SpecContext can provide reports when an interrupt occurs [0d063c9]
## 1.21.0
### Features
- Eventually and Consistently can take a context.Context [65c01bc]
This enables integration with Ginkgo 2.3.0's interruptible nodes and node timeouts.
- Introduces Eventually.Within.ProbeEvery with tests and documentation (#591) [f633800]
- New BeKeyOf matcher with documentation and unit tests (#590) [fb586b3]
## Fixes
- Cover the entire gmeasure suite with leak detection [8c54344]
- Fix gmeasure leak [119d4ce]
- Ignore new Ginkgo ProgressSignal goroutine in gleak [ba548e2]
## Maintenance
- Fixes crashes on newer Ruby 3 installations by upgrading github-pages gem dependency (#596) [12469a0]
## 1.20.2
## Fixes
- label specs that rely on remote access; bump timeout on short-circuit test to make it less flaky [35eeadf]
- gexec: allow more headroom for SIGABRT-related unit tests (#581) [5b78f40]
- Enable reading from a closed gbytes.Buffer (#575) [061fd26]
## Maintenance
- Bump github.com/onsi/ginkgo/v2 from 2.1.5 to 2.1.6 (#583) [55d895b]
- Bump github.com/onsi/ginkgo/v2 from 2.1.4 to 2.1.5 (#582) [346de7c]
## 1.20.1
## Fixes
- fix false positive gleaks when using ginkgo -p (#577) [cb46517]
- Fix typos in gomega_dsl.go (#569) [5f71ed2]
- don't panic on Eventually(nil), fixing #555 (#567) [9d1186f]
- vet optional description args in assertions, fixing #560 (#566) [8e37808]
## Maintenance
- test: add new Go 1.19 to test matrix (#571) [40d7efe]
- Bump tzinfo from 1.2.9 to 1.2.10 in /docs (#564) [5f26371]
## 1.20.0
## Features
- New [`gleak`](https://onsi.github.io/gomega/#codegleakcode-finding-leaked-goroutines) experimental goroutine leak detection package! (#538) [85ba7bc]
- New `BeComparableTo` matcher(#546) that uses `gocmp` to make comparisons [e77ea75]
- New `HaveExistingField` matcher (#553) [fd130e1]
- Document how to wrap Gomega (#539) [56714a4]
## Fixes
- Support pointer receivers in HaveField; fixes #543 (#544) [8dab36e]
## Maintenance
- Bump various dependencies:
- Upgrade to yaml.v3 (#556) [f5a83b1]
- Bump github/codeql-action from 1 to 2 (#549) [52f5adf]
- Bump github.com/google/go-cmp from 0.5.7 to 0.5.8 (#551) [5f3942d]
- Bump nokogiri from 1.13.4 to 1.13.6 in /docs (#554) [eb4b4c2]
- Use latest ginkgo (#535) [1c29028]
- Bump nokogiri from 1.13.3 to 1.13.4 in /docs (#541) [1ce84d5]
- Bump actions/setup-go from 2 to 3 (#540) [755485e]
- Bump nokogiri from 1.12.5 to 1.13.3 in /docs (#522) [4fbb0dc]
- Bump actions/checkout from 2 to 3 (#526) [ac49202]
## 1.19.0
## Features
- New [`HaveEach`](https://onsi.github.io/gomega/#haveeachelement-interface) matcher to ensure that each and every element in an `array`, `slice`, or `map` satisfies the passed in matcher. (#523) [9fc2ae2] (#524) [c8ba582]
- Users can now wrap the `Gomega` interface to implement custom behavior on each assertion. (#521) [1f2e714]
- [`ContainElement`](https://onsi.github.io/gomega/#containelementelement-interface) now accepts an additional pointer argument. Elements that satisfy the matcher are stored in the pointer enabling developers to easily add subsequent, more detailed, assertions against the matching element. (#527) [1a4e27f]
## Fixes
- update RELEASING instructions to match ginkgo [0917cde]
- Bump github.com/onsi/ginkgo/v2 from 2.0.0 to 2.1.3 (#519) [49ab4b0]
- Fix CVE-2021-38561 (#534) [f1b4456]
- Fix max number of samples in experiments on non-64-bit systems. (#528) [1c84497]
- Remove dependency on ginkgo v1.16.4 (#530) [4dea8d5]
- Fix for Go 1.18 (#532) [56d2a29]
- Document precendence of timeouts (#533) [b607941]
## 1.18.1
## Fixes
- Add pointer support to HaveField matcher (#495) [79e41a3]
## 1.18.0
## Features
- Docs now live on the master branch in the docs folder which will make for easier PRs. The docs also use Ginkgo 2.0's new docs html/css/js. [2570272]
- New HaveValue matcher can handle actuals that are either values (in which case they are passed on unscathed) or pointers (in which case they are indirected). [Docs here.](https://onsi.github.io/gomega/#working-with-values) (#485) [bdc087c]
- Gmeasure has been declared GA [360db9d]
## Fixes
- Gomega now uses ioutil for Go 1.15 and lower (#492) - official support is only for the most recent two major versions of Go but this will unblock users who need to stay on older unsupported versions of Go. [c29c1c0]
## Maintenace
- Remove Travis workflow (#491) [72e6040]
- Upgrade to Ginkgo 2.0.0 GA [f383637]
- chore: fix description of HaveField matcher (#487) [2b4b2c0]
- use tools.go to ensure Ginkgo cli dependencies are included [f58a52b]
- remove dockerfile and simplify github actions to match ginkgo's actions [3f8160d]
## 1.17.0
### Features
- Add HaveField matcher [3a26311]
- add Error() assertions on the final error value of multi-return values (#480) [2f96943]
- separate out offsets and timeouts (#478) [18a4723]
- fix transformation error reporting (#479) [e001fab]
- allow transform functions to report errors (#472) [bf93408]
### Fixes
Stop using deprecated ioutil package (#467) [07f405d]
## 1.16.0
### Features
- feat: HaveHTTPStatus multiple expected values (#465) [aa69f1b]
- feat: HaveHTTPHeaderWithValue() matcher (#463) [dd83a96]
- feat: HaveHTTPBody matcher (#462) [504e1f2]
- feat: formatter for HTTP responses (#461) [e5b3157]
## 1.15.0
### Fixes
The previous version (1.14.0) introduced a change to allow `Eventually` and `Consistently` to support functions that make assertions. This was accomplished by overriding the global fail handler when running the callbacks passed to `Eventually/Consistently` in order to capture any resulting errors. Issue #457 uncovered a flaw with this approach: when multiple `Eventually`s are running concurrently they race when overriding the singleton global fail handler.
1.15.0 resolves this by requiring users who want to make assertions in `Eventually/Consistently` call backs to explicitly pass in a function that takes a `Gomega` as an argument. The passed-in `Gomega` instance can be used to make assertions. Any failures will cause `Eventually` to retry the callback. This cleaner interface avoids the issue of swapping out globals but comes at the cost of changing the contract introduced in v1.14.0. As such 1.15.0 introduces a breaking change with respect to 1.14.0 - however we expect that adoption of this feature in 1.14.0 remains limited.
In addition, 1.15.0 cleans up some of Gomega's internals. Most users shouldn't notice any differences stemming from the refactoring that was made.
## 1.14.0
### Features
- gmeasure.SamplingConfig now suppers a MinSamplingInterval [e94dbca]
- Eventually and Consistently support functions that make assertions [2f04e6e]
- Eventually and Consistently now allow their passed-in functions to make assertions.
These assertions must pass or the function is considered to have failed and is retried.
- Eventually and Consistently can now take functions with no return values. These implicitly return nil
if they contain no failed assertion. Otherwise they return an error wrapping the first assertion failure. This allows
these functions to be used with the Succeed() matcher.
- Introduce InterceptGomegaFailure - an analogue to InterceptGomegaFailures - that captures the first assertion failure
and halts execution in its passed-in callback.
### Fixes
- Call Verify GHTTPWithGomega receiver funcs (#454) [496e6fd]
- Build a binary with an expected name (#446) [7356360]
## 1.13.0
### Features
- gmeasure provides BETA support for benchmarking (#447) [8f2dfbf]
- Set consistently and eventually defaults on init (#443) [12eb778]
## 1.12.0
### Features
- Add Satisfy() matcher (#437) [c548f31]
- tweak truncation message [3360b8c]
- Add format.GomegaStringer (#427) [cc80b6f]
- Add Clear() method to gbytes.Buffer [c3c0920]
### Fixes
- Fix error message in BeNumericallyMatcher (#432) [09c074a]
- Bump github.com/onsi/ginkgo from 1.12.1 to 1.16.2 (#442) [e5f6ea0]
- Bump github.com/golang/protobuf from 1.4.3 to 1.5.2 (#431) [adae3bf]
- Bump golang.org/x/net (#441) [3275b35]
## 1.11.0
### Features
- feature: add index to gstruct element func (#419) [334e00d]
- feat(gexec) Add CompileTest functions. Close #410 (#411) [47c613f]
### Fixes
- Check more carefully for nils in WithTransform (#423) [3c60a15]
- fix: typo in Makefile [b82522a]
- Allow WithTransform function to accept a nil value (#422) [b75d2f2]
- fix: print value type for interface{} containers (#409) [f08e2dc]
- fix(BeElementOf): consistently flatten expected values [1fa9468]
## 1.10.5
### Fixes
- fix: collections matchers should display type of expectation (#408) [6b4eb5a]
- fix(ContainElements): consistently flatten expected values [073b880]
- fix(ConsistOf): consistently flatten expected values [7266efe]
## 1.10.4
### Fixes
- update golang net library to more recent version without vulnerability (#406) [817a8b9]
- Correct spelling: alloted -> allotted (#403) [0bae715]
- fix a panic in MessageWithDiff with long message (#402) [ea06b9b]
## 1.10.3
### Fixes
- updates golang/x/net to fix vulnerability detected by snyk (#394) [c479356]
## 1.10.2
### Fixes
- Add ExpectWithOffset, EventuallyWithOffset and ConsistentlyWithOffset to WithT (#391) [990941a]
## 1.10.1
### Fixes
- Update dependencies (#389) [9f5eecd]
## 1.10.0
### Features
- Add HaveHTTPStatusMatcher (#378) [f335c94]
- Changed matcher for content-type in VerifyJSONRepresenting (#377) [6024f5b]
- Make ghttp usable with x-unit style tests (#376) [c0be499]
- Implement PanicWith matcher (#381) [f8032b4]
## 1.9.0
### Features
- Add ContainElements matcher (#370) [2f57380]
- Output missing and extra elements in ConsistOf failure message [a31eda7]
- Document method LargestMatching [7c5a280]
## 1.8.1
### Fixes
- Fix unexpected MatchError() behaviour (#375) [8ae7b2f]
## 1.8.0
### Features
- Allow optional description to be lazily evaluated function (#364) [bf64010]
- Support wrapped errors (#359) [0a981cb]
## 1.7.1
### Fixes
- Bump go-yaml version to cover fixed ddos heuristic (#362) [95e431e]
## 1.7.0
### Features
- export format property variables (#347) [642e5ba]
### Fixes
- minor fix in the documentation of ExpectWithOffset (#358) [beea727]
## 1.6.0
### Features
- Display special chars on error [41e1b26]
- Add BeElementOf matcher [6a48b48]
### Fixes
- Remove duplication in XML matcher tests [cc1a6cb]
- Remove unnecessary conversions (#357) [7bf756a]
- Fixed import order (#353) [2e3b965]
- Added missing error handling in test (#355) [c98d3eb]
- Simplify code (#356) [0001ed9]
- Simplify code (#354) [0d9100e]
- Fixed typos (#352) [3f647c4]
- Add failure message tests to BeElementOf matcher [efe19c3]
- Update go-testcov untested sections [37ee382]
- Mark all uncovered files so go-testcov ./... works [53b150e]
- Reenable gotip in travis [5c249dc]
- Fix the typo of comment (#345) [f0e010e]
- Optimize contain_element_matcher [abeb93d]
## 1.5.0
### Features
- Added MatchKeys matchers [8b909fc]
### Fixes and Minor Improvements
- Add type aliases to remove stuttering [03b0461]
- Don't run session_test.go on windows (#324) [5533ce8]
## 1.4.3
### Fixes:
- ensure file name and line numbers are correctly reported for XUnit [6fff58f]
- Fixed matcher for content-type (#305) [69d9b43]
## 1.4.2
### Fixes:
- Add go.mod and go.sum files to define the gomega go module [f3de367, a085d30]
- Work around go vet issue with Go v1.11 (#300) [40dd6ad]
- Better output when using with go XUnit-style tests, fixes #255 (#297) [29a4b97]
- Fix MatchJSON fail to parse json.RawMessage (#298) [ae19f1b]
- show threshold in failure message of BeNumericallyMatcher (#293) [4bbecc8]
## 1.4.1
### Fixes:
- Update documentation formatting and examples (#289) [9be8410]
- allow 'Receive' matcher to be used with concrete types (#286) [41673fd]
- Fix data race in ghttp server (#283) [7ac6b01]
- Travis badge should only show master [cc102ab]
## 1.4.0
### Features
- Make string pretty diff user configurable (#273) [eb112ce, 649b44d]
### Fixes
- Use httputil.DumpRequest to pretty-print unhandled requests (#278) [a4ff0fc, b7d1a52]
- fix typo floa32 > float32 (#272) [041ae3b, 6e33911]
- Fix link to documentation on adding your own matchers (#270) [bb2c830, fcebc62]
- Use setters and getters to avoid race condition (#262) [13057c3, a9c79f1]
- Avoid sending a signal if the process is not alive (#259) [b8043e5, 4fc1762]
- Improve message from AssignableToTypeOf when expected value is nil (#281) [9c1fb20]
## 1.3.0
Improvements:
- The `Equal` matcher matches byte slices more performantly.
- Improved how `MatchError` matches error strings.
- `MatchXML` ignores the order of xml node attributes.
- Improve support for XUnit style golang tests. ([#254](https://github.com/onsi/gomega/issues/254))
Bug Fixes:
- Diff generation now handles multi-byte sequences correctly.
- Multiple goroutines can now call `gexec.Build` concurrently.
## 1.2.0
Improvements:
- Added `BeSent` which attempts to send a value down a channel and fails if the attempt blocks. Can be paired with `Eventually` to safely send a value down a channel with a timeout.
- `Ω`, `Expect`, `Eventually`, and `Consistently` now immediately `panic` if there is no registered fail handler. This is always a mistake that can hide failing tests.
- `Receive()` no longer errors when passed a closed channel, it's perfectly fine to attempt to read from a closed channel so Ω(c).Should(Receive()) always fails and Ω(c).ShoudlNot(Receive()) always passes with a closed channel.
- Added `HavePrefix` and `HaveSuffix` matchers.
- `ghttp` can now handle concurrent requests.
- Added `Succeed` which allows one to write `Ω(MyFunction()).Should(Succeed())`.
- Improved `ghttp`'s behavior around failing assertions and panics:
- If a registered handler makes a failing assertion `ghttp` will return `500`.
- If a registered handler panics, `ghttp` will return `500` *and* fail the test. This is new behavior that may cause existing code to break. This code is almost certainly incorrect and creating a false positive.
- `ghttp` servers can take an `io.Writer`. `ghttp` will write a line to the writer when each request arrives.
- Added `WithTransform` matcher to allow munging input data before feeding into the relevant matcher
- Added boolean `And`, `Or`, and `Not` matchers to allow creating composite matchers
- Added `gbytes.TimeoutCloser`, `gbytes.TimeoutReader`, and `gbytes.TimeoutWriter` - these are convenience wrappers that timeout if the underlying Closer/Reader/Writer does not return within the alloted time.
- Added `gbytes.BufferReader` - this constructs a `gbytes.Buffer` that asynchronously reads the passed-in `io.Reader` into its buffer.
Bug Fixes:
- gexec: `session.Wait` now uses `EventuallyWithOffset` to get the right line number in the failure.
- `ContainElement` no longer bails if a passed-in matcher errors.
## 1.0 (8/2/2014)
No changes. Dropping "beta" from the version number.
## 1.0.0-beta (7/8/2014)
Breaking Changes:
- Changed OmegaMatcher interface. Instead of having `Match` return failure messages, two new methods `FailureMessage` and `NegatedFailureMessage` are called instead.
- Moved and renamed OmegaFailHandler to types.GomegaFailHandler and OmegaMatcher to types.GomegaMatcher. Any references to OmegaMatcher in any custom matchers will need to be changed to point to types.GomegaMatcher
New Test-Support Features:
- `ghttp`: supports testing http clients
- Provides a flexible fake http server
- Provides a collection of chainable http handlers that perform assertions.
- `gbytes`: supports making ordered assertions against streams of data
- Provides a `gbytes.Buffer`
- Provides a `Say` matcher to perform ordered assertions against output data
- `gexec`: supports testing external processes
- Provides support for building Go binaries
- Wraps and starts `exec.Cmd` commands
- Makes it easy to assert against stdout and stderr
- Makes it easy to send signals and wait for processes to exit
- Provides an `Exit` matcher to assert against exit code.
DSL Changes:
- `Eventually` and `Consistently` can accept `time.Duration` interval and polling inputs.
- The default timeouts for `Eventually` and `Consistently` are now configurable.
New Matchers:
- `ConsistOf`: order-independent assertion against the elements of an array/slice or keys of a map.
- `BeTemporally`: like `BeNumerically` but for `time.Time`
- `HaveKeyWithValue`: asserts a map has a given key with the given value.
Updated Matchers:
- `Receive` matcher can take a matcher as an argument and passes only if the channel under test receives an objet that satisfies the passed-in matcher.
- Matchers that implement `MatchMayChangeInTheFuture(actual interface{}) bool` can inform `Eventually` and/or `Consistently` when a match has no chance of changing status in the future. For example, `Receive` returns `false` when a channel is closed.
Misc:
- Start using semantic versioning
- Start maintaining changelog
Major refactor:
- Pull out Gomega's internal to `internal`
golang-gomega-1.27.10/CONTRIBUTING.md 0000664 0000000 0000000 00000001637 14462163431 0016632 0 ustar 00root root 0000000 0000000 # Contributing to Gomega
Your contributions to Gomega are essential for its long-term maintenance and improvement. To make a contribution:
- Please **open an issue first** - describe what problem you are trying to solve and give the community a forum for input and feedback ahead of investing time in writing code!
- Ensure adequate test coverage:
- Make sure to add appropriate unit tests
- Please run all tests locally (`ginkgo -r -p`) and make sure they go green before submitting the PR
- Please run following linter locally `go vet ./...` and make sure output does not contain any warnings
- Update the documentation. In addition to standard `godoc` comments Gomega has extensive documentation on the `gh-pages` branch. If relevant, please submit a docs PR to that branch alongside your code PR.
If you're a committer, check out RELEASING.md to learn how to cut a release.
Thanks for supporting Gomega!
golang-gomega-1.27.10/LICENSE 0000664 0000000 0000000 00000002046 14462163431 0015401 0 ustar 00root root 0000000 0000000 Copyright (c) 2013-2014 Onsi Fakhouri
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
golang-gomega-1.27.10/README.md 0000664 0000000 0000000 00000001715 14462163431 0015655 0 ustar 00root root 0000000 0000000 
[](https://github.com/onsi/gomega/actions/workflows/test.yml)
Jump straight to the [docs](http://onsi.github.io/gomega/) to learn about Gomega, including a list of [all available matchers](http://onsi.github.io/gomega/#provided-matchers).
If you have a question, comment, bug report, feature request, etc. please open a GitHub issue.
## [Ginkgo](http://github.com/onsi/ginkgo): a BDD Testing Framework for Golang
Learn more about Ginkgo [here](http://onsi.github.io/ginkgo/)
## Community Matchers
A collection of community matchers is available on the [wiki](https://github.com/onsi/gomega/wiki).
## License
Gomega is MIT-Licensed
The `ConsistOf` matcher uses [goraph](https://github.com/amitkgupta/goraph) which is embedded in the source to simplify distribution. goraph has an MIT license.
golang-gomega-1.27.10/RELEASING.md 0000664 0000000 0000000 00000001530 14462163431 0016224 0 ustar 00root root 0000000 0000000 A Gomega release is a tagged sha and a GitHub release. To cut a release:
1. Ensure CHANGELOG.md is up to date.
- Use
```bash
LAST_VERSION=$(git tag --sort=version:refname | tail -n1)
CHANGES=$(git log --pretty=format:'- %s [%h]' HEAD...$LAST_VERSION)
echo -e "## NEXT\n\n$CHANGES\n\n### Features\n\n### Fixes\n\n### Maintenance\n\n$(cat CHANGELOG.md)" > CHANGELOG.md
```
to update the changelog
- Categorize the changes into
- Breaking Changes (requires a major version)
- New Features (minor version)
- Fixes (fix version)
- Maintenance (which in general should not be mentioned in `CHANGELOG.md` as they have no user impact)
1. Update GOMEGA_VERSION in `gomega_dsl.go`
1. Commit, push, and release:
```
git commit -m "vM.m.p"
git push
gh release create "vM.m.p"
git fetch --tags origin master
``` golang-gomega-1.27.10/docs/ 0000775 0000000 0000000 00000000000 14462163431 0015322 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/docs/.gitignore 0000664 0000000 0000000 00000000075 14462163431 0017314 0 ustar 00root root 0000000 0000000 _site
.sass-cache
.jekyll-cache
.jekyll-metadata
vendor
golang-gomega-1.27.10/docs/Gemfile 0000664 0000000 0000000 00000002176 14462163431 0016623 0 ustar 00root root 0000000 0000000 source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
# bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
# gem "jekyll", "~> 4.2.1"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", "~> 228", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
gem "jekyll-feed", "~> 0.12"
end
gem "webrick"
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
gem "tzinfo", "~> 1.2"
gem "tzinfo-data"
end
# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
golang-gomega-1.27.10/docs/Gemfile.lock 0000664 0000000 0000000 00000016421 14462163431 0017550 0 ustar 00root root 0000000 0000000 GEM
remote: https://rubygems.org/
specs:
activesupport (6.0.6.1)
concurrent-ruby (~> 1.0, >= 1.0.2)
i18n (>= 0.7, < 2)
minitest (~> 5.1)
tzinfo (~> 1.1)
zeitwerk (~> 2.2, >= 2.2.2)
addressable (2.8.1)
public_suffix (>= 2.0.2, < 6.0)
coffee-script (2.4.1)
coffee-script-source
execjs
coffee-script-source (1.11.1)
colorator (1.1.0)
commonmarker (0.23.9)
concurrent-ruby (1.2.0)
dnsruby (1.61.9)
simpleidn (~> 0.1)
em-websocket (0.5.3)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0)
ethon (0.16.0)
ffi (>= 1.15.0)
eventmachine (1.2.7)
execjs (2.8.1)
faraday (2.7.4)
faraday-net_http (>= 2.0, < 3.1)
ruby2_keywords (>= 0.0.4)
faraday-net_http (3.0.2)
ffi (1.15.5)
forwardable-extended (2.6.0)
gemoji (3.0.1)
github-pages (228)
github-pages-health-check (= 1.17.9)
jekyll (= 3.9.3)
jekyll-avatar (= 0.7.0)
jekyll-coffeescript (= 1.1.1)
jekyll-commonmark-ghpages (= 0.4.0)
jekyll-default-layout (= 0.1.4)
jekyll-feed (= 0.15.1)
jekyll-gist (= 1.5.0)
jekyll-github-metadata (= 2.13.0)
jekyll-include-cache (= 0.2.1)
jekyll-mentions (= 1.6.0)
jekyll-optional-front-matter (= 0.3.2)
jekyll-paginate (= 1.1.0)
jekyll-readme-index (= 0.3.0)
jekyll-redirect-from (= 0.16.0)
jekyll-relative-links (= 0.6.1)
jekyll-remote-theme (= 0.4.3)
jekyll-sass-converter (= 1.5.2)
jekyll-seo-tag (= 2.8.0)
jekyll-sitemap (= 1.4.0)
jekyll-swiss (= 1.0.0)
jekyll-theme-architect (= 0.2.0)
jekyll-theme-cayman (= 0.2.0)
jekyll-theme-dinky (= 0.2.0)
jekyll-theme-hacker (= 0.2.0)
jekyll-theme-leap-day (= 0.2.0)
jekyll-theme-merlot (= 0.2.0)
jekyll-theme-midnight (= 0.2.0)
jekyll-theme-minimal (= 0.2.0)
jekyll-theme-modernist (= 0.2.0)
jekyll-theme-primer (= 0.6.0)
jekyll-theme-slate (= 0.2.0)
jekyll-theme-tactile (= 0.2.0)
jekyll-theme-time-machine (= 0.2.0)
jekyll-titles-from-headings (= 0.5.3)
jemoji (= 0.12.0)
kramdown (= 2.3.2)
kramdown-parser-gfm (= 1.1.0)
liquid (= 4.0.4)
mercenary (~> 0.3)
minima (= 2.5.1)
nokogiri (>= 1.13.6, < 2.0)
rouge (= 3.26.0)
terminal-table (~> 1.4)
github-pages-health-check (1.17.9)
addressable (~> 2.3)
dnsruby (~> 1.60)
octokit (~> 4.0)
public_suffix (>= 3.0, < 5.0)
typhoeus (~> 1.3)
html-pipeline (2.14.3)
activesupport (>= 2)
nokogiri (>= 1.4)
http_parser.rb (0.8.0)
i18n (1.12.0)
concurrent-ruby (~> 1.0)
jekyll (3.9.3)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
i18n (>= 0.7, < 2)
jekyll-sass-converter (~> 1.0)
jekyll-watch (~> 2.0)
kramdown (>= 1.17, < 3)
liquid (~> 4.0)
mercenary (~> 0.3.3)
pathutil (~> 0.9)
rouge (>= 1.7, < 4)
safe_yaml (~> 1.0)
jekyll-avatar (0.7.0)
jekyll (>= 3.0, < 5.0)
jekyll-coffeescript (1.1.1)
coffee-script (~> 2.2)
coffee-script-source (~> 1.11.1)
jekyll-commonmark (1.4.0)
commonmarker (~> 0.22)
jekyll-commonmark-ghpages (0.4.0)
commonmarker (~> 0.23.7)
jekyll (~> 3.9.0)
jekyll-commonmark (~> 1.4.0)
rouge (>= 2.0, < 5.0)
jekyll-default-layout (0.1.4)
jekyll (~> 3.0)
jekyll-feed (0.15.1)
jekyll (>= 3.7, < 5.0)
jekyll-gist (1.5.0)
octokit (~> 4.2)
jekyll-github-metadata (2.13.0)
jekyll (>= 3.4, < 5.0)
octokit (~> 4.0, != 4.4.0)
jekyll-include-cache (0.2.1)
jekyll (>= 3.7, < 5.0)
jekyll-mentions (1.6.0)
html-pipeline (~> 2.3)
jekyll (>= 3.7, < 5.0)
jekyll-optional-front-matter (0.3.2)
jekyll (>= 3.0, < 5.0)
jekyll-paginate (1.1.0)
jekyll-readme-index (0.3.0)
jekyll (>= 3.0, < 5.0)
jekyll-redirect-from (0.16.0)
jekyll (>= 3.3, < 5.0)
jekyll-relative-links (0.6.1)
jekyll (>= 3.3, < 5.0)
jekyll-remote-theme (0.4.3)
addressable (~> 2.0)
jekyll (>= 3.5, < 5.0)
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
rubyzip (>= 1.3.0, < 3.0)
jekyll-sass-converter (1.5.2)
sass (~> 3.4)
jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-sitemap (1.4.0)
jekyll (>= 3.7, < 5.0)
jekyll-swiss (1.0.0)
jekyll-theme-architect (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-cayman (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-dinky (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-hacker (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-leap-day (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-merlot (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-midnight (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-minimal (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-modernist (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-primer (0.6.0)
jekyll (> 3.5, < 5.0)
jekyll-github-metadata (~> 2.9)
jekyll-seo-tag (~> 2.0)
jekyll-theme-slate (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-tactile (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-theme-time-machine (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-titles-from-headings (0.5.3)
jekyll (>= 3.3, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
jemoji (0.12.0)
gemoji (~> 3.0)
html-pipeline (~> 2.2)
jekyll (>= 3.0, < 5.0)
kramdown (2.3.2)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.4)
listen (3.8.0)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.3.6)
minima (2.5.1)
jekyll (>= 3.5, < 5.0)
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
minitest (5.17.0)
nokogiri (1.14.3-x86_64-linux)
racc (~> 1.4)
octokit (4.25.1)
faraday (>= 1, < 3)
sawyer (~> 0.9)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (4.0.7)
racc (1.6.2)
rb-fsevent (0.11.2)
rb-inotify (0.10.1)
ffi (~> 1.0)
rexml (3.2.5)
rouge (3.26.0)
ruby2_keywords (0.0.5)
rubyzip (2.3.2)
safe_yaml (1.0.5)
sass (3.7.4)
sass-listen (~> 4.0.0)
sass-listen (4.0.0)
rb-fsevent (~> 0.9, >= 0.9.4)
rb-inotify (~> 0.9, >= 0.9.7)
sawyer (0.9.2)
addressable (>= 2.3.5)
faraday (>= 0.17.3, < 3)
simpleidn (0.2.1)
unf (~> 0.1.4)
terminal-table (1.8.0)
unicode-display_width (~> 1.1, >= 1.1.1)
thread_safe (0.3.6)
typhoeus (1.4.0)
ethon (>= 0.9.0)
tzinfo (1.2.10)
thread_safe (~> 0.1)
unf (0.1.4)
unf_ext
unf_ext (0.0.8.2)
unicode-display_width (1.8.0)
webrick (1.8.1)
zeitwerk (2.6.6)
PLATFORMS
x86_64-linux
DEPENDENCIES
github-pages (~> 228)
jekyll-feed (~> 0.12)
minima (~> 2.5)
tzinfo (~> 1.2)
tzinfo-data
wdm (~> 0.1.1)
webrick
BUNDLED WITH
2.3.22
golang-gomega-1.27.10/docs/_config.yml 0000664 0000000 0000000 00000000240 14462163431 0017445 0 ustar 00root root 0000000 0000000 baseurl: "/gomega" # the subpath of your site, e.g. /blog
# Build settings
name: Gomega
markdown: GFM
highlighter: rouge
lsi: false
exclude:
- "*.go" golang-gomega-1.27.10/docs/_layouts/ 0000775 0000000 0000000 00000000000 14462163431 0017161 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/docs/_layouts/default.html 0000664 0000000 0000000 00000002612 14462163431 0021474 0 ustar 00root root 0000000 0000000
*NeC IDATxohUulY۪YmֵZz9!)ai0j
%" "ϋ^+P ͡3ˢ5sV}s9wϋ<߿755"*$j}6P n2`\gG\^$SE, [%
P^mஈ./s
a ff8>dQФ lSgCn w@=
PfIXGl
^/SI( l^ca
0|
P` aQ>h+ 0x+Q dhP!OG7@p, @{- iާ9G 3~FQ)%mgKvC|?DZ~ ~ OV1?7 ;yemb 1 -1A]= `4lqߺV3t"@cg2N[cY
rVm4" zBinu:'nUŶ*?ﵔF.t`B̫UI۟R$>a]Nd+y]ǃtz|rVv!G,[ |c* 䱿}G x?
Y>uvN`ƭGK$;qkfAFn <8ٶ0 !1xdipo;%!?±86WrDf^q8C81qڳ({0hï# .
#EN5!. 3*-\. oJiOfs}JvfN%YG5LGo]J: xMn# :ا TOZ&] /si}Ў!lhԡkW2 ~mU^vvOmz0}XYB_
-Bs_ IENDB` golang-gomega-1.27.10/docs/images/go.png 0000664 0000000 0000000 00000012431 14462163431 0017703 0 ustar 00root root 0000000 0000000 PNG
IHDR d !Zdr sRGB eXIfMM * V ^( 1 fi | , , Pixelmator Pro 2.1.5 Ϡ d 2021:10:14 11:28:55 [ pHYs .# .#x?v iTXtXML:com.adobe.xmp
207
100
3000000/10000
3000000/10000
1
2
Pixelmator Pro 2.1.5
2021-10-14T11:28:55-06:00
2021-10-14T11:31:18-06:00
ʸ ,IDATx E{bK EiJ)[SQ-RCOVB[(AP{Ҋ% IŖDd|;3ｳ7yܹs|+1p 8 ǀc1p 8 ǀc1p 8 ǀc1p 8 ǀc1@;Kz 455Fu*` X
kn1G'eu*S{`
>C߫%ςT 8BmM
,`!p\iR(Y %_.Za |ě$T:E8#2C?<f jNuYY ?2LVq
i{$ev@qZ Ht 1 y?j o" whߥ<4Nq (ʬWa8J?Z4; *c' f$ DNI´ku[ m]^&a_d_]HZԤ8΄2w 5m6eM THى+-#w ^-?i
KZh+sg-hf%)Yǀ^.j
@u h rw?<*)?G2GWi@ך&Z;L5+ )-hQ}Țǡ᫂tXNz
%]^E[+ <[gn] *!G+R< , l[
M7sx5? 8&E;, /o۲Gtڡj[M><]̱q qn`a Qah%F]@\q@~ ̦8-1c
op%}s3pXE;wC~{:ֿ s 5|ƥz|#Au_kwuF?Ъgz{`<>_rE8܂/ϸPP: ^ < ߇Г/ =gu
[Sw Fi1%huΉ ȢՒs[2š';
){:F-y
lػRa4$Oj4jFmKuc7vۃw
U'o{X 6 s/y=4i>r_dw{`ɫp5UbS܆]܊U(kMaՒNUژ\0;G0SǙh.p3ޒj,u 8ZӒ#zIW ǫ>owKoKLFoL'> l||
8A9hI5\-;Yz%GΠNZ E%C( O/
AĮy\7y0 CzjԆk~Gc9\?L%G-4}uu6'jy4wᠠָ:}ɫ+yq]3zS y=&;Ϛʫ>A̢5T2>ҵbBoqަlb֭:\ S
'u4-c F3YPU;u5LrY܌9ɗQk*t0m2-oseG)G%*zM,q ZM<=jōNǸrq܌97Лf ҰtɆ\Ͽ?@S&e֪j j[C nrFͰ_MfF Mw QŨ7 YL}̗l33,3g [ U`g߹/Fxh Ȱ (
;5]h8\饠=zA0OQ+2f'$ Lw*Pt8rg]3JYxl@q0Mxwj]
}Mtu/,P37CG ~dQtJ'I Ɵ{ ?_qKʅ害:. o
z]:yb?CnTJ:i ?
~kf:yJiǰQ͉!DI'CU
.w4ВMADCU3mY3+& Bu Rϓv)4
dJ=?Dg ^)22,
.mJ BD#n"$Ph"b xR~֑c .z1MgC I iaK
#r F*+vw%"e
OJjvC}MBYv`z(bF[ʃxu F~0{CA5+TniŭaCZa [2 RZ/v'L 82w(НGDD- cmv tkՁ45
{s*8」|0dS`b{ۢo^m ' ![Pөdl`ѫqsϖӓvKubէw6燙 =]>6N+_Q|
t?\V5ď+`.-_BY' ZB.ZM C ݅4-u|@>%!f bey?
b芥Nl,_& ? |Ԕw`w$HRǘ.@ 7s.\/U_x~ Ks;?@A$$ G`>ЂE͜ml9BmUYcpAa^Ŷ? KAgH 0=ˈʺ!{VJd:b;qm-韉^4OZ뇟 nr_C NnEFS:N?㸤 )45;TXeSi]S-DZU
uTR̺/ź40z^O{5$nfr>
GQɪlO @e(.՝GV&]{):H K4x8hpҺ
GzKJy8<h"(r% S!C_b|t *#+Nkof^Xy
bii)雈PqR/fi Z ȣӺ X 䑜Z7SPs-5b;[@^d^Yr -r}M&pL32B&_ f'+Y9*=H nYk$ vC ,Ȣ©@^,VOlE!Ӕ1>dj̎?@d
Nh\$+ P!`>HJbh8-+<w(
>=|榪#K%ic p$t&ET0&?`Cя=;l>Fq<
PNCј 7]AWaE/g 9 !> tΠ"M/~.>1胈3iash8FF+ZtgڲvJ8 ėǀc1p 8 ǀc1p 8 ǀc1p 8 ǀc1p 8 ǀc\ s IENDB` golang-gomega-1.27.10/docs/images/gomega.png 0000664 0000000 0000000 00000124416 14462163431 0020544 0 ustar 00root root 0000000 0000000 PNG
IHDR
^ TD sRGB eXIfMM * V ^( 1 fi | H H Pixelmator Pro 2.3.4
^ pHYs iTXtXML:com.adobe.xmp
350
1546
1
720000/10000
2
720000/10000
1
Pixelmator Pro 2.3.4
2022-01-17T14:21:54-07:00
5 @ IDATx]EM
$BB@:$, " lEAEDD& {}߁6a+dw)yyeB @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ CQq
4 Aug#c}< &]_{?t.w.Η"}YyC @ @ 8EBSA0UQݤä[V Z+JΒNK_ @ @ P(H 9c"0Tv# #]_꣬VV4xDf @ @ P(H 1b `[-_obSzR @ @ @(Ď1GI *"ͳ}`poR'@ @ @ @29Lz=lHw" @ @ / (ꃤWKm
3hgJI@ @ @ ++cQ<,=NN@ @ @ !]|\@ 7v @ @ |A lkۤK@ @ @ @j&OJm l5IR% @ @ !※ S&` @ @ CXyLJ [
@ @ @ y$p~PJ_GK @ @ P91v)pܥ [K+! @ @ @ +ܤ8AbOjiO)@ @ @ xc)riӁe @ @ @<%(? @ @ ImW hZZH@ @ @ @NKy$m:`|^s'M@ @ @ %]LJQ ͽaE$ @ @ $rbkrN @ @ @t`0k!^v" @ @ 1]9^sǯB @ @ k{+Җ9R^:=H @ @ 8vBiҾՙj}XiOR+. @ @ (ⴁS>aA @ @ =."'iY9{m @ @ '"O$ l/wH& )]#C @ @ PP ?_ @%` eqbAI @ @ 51z=z@J
$9A @ @ )Rdؽl%dcX-KcA@ @ @,̸,\N6U!S j@W {iVCC @ @ `&o2\Ӱz%ؓm|$I` },I'؆ @ @ '@y. INu=P@S;ƚ @ @ cg)&`75%3iG؇ @ @ &͌óo*}!P&O29 @ @ P% `ʗ 'wH 9#]S|A @ @ (u
)mςTO`L̕ }~.E҅ҵRjiS'mW=Qjw T 5Wp @ @ @ PP .- \WI>)R+$%d
cH. &E&Р&3nJ @ @ @ p,e1;K]:QmC) @ @ BNʠr /NYj3߷28E\@ @ @ &N?*eeJnR_o
B)}&j@ @ @ H咁(6gI-yAqfj~E0 @ @ ؍oJ0ޚΔv*V0PT_&} @ @ S}i+ Ґ ۾OҦ,m @ @ @ޫ6Zwz+s1
پ> @ @ Ґ~KͶ:<ޭ? ~u]* %/K0_CT @ @ @{jc{_L`NKe緌3 @ @ pm6xm{02,lߤqwݖmEU8Y @ @ @ gr.pl5 |{%sBJ\hiG R ЮqPţ +Xq
bcmXWK5Qc!i(Զ[[} .H{v^Q(G @ @ Ȝ@2 l Wf]]ӟ6ތ7IR,C ro/}r顅56BxQk͍z[ sGE@ @ rMB 9xu^rhł)VX1Nfr0u{LY{.XrdaAņM~mUSXV!S3`Oz#Z@ @ PFg?0q#Ԣצ1lG ҃N.ֿ O'S 7²GV.dU轨Ыߣ;_=߁@ @ ` P(ȾkT>T#")_5|g}#ၧxΤWwCSE-,]1< _,]#'G+oQ@ @ /
?B f7%)= F`,=*ubOزzt艷 H Yeƌ
K|rَq F K~m<3OV@ @ k
r_!}<~-urxE)[}! SOow>p%KCQ
^}
<@B @ @
@Sxur{F6sgC1uۋ6w_`av1͗vŚְsg q|>B @ @ n g>uI
{Χ^J? NOT%ث Z|z`D xԭׂhNvޮY @ @ (dy7)ٹOfWR
-crf%d9.]=}@ԩ__>lKċ @ P(Ȧ[۞C6S(oK L+ζSI`W>J)>0
t*9M"оhЈB2 @ڌج@ivn}pu6:WHm> ץåIGJ{▿֏֦Vj2"M/JKEo jVi dMZڣ7٨6YY5n-O6i{^F<
iWjw̵IskuVwk{{ ۢ)<guRl[n-lwdߡjݥ͉}"]jeXvގw, zp"@L&~%{_!W yqWsavѾ :bW^v}B"бӆh/ן?Bolm_ҷm 7iҩA LЂXQ !R/+m?t>-g~"~GKJGm~lK4mQi:S^@ c? Z -'G>!}@jB WI.FsפAČs6[zۂCBA}A._> ,ݴaL*;;ei;FnO˙O~F`ѼYC6kXjڵ_u8бbv켤]a͊v,[;iÀbcCBcCBcc *]w ~Or718鑛uS.
:CjΑY:*åK\w
>,Bߥ6c@KzāR{߱>R'#oJ)].E P
.}tfk(V ݿI;j) tRpVT@S r֨klZڊOJ`8G8 %Їd uͤڱAٮxlPy}&WB -jkWc?Z\dj$zmTSzyЫϟfZfS.rbG>:-b]pg˽^(OOjR,Fc.?^E)qS4x>c}IѦ8]"0R
:Q$xgӟzpi ٵR$mH=EWYlƙV Mjt" )6!ҩR{#~033.}(>lv2 \$`Δ$K)B2JoR#` "miJݺha`Z[ޖ0"N,
Fcq.9d^
_g&{Vy/u7;uمK9L KyGNV8S>-ߔ 4</5:Rۮi 59CzOMi5__JIPeVG&0GM>$}-3x61Sm;g.&ic M ) &! RFm>
퇻Fݸt{o[R 2/42"МDQ+=(%Hr9HM
`3q
M$`yVIJM.yy%K幷rTl%PǦ
iۗcw\.4C-sm9?0; E 3ߙ
d;Y*jU*m^6oV;"8 g
p+et;Y),x@Vo)3=VBt,tA%@Y, (k/|Ҡ
~D$u!%co& h[Bf|Vq&ǍSur^.: $*?J'K;R9a[%)uI:əm lBl Iݫ2" Hxw؞f(3K*(V/iBO.7Ǔw Rد RjZ=fμA5
)qW=m?]RN yF\)X0M<ΩWô7ڗF YA磫-goy_+HwD`77Iˢ->+川}g+
^%FHAG1Iٽ":-JbAv}n2|wI9n{d韥}$6U#Y9s PPJ_7~ʩ Ѿow
rx@ߑ}3RK_s& i݀a͝XU~[/,6pvd;Eu~p) +=&뛏ߤ b',o)K
S$0AJOK'#`㒶phv!
a2 DI?E[v&d; N;S+>j {`geI]{[+f.`t n^Ff:{ kv}n"~S
tAQ w۶cpG\2[+D?镱RqR{sFj p3љZN/mg')[fؗ TV%6j Nmm˸&Mwś5 |ϐn= ܾN+-^ Qs| m/)VP6VilE[-PB(ڻq?} }}AAQvkLvGu߰euyvJF#=9F,ӝm`{ZS$(\;ɞ8wn+)[A[}RiNB{R {ϸE@gyܒhe}O-#^/Jlt($w-[5 0Uc=hh }Oة
摓!ġ^ <:WEɦcv[lV KtmM>%Ylu/&i@m w*{R2y4QpM
ǹ3n!r"-E \"`Twhb' <9!>&; O=LW˝˱_ϣ }q,xi-G#`[)|N=sk!l&m ?|hpIf b%ł Gjv"Aije6yi/ϖ"+(g+lU B䜗-O
|r$W*IL .k B~8% S9 }˹6nPي˹זs n
+xa
GڶAڼ
\ {i~KJK!` &uv3Zd@~7\_\M7"A۬bwb, J?d^udL;aNDA6ntnMT5O;Z)Þ}lP7 rYݸf|f7dƶ@ ph,;0uR+!¡p0'@.>Gn g3&p q ߚ}n}ghM9ų
t-B T@`e3?]XԪnINWf?Ɛ2LK]הqI*Mʘ_,NNRoNf>DQ}l;7sCnUZ|^$C,:=D +}nlhM!op)]/{ !nZaU}ST#}
X!@ !ߟ)! 6B lYFv\arblTӮ r1h]3_Ab=c_u WC @=Eھ\/5o9:T!Q$p_҈hN{w՟)R+^E>x鲐 }4@\bTݳʽ,_' _cKUUu
cf.p# :?-%lE`;f_hlie^++ԏ' #_df${
}<-gq ded:a ' xF`3*^ڝN 8d*_|渱7/gx;
ILYmc.y6rxn0FP$pK2 #̼:m;&/ UH JJ}h NZΪԖ\g4:WB`
an)mSoӱW e3* ]K
W{[ҩ OD =|H15 ^T .KO$
4®(:]tNJP x_8xP;'0Dq>S @+.-*. +
Q2bH=%"A`L+yM
H ;qseƺ5 7,qs )b"OO+X>ֱڽ_m}(gV\"A[UR7aUYb?a12'p"Hy7IH P(o9 @c/+l{Ү]\^`~F4]~Qiu3< 9 }_ĢHۯ~K+Zhۈ49{Zc; 힅s|Bc=$zU(OBAL/ Lإ8w֗\
>87QẀ]{ -C d 0t^e 0Vi0 Uܡ9ɕ4!'8bk Y)J`}vX)P(Z" 2
?rmf?nMHmpӶ`|l YVBcGJKCJri$K9 [e{:ibGZ]mIjH8
'2Yg^#7*y6onޣNU)
!se e@Bef-O>f! kAq\N{I&c !1g/ѰQgl)Rj
*,yR$"}
6im NtVKO
4yN Z""×wCNѶC1YE)F~+ԥ2~ّ*(e_lnV#=u$ۥ")һ6>tٻ7Ӆ"N g2z<9q/9+6gR+e-}Ajo,7_'}X!yi'i^Ķ'ҵ&mO^$I|(P!u?N<mE=kVJaRxq 8/ۤgKw )]np8Lf^qf}Q68Aj3&6(ä;+f Q^UR6Xe[\-uH0^<
VX/6 RB{}ـu Ċ_@e@_Ⱦ)
VN$w+={ľoSj+C]H K(Χܳ.Dy!Ĥ q=ʛ#G#ƺQOMU._*\ Gd
\)$& 2oھHyj~~le4
('HC:]Uz셊ø[ fw #-Q|]t0~l$d Mj}u`Ϥ >bo,9z|&^"=8'ːP_G2PgF< &,A L
3j5piVmuY^UpK v9*cVi#/MQ~^}+ ޙ4teۗs䐵; Jv//J8nwݝP
>4a+vB:P(B̡a#0XSX'NlV "טG5yvSĒGW6`X}9>ءu` {;!
b2Q03Cyؖd%t4ܺ*zAV Ah*)RaRU$w+ H{zAP_wϔSl\N#\uG}H8E 2z^Ņw=Fq >Y ^OL
AR ƶB"җjy?b۬0Vt/Nw Cz%d-B,l髟7s^Xz(sMh
Pq P,q!ܦl% 9hlۡKJ'5}\ .@4yniˁ/} KVM2ϓ⽧L6X|Jmv[6)dQ~*
iHmkJ0YѾ_&_y6Bjߣ@ ȁJ$@DP%4 uE:&$0v||Sv#U$5}3e,.^`CH<ʌ |@ oJ3!lt
uyE`3}*>'Pau)vQl> N
)Vr|O>JN%K`dͧf圥PP-B m<1
yY}0ȏUzP4LB
Gue?諎3j+nAJlQ%Wb;%A @ IDATrk.:ɛ5%UbPwӤ$Y #=p͝99ȑ"m Z(Xcg3 иxiGԽjmp}ڷPs̔ a]@̃SI:D|BX [j`-O k1*mf^I$jŖf
ThSsras=?6Gyۆ?`SNYGSA0X;ޛ%^v[nǏb͚UrG$}y& SNYhr*L>Y',k=u=]YVKpY]o+mBvzS>";Q%mnz pKDӘ|}ۈg8S+|ȗk{n NtSw9H[AlnµEgŶamo& cS2/ǽRJ 5KiHjuN> I{ϫvRtAޡl;d_v1<v'Yv𡗈
@8 WQn\Wx6=oxj@>Ճˁcm\-솘U&6HXV(8c*y ϖ[05WGvҳsW(W=9pc-NwsZؙet(7Dk 6y3/'VݴǮ,8 V\`\qdK4-,
]BڂΥB(>FmOcO:l߹ -@YOmyHRo ְG>ijOnfO :~MI@z($xZmXJJT §bMEC%(/?R6?ڨ Cuo
|2~'ط=R8y =yk9ߓXӶx,m1ߥYzƘS3>byi\*ׇ2?U!U"rX 2,z}6b慴oƋ8 kVN0^Db+0#:_cA@b"mEH\"z)wRtw]S崷yس2n욆IOlzo Lo A$ hs}\to+{Z$@E4 t=xmKqْ;>SXZMmTMja+Bxض*+܌Y[_nYwwf Dm J[B)ܚ68OM7x;aC I1I:6 @ >=]f!,-3eCeѪe|ֽ3Eψ.=)g/ufWʦS
-Ȗ$b5F8mR)X^sZoIDw>vihl?͍ P)>J/:dIBA|ClzKhBa=XcĜCW{_eh(jߊ[i
BBH" f/)ǕST9J$@DP%4PP$@{'OGZ[, ?\eL}37 zBݗie:^mC}v
|PFl)}7eXm7(}V=3D
:tι5
\zi+}n.hM3 yï8PV })g K|C[eq9'(c_ҧ'x C aC TDy}`%ƆZoRPfz@j}}ׂm=63uMWzׅRe)TJ&лGy] UmG-=R;4E_Iz4)Áx~#``{%}: P(hK%GC-X $ʀ=X,t<@s(wx#j?Awu&2:[q@c_ P
SK̕f[) 7KjŁ P\*9+ٺBA296o[aex& t"f
{)̏ϔs) v%hЩ sdyQw(+BzQ1~!P%4^U szaNus5*"`[Ym 1@)(B6:i+V(@ Dl=[9oyqT7L"lVD,c4t6(#mbsG`Nyi
6 Ԫ
ۘ($ P(m?x1a
H@mJNJ"0bſCIm]h(\5Ayu5fK3#ы"fvIK `?7 휸 a'W+:{?m!zl@ %
=OB, kA 9$lYOiofmuW^By.
X26ln٘`i9
EZ=S ޛKk
vexM:a͖YkNtA@TQz&K TXIA @7j?WG.^JufZGg8Џ0eg## gx^ұR+ (Akkkt3 6FnF6Zn,} }8! @BA
q(ۛBA~mب^m#'NM{ ~
!lE4 xb & ɋi[A &JZqV f
vssڞNED0Ȁ@TSPll` rS~@
# z 60@g;& W"Z`= Zpa[j7E!R-'IrKA@ *
lȅ[>@
] Q vu8L[o& 3}s/Grݧy}tJkfr[z1I@ DmYzthޒ'_@u#+az&OQ9 A@ CQ~f,C3?"pvICl=<1 A 01YN8 O<+
zXHm R" +
M:cqg"!dEgr]bc#BK}%v//$^J #@ =xJ@҅dNת ۋoaYi]. 1~,[@ B. /LB+xP(WתNk C
r遥Lekbe[
8)[-SHlx oQȅG@riƁzr{<~iƼG(ۗ8ۖSx!@ @.ؖ3=c9msTOܗ[rU_+/Km0
sIm^BK|C߿''?66yqQS fmH
K"СvY7jnc! .@ hJ['<:% aiPG(pt *nOE'uU}EWmcraalB5]kK:vp)\Rlb+kgrO$@y^Lh>tB5!Ndki 7QeI`_9&BJ ˞7<"@ z8NX=܉("I4 G;|#ڰn/ k,{s}An Hzm==@ yV}Wԛ{ PLOrP#7x'0h 5½
˗w/ET] e1䯇 < gBo`s t8Ǒ&~Fx Ehp o ̿1UۖfO'"! Op(v}|ɥrrG?t!A ?FM`Bǥ*˒!- P(H ^Yqb @HlRQVڍ^˲Ŷ7eKuK u K)h@ !j>>Ǡ BA6 E{dÿ%St̖Nr .P\a9cA:A-YMkWS<P\@ 48nv@ [ lx!@ MP($ VF`@eqUK+˒!@fO_{c2$
uKȅL-9tXΐ K?tJmi
fVH֬ uyrJiG@ 9$96RN}%.)9;0Gf\פJQ @#
{3;AM`
jѼB|oBq
]/{1 n<.EL "vuTD`uEW~K7u
v
nYoei > +>Y__[t dݖwVU^?6@zIs[(T F}xbَ2.5+7Ggg1+&9X 01Y$](_ pGGi Y?d]eQm
`"E m6@xzk6]2i7R@RuWYM?:Zurn3_l\^bMaF5"\@ V'2 $$v`weDml"KeJjR氍AB%|a[ uIҏJ/Z" hӃ?( JC-WnJ,E%pBgyPwNqWxy*uYV=g8yA]ڥ⩟2y @ -p{R@KQo}|0uV<+3iyQ$$aʾm!a? Ln'v\PUӥI e]A@
qPl_zhͼ>YEo7I˧נ ުH}z |/
8{?6kBA}\e gW lp@-NE*P H _b[W RDJ'xGi-헌i/>(U4Qr@ BZNkЉdvSKnMf D8web[rɪ{b;SvYݗmun@ Iv& B")͍,(I>rP(H՚e⩿~98-Cb"phS4x%1̲% Ѽ,]_-rF=zg꧆L+7 C g R H Ia-(OyLN߬)Z1'""@
@`ł3JpГ $?[~~Z 8Fy#.)tŕ a.d3wx!9NmU 0#,^ H*aO4j@#-xOBA]xC2^^3N%p.ZEo@kJƚ7zc %DcH H?'dsVo=]^FnЧ.:+Kq lӗBK|qp{N=s[uϠs\iDau^YjX8a%5ss sύ C TSPyzYJm'2^:OsBxrt+deVA
vmp}.3=y>38njзF@q̡U~uW._!Y> "~% LE
37?m&^'\}Nя5{xڝG*
ּ8*Mpy+6̙VN~jӘ=-RC@ T{'|?Ab t
M~KgldfP(hJJ`71[J/,gL`'jkSv۲KLЮ@
NU˜Qxԣ׳/e@ ݣUl|=~T'6#G-iU>l4'#L e{8V͇<ͮ맳sԽp [7] uzm3uDp+0u2[4 䜀sz ?O`B}m)Glv[+va4+gOq_(pok
3]|I pq-J7ڼ%RS?h Sqs\%8-<Å|stɑHG @ ~o?tDH-G>wcBHv ӳs g<$b⦰L̤CBA:[2E'8\)=@R!`+<ܭ;pYn=ݸӊe#[XdxExQ4c`r&1@ [>
s_(Cʺ"=d&ClB ]tk
{LBAUvk
9< Wx)@㞇
s~hƖ3mJ#0Y'2VZrenO! @@l\IjӃ= 0Ma#Ԓ쪖I7mVF[)[$ٖCK0'yʍ3$@ C]qU`EzR|ewnzUѸ{z]#|ID=z?U+e! =Oy0ˎP]۲]ú]$=倉y~ъ _هzV,I=JV ?ד}yr!XvN;vg?@ H۪XNF $[4Ｌʙ\!}oD#0T/L[.SzS1$~;E7Dl(+*"Pr:R(Gx)AB ?cҽ-9ò c߶"r! @56v,yiOHal{[B 0AvR$}pGMGG sƭRƖ6ٟJY6~+<.eVx۬mĉaX ,ds,8"}.z5훢 Wb'nw_b@y6-]\#JRZ[W
̉$ 2o; MMOJ3J:
uU\ϥȌ зfol~N|Lΐ|]S::{cL^d E>*?bʥkjRפ?2 Z#p]k'=9}; i5+S]~M}U^
ҎUYjtbG
!8P$# 0
M/io
5i˶3κԾ,ݱr3]2zLuiJzO>b\WsطSO`>@ xTg6,,B̼W]U
f܇.==/H}Y6ԧBE %Ѹ 2M@(I3>[ޒUc˥}sU֊%?>$ tHfڭf[1(]Yro>6B ҥAT "@TT)JSPy1H$bHHHMߝnݽmf3O ʴ:1gg<0:@ _WpC ŇUF(zrr(=Z՚V ג3>J
rrrmb]\SW jk)t\,̓g 0Qm8S
nLne.G{7Q͎\b2A2]\ v?jpw X{3u?Wz
}]Z_7sMZFނ0zpQaƏ}*5֗$s4@ LfS*_*LBY)NEݢ.ET]/9j8:j:>SӒ'`]o>?V?>x9e(Yy.{#jRCܪi_TS(E X[6䳾9Sl'6~~s.dlsΉt8ي 8ǜ $nOsMlsU@ C$|hvI^c ԛXQxE%[EI-.ºvTv Y;9fTT+I!$-Ih]5=[ i8-DA7(Hven7a ؇M݊{L[!imYծSs~F U'OM%+cӎ,4~[ +f+Uܗi7m]:#gv8#B, K`'CK8ٓ3_E.NX@$3{kP)(W*(mZue&f)o)V:+d 0Q` YuـzcbC1AzO.`,ʋK*%INɳ G+(ZR*uL SQ=L]7Zԭr/Y6]ܓ%Q<}8Î
UU^#gRAUx¼Vصky-B @쬂S= LrwƓ?)_ [nqavi ink𖫔5e2Q2eҸg- $bGsuVE Ywx%!ۗ] uR;$A 现$I
9#VdboS++&l^N]{OboM -mj3uu]sWG5\X]־̢5K/_sAQ-/gfk&SoگX[L97knLz9&ai
)/(v뭍7%GamGz?AGUxר(;Pk\%UD^ ,#M_JgO H \RSsTjoiƢl`bGŊ H)0Ov$L?vDL/& 쨎 W_mYKvYSr0esZ./5YRG}w^32+nO}E-8;{E6/Z7a쵑 Kq۾?s ʐr,qUt5فeҷܐ{*x~&
25˶y8 Imon:{z d}&#pM܆ڲ;v(N lq7L.3{d( "5<{bg^C6<η4nJ쀬˕Z u!PYeXg*ؿ_yNj J%(l$t@zSHk Va,;{QwXoM7j xd$@[ ^١%Xs9IpАC ?,dx@ ZiKO8@>BB%;cg+okES/
L︻>M+캖vv
(posީ^T;]
;;vy
{#/}wއ z*Fѷ}f̾+ ~oo{_}Wͨao6m< # x8v5`?Uv CӲm`i \KZqc Z[ .5}Wk'5we]ʻz qj.;xlx4*;ls>3& Pz=8ԭ2mڮma ]eBqUUt /)"ڬ?ԭG
Y+Q'n|lf mNsr/ @~*.SU ?߰S>SڵV`;fux0#UO)`J8ܗMEKu]-Mͅi )odۇEH@Ւ gL6ׅ1'g?l2M t~灔 ?66_d=-}
r3ڣ @jͶ3f-x\eHRIZ;B=LUJp p,p]rS#~_[rF]އ|6SQʇk\cIz'̞xin}I3{ xfC69d^n^ H&(4rbv/ۑ}۩obg?WI>+48Ca *I}*eB]UnFߚ>7UqW9^?g2 fh @Ee]ςi~VW?C zDv}X%|k'm~yrf.`wuץl_?Lef3~*AC<7?X]SV۰h^ L%^vӀ-5 .:^vLVV*˔UQcZJFYR)ikohlWjS3Z؎u= mW x Tj)wt ⻎NXߏ{L\ rC.%f3*տ3;J]fLmvM>L EkNwWRH#^
u XUZg"PB#ۗ'υ# мĔsmF)p.>XfL]3
0
ͼWw
T(1f6_~ծ01,[ N5.Uװ|ۺ:tB@ L/;\)瑓UΫ"p
}c;+-ikC^Rk YΪ&7N/㔉 &J*vbe ;;GNmM7}VW()6jLfL8Z-v~Iɂ[]'(N zbGG9Q\ryρw0\wߐ{KaQO vʯ))Es =zY;,Ŏ5ZrnSi'r]s| _1c=4ݫj?k=zM4@ or^RR65 42eviX;Su0nJ^ Nm3 2D@Xw: VI̼$U֚jo7ޥ;Vn75ݛx7.?" Q M _U띀]ZDndd KNν(K,H+-|۟AKcvF-L~$sIuyӲo'{h*X9w-lO Ạ~G@
^e a~g?h7 P]JLnznn; A1O 0Qi Ӏ.V
bF酧)y=Qq|T YCc5^Iн Op#
Weu
@8tpO ոntl #-|dA!j-{ ] `׃O~ "3)PGLD뛤ޯQ1g*6OCZxNm(`h-}o57UΝxC.̀Hv~@ 6{+3@z nKdl0e(e3Z
ҵhK5dFP.=
vYL- Ryv$7IvJRuv]tn3E-c6ojc75]ǃ͛>σ^ ,,ZSq& .0_] ,*+zHރx40D/},S.CO6*ձ&Zضgx+&
ڜy
u-22Y(5x;m\+~_/C''BZٰ{祷s-GNmlfeLfC @\{ECu2f>|g+vi]ζh(@#Ns ZX`3$!"2Ĉޡ\ Sv>5v{Hս
lI?N,|o1
@ <r*L bv˳7= _Xò dG\ӢKTV~tƹz^W%Q
pFA ꛉmKK VQ46
$ʫ hz_%#&] _[
@}-k) F Gɂp ]<絾/tٲ%P nI U&ou M(۟(v=LCb^ΓtG/!T} ({^sCc`3Q'
M= 'k]p },m!v^ ;\ӝ9' *#Y Z ~RD! D/`b L~U!!6Ib6ApHPvÕ9 R2;46^ٟxO= 0Q&-z@z]ne;iڑ8IМ ,hn<_f q~Cqv%lDmɆ@ h*ż7"zBv= $G{_WNeF{b~voZlW)hL6JOi{)KS<^{CmGM(#]ZI^L oo~mU\_uv q^&i
|QjY[LvT)ʃ1/- vD
ix2@RCs!Z/Y [I-ybپUm7()mKه)vvܴ
>e㵉!;`~ LRҠvy1o}АCԱwXkɎl! /`;P.Us ރ?p9
kiQ%egDMܠp iרλ 5eިIS.ok$xpA&yЅbU] EA^ |^ '!;®$`Rl~Gy(u#Om2Iӛڏ6H\7p[>4j_!GXlgJG͌?TlUm]?=0rEoo<+ g-<t fLrTtͿ9xA&m+ư.V֎ph|[zޫ il5{ -)4wl'`w]o [quhal< l1A7Uv*h><r Ӿゐnv\ 75o7Fn3B;@ B;w|b;hn,V_U.VֺQUvv,yv`mh7(V9Oq}gI[Ivjg+EzC-3PyeǴ OU}\(`x1
|Wˀ憀h25(v<a[ e y.^xvEv-'g! @2}ݝʫ(*ZxN{!,S */PTT^P8Z$ժ(vɲ EJԭ]+WMDHWfkrq0Igh 0Qƍphvo_*.μԴ)m(ڿ4}v~"pyS rԪoBԈ @+v ,)
RC6Y q6ʓJŵTX9KJ;],5f{BD͊Mj6Ar)Gs;zW<خVvVWh,kQͺίWtxˤsZI|?d,n;z)vv> dJez]fXؤwAd%߶B ~C5 w[v9&
RC -ŮyseB+1{Yq
3[uqյ<ս[qܩ/onքZ_g d;vgG H Ů B+Z7/,k+Õ]rv{];+#sm+*Y_Њ yȑU *!9;scg (f"N:c] .P<@Av㵊v5XL@i ؛GQ#?kTGZ}"ze[&]:XXv&\7y !FS ۵y.b
^_{*ҭkW k; L}|̴F+Io6Nog`k#VyFbmRnbilJ/
xEh(5ڬ] S*G(3/ב$^NBfaE|9=麯 ny䴬}IL3)ƑB[ uTD ? :YbgtQ Tև==: `g[-֬qRi ܤr ՟M El"?:DKe.AX6QpՑNVMѮ,c^، !A O2rRI:cl7ok&͙d 4U% G
{J
{;r PHusr$h Φp >G4] droin2)aMtruR< joYmx&\; (V<镴^˾ةIƙ +ϛÂ_ fMM
:<ƅ E[Q3i APeo&@Coh`vf >Vh
/TlwvK5 )
E*`; UNQz(Iѭ2Zvy! 1f3KRLuTV$9-zlfwK ~
/87@ oFk$(*WluۙfgIg4/u'Q(hj-J_Ŏ
xw+fe{:cKА|ۥ6WhLl"ŎXY tj?n Z@eL]
7 ӯ0j[˙ bu׳3mZ&cST Utpʡ!Hr57"-ak>IuQ|nuδ{J^
F[Xոᥭ{ؾɣe
o̚tq q挾\):@ @{-aqهT.φ)'7&]{w%v@ >Z2w69¨ &zG(*Cz:f-픏 V@sL4cI覂UlM lԦj0692T_ Z{ȋwx#[,/ayfe݀C uF]9i@ ?vְQVW\=RX7]Jއێ$v@'u6bSEwkKI $٤{
|(Ge&`g āMNӶTDUd;Q폖lD-m۴tLhy+r]&~ZN[LdlЮӚLDjeVM9>ӄUI9 1F{}rYT4zG}KgS4(PGZ_sl iVl;~w[NQ)c
`H8^H̉MXL e; oivͻQ
_ )4@ @ \LT(vM W{]ϙ kɊ4N$(!@ts>g #@NwomueJWb7r@v
Ů\Y,hw.oeh @9<CU-MXVwf폖}cGlXm~X$boB}o6Ჯ[ @콴4E{mMbg.JKvR}of;/Sh gc]+ڃz팴z@ @ @ @ "`PR-bG p隒ΠR( @Q n rMK@ $D
Q P% Dl@ @ @ @ J3k`rc\ "@$Q +" 8I`f$I@ 0Q -:t~;l;1q!7 #@LoJ ]V *剂= Nm.E @ @ @yT|vG%e# @ (@ @ @ @@=PN@ @ @ @`ù #!\v174:@ L$~Q N
LrO} >6 8+O }T] އ| 苴 oUCT@ @ @ @ @>T|(qpVA&S
@ @ @ @ @ &' &
l ,]V\ߞg'@ @ @ @ @ |8}qI)1V6ZVcxY@ @ @ @ @ $Ϩ Ww*7WOUH6.us'~Щ@ @ @ @ A A,Pca0<~0nE @ @ @ @ I @KuMһ9Rp_ێc! ,pwW ӘΌ1 5]FM>7n@և @}Y4q6YOV*oX4@ @ @ @ @ 2 NݸַwjljNmħtYP @isӱ|?G"쩪 WjL )NQ @^x]Z5 ۮv_Jks x+MyZ[lAuqJ! $@\ :1uVNT*Jr8\^褠S ';}}rb;n6IzŮ_8\z'
@ OCAC @ @ @ U%mnJ AqʶJZؤ
@ &
@b@ @ @ MlW)Ǒ
"Ď]K2M +ZFilNWesb(}J%
/i _?.2rn_?Xs]FI#|.4.s~=GXi?šύۅO
wL3KoMcjH?͓eTUUou _ϓrd?C?=2롾 }*oOwDۛ_0BdYnan8c9^-y:e 74N537j1;,tnΟн
|aah7bA&h]+X4w p*+G-t⍅\ m])ޅ
J|{o,2BTIM*lO˝%\J^F5\KUlVZm6^zwG#8QG}1'7\y\qWYuX VZlq
N{y!N>N?Kt-v wX^څZ^VJol?V} 8)Z3V,7 fidEhqvЊXnv?W/r[^9oaն|roTH?p}s KyAF==6يqۺJ=uX|G3wO)73]Ks"pZx ,M _ tB 6lVf}@& \KỄKg.xVd̑m17Fֹ~g""jԘZm̬>N*k]H~3C)=9Mc <И.Wb ;iݷH5ZiP"O,J @/Eai1ޕ1.;v e5]9zϴڈv2=,
0aXV8c|+c̄Ll^խpH,m'{ u(df9۹2JfYew.k߱aoŜwݣH[Z9V:I3o pq gΡ
D̅<-54كk9nd]K%G. 7RUS]L@.21 zܱ/L!|M2BX9c2B#oN:1XRN/P;
gfl m#u(S=IQviA*d##&4Dڭ/mH &UBER7/j#bxSFVKf[XU;?W:!F3YB&TE = B"lR F"kMeHJ֪UȪ 0ק@0 8Hֈڃ-h2Y|$t.| $[ DDa>gv>0
DG ILR!c6 #tЩd۴. )ȫ\RBca#$F0 MLj kȌ9q~t̀zċ^Bn
ޒ.؈\3XT)9@}ZC絉j Oav ;ZW5N@E@K,Ma@ U k.s3 z ,nVVd\TPV $`>qUd#s]z1v@+ ϕAtfzr&DB^
&&B [ 0HJSl="< rdpYu5ς,ÜtvYIKM7ۄu#*E=ۡ
ҔVJ((fpAJlһ JMb"yҜ`9?f]@ *8~*1b)ޛibVh]p kR$}h4NPfF%YC80F~\
L=/踵0 $`dhѳĈDrՆf6`W%N)Х疼R" cWXG`;(P YpxTpӘ *Ã* 7r?+C@4y4bKJlu<Z! 5FL @G4 ij7# "%^EV j8A`on<|VР+`D{. TP-O/r
r0Ree$NB6l 8 Z%n i2HI0R@̹aC͞LCa;
7:dʖ8(83Qy qJ'1!xlҞ yd
:bO%`Α>\ncTkGݖ8,uSRtQ9Ѩ(&אew< ֯RntÏJRa{ ˙е"Sx0$+2MT Q 4
O\`IxhҧpD@5\MQ- ى<}P4 S>ez pEXgEAF8E Gn9H5v`HHb` uG
FQvca* `H@u ?G@&m1ފ'E1⎎Z[E
)/A# |@gk '@'VxW*eU Lq |:*3@շ k12q R ]8H `lr#O47W*ג9L4KjtjL9dPUwJDA`
kd֑87bUUu.lC!P%YEB4c $[d9r nU)8E{D3Qƺ ) Hz#tQ&9>=0$1Jѭ
& ҉p < ]&w F RA@Odp:S
L qm $Hߤп`4(49
{wUu ma|A ؉5Zj v2k5;U8ɏ [U9 ãnp 9dMyUM Q`;-UiL)H8W}gZ_D *kA@tC
2g#^Q ڒjHĚaW1Fu~rCy fF;Ί!8-AY0uD p`vrZAdHkr\2[Ar]A]"#UCr?N7#x5:}Oƍ7ˏJ˹cʈ2CCn zY '+ΉYNm>4ni%Ph ~ D$?w?l%ytQ8 8;ȥ!a2gW x&CM!h`3) \T
A㣘Si8;"RhӸ xnypD A
MT|]b@2]\Pr]ȋ`: |%Ĝ ,"ݮ@4+"ڪ2aX$Mnm^ U]= |*q)`6֤+piz UįeD⏴g}jك3!@ OݪC@JjKɢ18dW>wA+,|c>Ch<jA#?H-5dК$ Bˁlרc/\3DXdhgi% >Ļ
$;A =O kj7@FaVznWI\%= F4|L&̣400~U~DQtsFz[5 M硶hl৪ v
]Ƞ9U^
b s@%J*r & <] K( *B}3_dĻ0 2|c\v1`i eg8ojU{BgՋ4|os 訿YmeV3@x|P2V X*
dA $RB3 >AhSa>
Alh'jn
bh+^ ˼.Y6 ?&S!wUTSaccxZɣwk #iCkd/rFe{c5ly;|߸
*N qȄxґ( N#C!]2s_.' x";=Un
U LMF8cU䭚0V
/"{`az8 H8
uh(M
8Qf&*Xkfo =n=2 NU@~';!"7P:rv# I 9vܣ:1 d> U
GF9k=&|*h$"w](! Q=jsrLr XfH&'
|5fQ/|) n|uDE`R>`v$DX(w*𧶒6Q T7`#bR js79:`S&RHZS4 "pBE@qxYUPF HB-ìIV0 my5AU nԙl" o)ݬ=R8C8icKj{5J};bVwrW%f&GR@QaDTm֫Suinaf8c/&ϠP2:WXhUnϏ v(Ĩ`:bED<3 3I pT@YFvU_c(PL ?%& PU-+;7obeqG @@#)ڰ@.;u!J-~(`uN \nIbxe:5]` }\]?CRAI'd{`Ty
L FԬ2ogbĢkǔlFZpXnRe
Jltt=FB_q9$ÿSˑÙPd9
MTuƕa ^}~^˛[
A Bk ex=B``U X%[^ ȴCz2
*c^elo+ :"SWSP70 =hI5C
y68XN6I^|Q,eA E[gSg E$Lz)M[s(D6_w
]܊edA̩~B"[ ܭIEu_v52:TkUӁTI:UڬY} 5щ('r=$FB&\OJE4,U!u ҹ\\ 5]5+| |qBsԿ-ZU45Ϛ)s 0Dp @,3jNmE~ m&U " ZubZ g;qUpw];OEE ]M;v9etɊiS͕.g0d|ǴHurوhԵ(ܻ I,*"<`K:8ӦKz
Y&u $B?U}Բj2 ՌLs5҈:
rb"9S&e* ?0v ڶtƏ[ vBD"[}H>A :a8贐BjSsj D!
lxs!vxTQ""M*V]7C-Ԁ7M>}נ ,mMKB'^煘xdn'nV!
xT q1e3UW/^WpytOTb8 }7IG !zzCQwC>;^,Df硂Tex1j@LS] fDK i.!AZ m\dkUm(J /jԞZH?}=*W-BgP/T]SY<$M~tV`B?Q{eDEFk)'-ic/pW:s<@!ui,h|Zu ˪VgJh .'$GhigRNzM\sy3kIym")Gs|SF,O8kK2
V|0@&B
,4;*: @X{ ep T m,gZ8:W[G=NtC V-M6LfeV-~:hYDU(@
0JjЇ@65< [v: tudqܔ/Bn>꣔J_U$wZUZfV7 KQmOyQ-kl`'ZAFVj]#e8өcsg}DIgU6+Uki ) *
@xRQ;ԃ糚OcQQ
W+N6KM,S53Q@&Y5tkÒ ":yZVLjj(2CZ[Tt }
'oQ ^$T4M>teΫu\e :{ԩ_կg16op98dIaŮ %A4U *q@p&b(yzV$
zU;"\,L5 "U
8)S
Ё WעOLtåKG k.YZTEmQ`A yl'Ya#kղ*$"bd4 & .d j6ouN8tqDOC06lN=$u:KJ.
6D(nL)-vq0:^ -@Q#,rc[Q@<6.5UCR0V ?Ud w2# 0E5
d JFൽV!3SΓWQ%!|6/5i~e0$%
~m~/A/:.{wE/(:PY.+PiY_QRE QG
pK
,ȫx:;gmZe 2HSQ2[ja[âM_uW~
W L(X 2];)5:Ǩ=L9f~7; ad$G ] *{ۋ48H|U{ 3N?A![:s~␌[8؈o#ܩn0W
ECG*;dpUUDT=1QryŴ#F> E?3TcǧX3g鸀_|gL{Fp!oEϯ)4nl҅~On^ Vᘟz_ `DЉ[u,:B{ PYÿ #a|u߄~pP,uU(|TX&:/4~Uep'Vqhm÷^-K
u귴@S_v RR a$0@E k= H WutI)zw
ȟV3:A xx&) ;UMVmnD
4 ^цU@R*:B89"{SAD'.]D!gc,+:i):>'HSVkO8.Ь
C&W#@
Яm"_QTF2bu(0a*5S;y"ʋ~vjh1-b& @y>iw vjUX D sbTS"4;u\T_QcψAMfuUtOQ&Û~ôixՎb wh iCCPICC profile x}=HPOӊEZ ꐡ:Yq*Bi+`?hҐ8
.κ:
x_Rh8{BT30eq1_{_a #(1SOf{ꥺ,?+LD9̦s'tAG.q.9,̈MGR]ʆJ
ź bKGD pHYs .# .#x?v tIME
0 IDATxw|U眻Gn! CEmk+mZj-ֺE-n'v ޛ&{{s8?R_nn9|} WOhd xH҂#}g>1Q#zoc ۀ&](]-7fitr7})ym7H]A 8 IZĉ[L<)ChЛJ D=TQ\-7XY14X̀맑4p ,z1{cN=Y\^*bK:{P t9r z LUA>ǩv:Gz)es{?HjMPabѤ MxR2jUr)aGKɿ\Wc
cp bz81o?B1 )_aGK: <
f\UH@_O4cDkŔÅ!|~!!Ey\. زC|n B 뻼
OԨZ?A$uGdkؽsʏ .k.MBmc @uQ!<0G0!)GDKue K$%%a0())SҪ@] *w/+eՂ4~$JM KL?HVFQc StQ* 6 `L1 я>(g&::QxF 6+MUf ԑÜܵ"
EPbn"/XT: a#0s/-㴶% M,}EkG $6C\/vmm\ jc-Z̙3ȹ\`ڱ;}, -- i :!CApp0z Ah_\{Xt 99d) qfR^/9ȟk1iE_ @R /2rK8N8ߏ#2~amjb Kq/ɸq << Nt q$ظy3_n֯`#O2xꍜV"Qi$> l] 3>k/0~ ~_ NH@@ ^7ODD``Xؿ]^^w jY"2Z` 6 t:E&B"<)vfwϟzQ ( #ǧM_Jhhh ^uPY65ί9f9/"ӧOoKmQ `ADFsb
g
U_^s9OK)'G }#F\ T*N<ɱ% >87pߞPd -2>뀟NcǎѫW/] G@uQ! \Q@* Wyh<&M"33 {*jjr N'oi担/hXYI= :DQ<? /=~ 6 |;X!CMW.prv"Ù1cnDo: k\v9&6`knb/~<*Ӛntﭙ(.o)Iwy'| =z*222 dddPT\:Su+5TT/DEuF ǔ[n3x >Sh= vs3* TZ ^yjUG H yljaX./ P`4q9 Ⱦ+wVzR}-]w x(((ȑ#466x։o#sҵX*)8"Sz J:
LHIhiijhS>Sx6mс%ēW^a$ (
93t[ wy]vvʱcǎ n֦&wșXXzu;glfdeehH[ssm
A0њ=!+k5gѠAg ,HBW1eۍZo >|>zQFΝ;Oetjsi(е F=Q Rl`3c 4577}vzCH\SBhx<]s{Ϗ{Ϻ]hhh *:dښ]_c0:!qHB'o6C ,عs'V"uH:DR*Йihh_@MM
\.رc444`4n]: 0 (lOII7rH9!!Lb^z%ҮBꈑ%nks.{r4]4Nt@yy9f㡮fϟOBB}y;m˲aQ`
^ xqqqtYA~G?ݯsd~YN6{$ ++0ou OTjO:b*)%$rQWW (Y֬YsPJs@@tB: oT խ/ZhIjjo'44Sb'O3g}nsMQ!˟}6S55:cAANbvE\\C:#K 7|3&-[`"$6cαRIxR!*#ܑh
^nݺeeejVKTTTu555{d2hsoٸZSM$ DPtǝ<>|xCI`ժU= 0ot7බKҀA ]
QYz=ﰅ(vc|I&MҥKٶ 7>cb;ckRSjNEü}ХK =zTƍYn +Wd|g;K/quuʗr\TUUЀd2KAA> KʘҫgEz;orዬ/q h-R1`oEXb$]4Ѭ,'_䍻etxA )"[dbw0jU
Je<:ֿK&&PVp}c1c ;tJ"66r^u6 _ 2%(PZu%Phի BCJ
b`> h A*DĈ@R #OQfdx~?u8V. rNSdJOn~1'\]w),,5N;'O Sg&hF 8@Tih>akj¤נUuiS)$2&`%۷1~f@xR g"77 |I籱͛7oaf=4#nݾy<4i@4@sw Ye#jHRBS9n`/,ewv L/~IXB"[~;v,'Nd -4|>aŊ,Z+H Zy ɟ6Tw7 2n?`Ŭ8QdَcJ7K'90:k#Z~N&WoN;SO/3{llnp8سw/CD$SN9PM
!@^wR (sw̏\\ԋ1h7Nyc2JQB:amN7rs~~9fgEHl 1 n
?k$ш ύ}#LIA%яpuUSC!@-f/8%8:5/>WW2g#b @T `j0 -Gȸү-˿(31h1z_\SRAc0 z t&+ Nd^ @Ivӑddc`n* y+v_7&&.@Z',1$~(R ^`{o:{gy닒a48G g_Q_Wb?flF Nh| KCO:͏1+Uȩ:p[OOfW9{9y7裏dggSSSDLGIEkFw{|j9[Jq!2ODwDT0tL
z{Ag $+
(`nfZWzMzt짣ڂ3^s]-ueQuwGB?q)"HU+ccYogx<6+KZHqkBB ӝ<_{=Fe2;h~MACӇxz Qhe2 !&=}Ȉ'=.?r1O:2zjihж), x
o[gΜ9 >J
4
JTB?,7^OLt3۷ϣ ˉ`l9(REuQC{`;\U+I!:؏u_}j z]o˲Œi֎-$
xvر>,CLj#0>V}KKcz5%E\E:=Ơ 1h镎nA-z< V+
χ(k] $V |Tń9#_L!$E 3}4˞^˷wJNe
f ޏJA ! Fmf];XxMvsi_MEqٳȠo߾1 ֮]{F7H>}/ )鄫 IDATT*BCC(2 Ӊz)++#;;
JKK$͈JZT"HJ%ZKKC=nkK}"Ci#OQig%ep/ CaA| qZ[UĉdNbӦM,] zElllĻ]^n|] Avc6Q(B ֟Kbaƍ gCv|L4y p 'Ng Gљ:vgM5G&""H֭[ɓϊ9 :Ě[UˋƻB 2X
M]^ rkEɶXvK
\ҵ8y$;v`߾}cta3nbsp]zw 6bKss3n]dj4 @ee%_ZM|*.P=߉#ӓ
Zb,ve䍇 7;ٳg >?G Xn dffO Z)ꫫ_hi`wW###ѣk֬qƵRէů*
s&
: l w:nwMFɶrqGW'OLrrr%f{nVXZfڴiddd78 HLZ/h**8kdRn*ﾛ7vUTT+p=0d y233 ^>=I9N-~D說P(0a&M"66kxW-.PAE{>!LY#c=F~~U F^^ =۶m{o߾bƍ$;
:gI믿o= {SSn WTl:\@
HP~{` vɆ
J.q8 ,]1c{b
2227o yyyYYY KL">}v\v xVtɋ)Ӏl /m1iZ| r˰:\
ȩ
FeHRf6l!!!dddp]wa)..>X̗_M1z9i=wq 8N~ml I 0u||>_k={ذa@ pQYhu6l82}'U}"$4FP*lV6X&骬PTo>z 8p q>#ǎgyAn}ǷlBW[վB`ҤI̟?r 9Byy9Ǐg8 jjjؽ{w;]N{Ꞷ`f`jy翶 j
C@SȆ`ӰaîJKK3k, z!,Yf˖-̙3Iߟ&?}/+a;xG0deeqqGyy9?8= cƌARȲe;v,7| ٍYy 9lI͖ƀچzޤx"Q 5:::j[nÇe֭[GMM
RIBBOl߳9wމBEgﾛC|r۷/,\S2ydALHHwΝSN
x< > 0n$z rh[lfbh4ddE?ç x5 ~rP__trl̝;rM;w.!!!x^N'Ϳ۶m__l@Fe-s/Zrxޙ n%Jvt~@Sp]hPD >0NVe???Y+&v;EEElڴ}ؾu#"Ʉd"((+ʕ+Q|<#s=mEQDT8q\"""Zlڴ *WZѶItHٞKF%I환qXP}}y1ciyyy[e˖Cĉo~äI.kO3^{I&1w\233/vO?ҥKcރи'cŇ)@UGZbFQgc__ON~ܤpBU9q `֭غ 5C xq˷[׳`.m}qi&/^믿_OLLE
1%K+<2UZ٪ 7@RLkAǔY*?I8vA,
A%'REGFG8̙so':::JVGQQ|
ׯg\I߄lDЪj^ 'Jkyl>QG }ԩS/K||>[^/&Lh@KK dʕ,YD6iBSz*w n%oXt inPjh 'ʽFETjk|2zՆqI$IPfzA9!\.ׯ Ì 1! U`Ш[50!&=_>Jg`ܸq $&&|,LGcc#[la/䂜RKrLz~zJ,zA 9- Y.Y ]}D$VW/(] EI=:t(iiiFd
MJJڵ}7-s)3R 5_"L-:\ /k3Řvکڶm} mNO \PUl'%\ 5˺]M
ݡ .66lm27YM*)|^2xlOOL\ /uf+{NW{HF,Y1c.[x< rVU,))!//l},U7"Cc#OGUL`#YWwSg-3_:2N}]_*#24Tdh)+9e:Na7[FKz\CJkbO @q-=SoBgdYj܌j<}%NQQY{8dAor5f o h$Ew-J % 4g)g!:O)V8n Ri-:^"H AO5u{ -⍯텴؈ eMu-e"&6Jg2$IzVSTjUfNt ;vEuu5UUղRxzS; z?cjLZkW*nQ uv
o>U RbNPΣ@eBV4NK~ M-|s$}{:ճb5k[lfՎ][,(JO 2>12:\3yihPhi|> ڐnM di
-֦nQ}SНj 0Z U;}ۋrt%!.F!aU1u}V*A<^\p .V:`!rc"
nv>y%pjAD'˲`kK,d3,,˲ W5X:CBR$ȈrDֿAmY>OhCuRSS|Tw hj Qlg{N@aRh|C*zħ
*ک* ?ӻRKcgP?KyE
INK{d
$Y &cw؈␠
E'rDe K5Cd5ME\+q [isX
.S$QZEDQquR;+Ymf-Wʧz먼Ot}oł#H;zwgB`MҪKkWg _.A
/RΓJ_:Ӳ"Of(( x EzE6cAF']q@ /VH}N 2Wҽrˤj*̣DB
Z#ysWvtˮ: ?yR
D䒑B@a`Ξ C[f~!FFģQʶ4I|?Q`XCEF\g] q \?De3F93x)#zwdɈvEeEUYrlySg~/I2YFQC
Wa-∾
8ʋ]+aMB}
sy>@-GH8<@Ψ=.S
>$
=Eܡ^5iׇdA.>E]ܺG1ɇT$# r%˖Aș '4$"HwOsz ezȍ؋JĖ:LY 5d(dFfmW ;⚛ֈ*.N[is g-4c%:&lSpO&
(>B+w]Hx^]riܬUR *ْ"HqG m !OFXW'2 IENDB` golang-gomega-1.27.10/docs/images/sponsor.png 0000664 0000000 0000000 00000005255 14462163431 0021007 0 ustar 00root root 0000000 0000000 PNG
IHDR @ @ iq sRGB eXIfMM * V ^( 1 fi | H H Pixelmator Pro 2.1.5 @ @ 2021:10:14 11:22:28 W pHYs iTXtXML:com.adobe.xmp
2
720000/10000
1
720000/10000
64
64
Pixelmator Pro 2.1.5
2021-10-14T11:22:28-06:00
2021-10-14T11:31:52-06:00
s{ IDATx[UycEeie&qLd'JQPD A*0 ,"aZD
3B-et~Q/v=kͷOf|.gk3dHG: tӁqjyk.=@A} q ցZ[fW`2Fa`
Z* _gэK Da 讬/ [AQxRBA ! @Y"fTx)[ Rs:Q V:@ކtpn{{[>ng(~(*^7v$G^wpKeWiǂU1I `&͡Mm!̄}f_h)pZAM3܈46vZ@5i
bv Z E i@#E`M*ZA*O?
,"A,"}ʉiCv1.J;
>oxdb2&5fs4,:
`GomegaFailHandler` is defined in the `types` subpackage.
## Using Gomega with Golang's XUnit-style Tests
Though Gomega is tailored to work best with Ginkgo it is easy to use Gomega with Golang's XUnit style tests. Here's how:
To use Gomega with Golang's XUnit style tests:
```go
func TestFarmHasCow(t *testing.T) {
g := NewWithT(t)
f := farm.New([]string{"Cow", "Horse"})
g.Expect(f.HasCow()).To(BeTrue(), "Farm should have cow")
}
```
`NewWithT(t)` wraps a `*testing.T` and returns a struct that supports `Expect`, `Eventually`, and `Consistently`.
## Making Assertions
Gomega provides two notations for making assertions. These notations are functionally equivalent and their differences are purely aesthetic.
- When you use the `Ω` notation, your assertions look like this:
```go
Ω(ACTUAL).Should(Equal(EXPECTED))
Ω(ACTUAL).ShouldNot(Equal(EXPECTED))
```
- When you use the `Expect` notation, your assertions look like this:
```go
Expect(ACTUAL).To(Equal(EXPECTED))
Expect(ACTUAL).NotTo(Equal(EXPECTED))
Expect(ACTUAL).ToNot(Equal(EXPECTED))
```
On OS X the `Ω` character should be easy to type, it is usually just option-z: `⌥z`.
On the left hand side, you can pass anything you want in to `Ω` and `Expect` for `ACTUAL`. On the right hand side you must pass an object that satisfies the `GomegaMatcher` interface. Gomega's matchers (e.g. `Equal(EXPECTED)`) are simply functions that create and initialize an appropriate `GomegaMatcher` object.
> Note that `Should` and `To` are just syntactic sugar and are functionally identical. Same is the case for `ToNot` and `NotTo`.
> The `GomegaMatcher` interface is pretty simple and is discussed in the [custom matchers](#adding-your-own-matchers) section. It is defined in the `types` subpackage.
### Handling Errors
It is a common pattern, in Golang, for functions and methods to return two things - a value and an error. For example:
```go
func DoSomethingHard() (string, error) {
...
}
```
To assert on the return value of such a method you might write a test that looks like this:
```go
result, err := DoSomethingHard()
Ω(err).ShouldNot(HaveOccurred())
Ω(result).Should(Equal("foo"))
```
Gomega streamlines this very common use case. Both `Ω` and `Expect` accept *multiple* arguments. The first argument is passed to the matcher, and the match only succeeds if *all* subsequent arguments are `nil` or zero-valued. With this, we can rewrite the above example as:
```go
Ω(DoSomethingHard()).Should(Equal("foo"))
```
This will only pass if the return value of `DoSomethingHard()` is `("foo", nil)`.
Additionally, if you call a function with a single `error` return value you can use the `Succeed` matcher to assert the function has returned without error. So for a function of the form:
```go
func DoSomethingSimple() error {
...
}
```
You can either write:
```go
err := DoSomethingSimple()
Ω(err).ShouldNot(HaveOccurred())
```
Or you can write:
```go
Ω(DoSomethingSimple()).Should(Succeed())
```
> You should not use a function with multiple return values (like `DoSomethingHard`) with `Succeed`. Matchers are only passed the *first* value provided to `Ω`/`Expect`, the subsequent arguments are handled by `Ω` and `Expect` as outlined above. As a result of this behavior `Ω(DoSomethingHard()).ShouldNot(Succeed())` would never pass.
Assertions about errors on functions with multiple return values can be made as follows (and in a lazy way when not asserting that all other return values are zero values):
```go
_, _, _, err := MultipleReturnValuesFunc()
Ω(err).Should(HaveOccurred())
```
Alternatively, such error assertions on multi return value functions can be simplified by chaining `Error` to `Ω` and `Expect`. Doing so will additionally automatically assert that all return values, except for the trailing error return value, are in fact zero values:
```go
Ω(MultipleReturnValuesFunc()).Error().Should(HaveOccurred())
```
Similar, asserting that no error occurred is supported, too (where the other return values are allowed to take on any value):
```go
Ω(MultipleReturnValuesFunc()).Error().ShouldNot(HaveOccured())
```
### Annotating Assertions
You can annotate any assertion by passing either a format string (and optional inputs to format) or a function of type `func() string` after the `GomegaMatcher`:
```go
Ω(ACTUAL).Should(Equal(EXPECTED), "My annotation %d", foo)
Ω(ACTUAL).ShouldNot(Equal(EXPECTED), "My annotation %d", foo)
Expect(ACTUAL).To(Equal(EXPECTED), "My annotation %d", foo)
Expect(ACTUAL).NotTo(Equal(EXPECTED), "My annotation %d", foo)
Expect(ACTUAL).ToNot(Equal(EXPECTED), "My annotation %d", foo)
Expect(ACTUAL).To(Equal(EXPECTED), func() string { return "My annotation" })
```
If you pass a format string, the format string and inputs will be passed to `fmt.Sprintf(...)`.
If you instead pass a function, the function will be lazily evaluated if the assertion fails.
In both cases, if the assertion fails, Gomega will print your annotation alongside its standard failure message.
This is useful in cases where the standard failure message lacks context. For example, if the following assertion fails:
```go
Ω(SprocketsAreLeaky()).Should(BeFalse())
```
Gomega will output:
```
Expected
: true
to be false
```
But this assertion:
```go
Ω(SprocketsAreLeaky()).Should(BeFalse(), "Sprockets shouldn't leak")
```
Will offer the more helpful output:
```
Sprockets shouldn't leak
Expected
: true
to be false
```
### Adjusting Output
When a failure occurs, Gomega prints out a recursive description of the objects involved in the failed assertion. This output can be very verbose, but Gomega's philosophy is to give as much output as possible to aid in identifying the root cause of a test failure.
These recursive object renditions are performed by the `format` subpackage. `format` provides some globally adjustable settings to tune Gomega's output:
- `format.MaxLength = 4000`: Gomega will recursively traverse nested data structures as it produces output. If the length of this string representation is more than MaxLength, it will be truncated to MaxLength. To disable this behavior, set the MaxLength to `0`.
- `format.MaxDepth = 10`: Gomega will recursively traverse nested data structures as it produces output. By default the maximum depth of this recursion is set to `10` you can adjust this to see deeper or shallower representations of objects.
- Implementing `format.GomegaStringer`: If `GomegaStringer` interface is implemented on an object, Gomega will call `GomegaString` for an object's string representation. This is regardless of the `format.UseStringerRepresentation` value. Best practice to implement this interface is to implement it in a helper test file (e.g. `helper_test.go`) to avoid leaking it to your package's exported API.
- `format.UseStringerRepresentation = false`: Gomega does *not* call `String` or `GoString` on objects that satisfy the `Stringer` and `GoStringer` interfaces. Oftentimes such representations, while more human readable, do not contain all the relevant information associated with an object thereby making it harder to understand why a test might be failing. If you'd rather see the output of `String` or `GoString` set this property to `true`.
> For a tricky example of why `format.UseStringerRepresentation = false` is your friend, check out issue [#37](https://github.com/onsi/gomega/issues/37).
- `format.PrintContextObjects = false`: Gomega by default will not print the content of objects satisfying the context.Context interface, due to too much output. If you want to enable displaying that content, set this property to `true`.
If you want to use Gomega's recursive object description in your own code you can call into the `format` package directly:
```go
fmt.Println(format.Object(theThingYouWantToPrint, 1))
```
- `format.TruncatedDiff = true`: Gomega will truncate long strings and only show where they differ. You can set this to `false` if
you want to see the full strings.
You can also register your own custom formatter using `format.RegisterCustomFormatter(f)`. Custom formatters must be of type `type CustomFormatter func(value interface{}) (string, bool)`. Gomega will pass in any objects to be formatted to each registered custom formatter. A custom formatter signals that it will handle the passed-in object by returning a formatted string and `true`. If it does not handle the object it should return `"", false`. Strings returned by custom formatters will _not_ be truncated (though they may be truncated if the object being formatted is within another struct). Custom formatters take precedence of `GomegaStringer` and `format.UseStringerRepresentation`.
`format.RegisterCustomFormatter` returns a key that can be used to unregister the custom formatter:
```go
key := format.RegisterCustomFormatter(myFormatter)
...
format.UnregisterCustomFormatter(key)
```
## Making Asynchronous Assertions
Gomega has support for making *asynchronous* assertions. There are two functions that provide this support: `Eventually` and `Consistently`.
### Eventually
`Eventually` checks that an assertion *eventually* passes. `Eventually` blocks when called and attempts an assertion periodically until it passes or a timeout occurs. Both the timeout and polling interval are configurable as optional arguments:
```go
Eventually(ACTUAL, (TIMEOUT), (POLLING_INTERVAL), (context.Context)).Should(MATCHER)
```
The first optional argument is the timeout (which defaults to 1s), the second is the polling interval (which defaults to 10ms). Both intervals can be specified as time.Duration, parsable duration strings (e.g. "100ms") or `float64` (in which case they are interpreted as seconds). You can also provide a `context.Context` which - when cancelled - will instruct `Eventually` to stop and exit with a failure message. You are also allowed to pass in the `context.Context` _first_ as `Eventually(ctx, ACTUAL)`.
> As with synchronous assertions, you can annotate asynchronous assertions by passing either a format string and optional inputs or a function of type `func() string` after the `GomegaMatcher`.
Alternatively, the timeout and polling interval can also be specified by chaining `Within` and `ProbeEvery` or `WithTimeout` and `WithPolling` to `Eventually`:
```go
Eventually(ACTUAL).WithTimeout(TIMEOUT).WithPolling(POLLING_INTERVAL).Should(MATCHER)
Eventually(ACTUAL).Within(TIMEOUT).ProbeEvery(POLLING_INTERVAL).Should(MATCHER)
```
You can also configure the context in this way:
```go
Eventually(ACTUAL).WithTimeout(TIMEOUT).WithPolling(POLLING_INTERVAL).WithContext(ctx).Should(MATCHER)
```
When no explicit timeout is provided, `Eventually` will use the default timeout. However if no explicit timeout is provided _and_ a context is provided, `Eventually` will not apply a timeout but will instead keep trying until the context is cancelled. If both a context and a timeout are provided, `Eventually` will keep trying until either the context is cancelled or time runs out, whichever comes first.
You can also ensure a number of consecutive pass before continuing with `MustPassRepeatedly`:
```go
Eventually(ACTUAL).MustPassRepeatedly(NUMBER).Should(MATCHER)
```
Eventually works with any Gomega compatible matcher and supports making assertions against three categories of `ACTUAL` value:
#### Category 1: Making `Eventually` assertions on values
There are several examples of values that can change over time. These can be passed in to `Eventually` and will be passed to the matcher repeatedly until a match occurs. For example:
```go
c := make(chan bool)
go DoStuff(c)
Eventually(c, "50ms").Should(BeClosed())
```
will poll the channel repeatedly until it is closed. In this example `Eventually` will block until either the specified timeout of 50ms has elapsed or the channel is closed, whichever comes first.
Several Gomega libraries allow you to use Eventually in this way. For example, the `gomega/gexec` package allows you to block until a `*gexec.Session` exits successfully via:
```go
Eventually(session).Should(gexec.Exit(0))
```
And the `gomega/gbytes` package allows you to monitor a streaming `*gbytes.Buffer` until a given string is seen:
```go
Eventually(buffer).Should(gbytes.Say("hello there"))
```
In these examples, both `session` and `buffer` are designed to be thread-safe when polled by the `Exit` and `Say` matchers. This is not true in general of most raw values, so while it is tempting to do something like:
```go
/* === INVALID === */
var s *string
go mutateStringEventually(s)
Eventually(s).Should(Equal("I've changed"))
```
this will trigger Go's race detector as the goroutine polling via Eventually will race over the value of `s` with the goroutine mutating the string.
Similarly, something like `Eventually(slice).Should(HaveLen(N))` probably won't do what you think it should -- `Eventually` will be passed a pointer to the slice, yes, but if the slice is being `append`ed to (as in: `slice = append(slice, ...)`) Go will generate a new pointer and the pointer passed to `Eventually` will not contain the new elements.
In both cases you should always pass `Eventually` a function that, when polled, returns the latest value of the object in question in a thread-safe way.
#### Category 2: Making `Eventually` assertions on functions
`Eventually` can be passed functions that **return at least one value**. When configured this way, `Eventually` will poll the function repeatedly and pass the first returned value to the matcher.
For example:
```go
Eventually(func() int {
return client.FetchCount()
}).Should(BeNumerically(">=", 17))
```
will repeatedly poll `client.FetchCount` until the `BeNumerically` matcher is satisfied.
> Note that this example could have been written as `Eventually(client.FetchCount).Should(BeNumerically(">=", 17))`
If multiple values are returned by the function, `Eventually` will pass the first value to the matcher and require that all others are zero-valued. This allows you to pass `Eventually` a function that returns a value and an error - a common pattern in Go.
For example, consider a method that returns a value and an error:
```go
func FetchFromDB() (string, error)
```
Then
```go
Eventually(FetchFromDB).Should(Equal("got it"))
```
will pass only if and when the returned error is `nil` *and* the returned string satisfies the matcher.
Eventually can also accept functions that take arguments, however you must provide those arguments using `Eventually().WithArguments()`. For example, consider a function that takes a user-id and makes a network request to fetch a full name:
```go
func FetchFullName(userId int) (string, error)
```
You can poll this function like so:
```go
Eventually(FetchFullName).WithArguments(1138).Should(Equal("Wookie"))
```
`WithArguments()` supports multiple arguments as well as variadic arguments.
It is important to note that the function passed into Eventually is invoked **synchronously** when polled. `Eventually` does not (in fact, it cannot) kill the function if it takes longer to return than `Eventually`'s configured timeout. This is where using a `context.Context` can be helpful. Here is an example that leverages Gingko's support for interruptible nodes and spec timeouts:
```go
It("fetches the correct count", func(ctx SpecContext) {
Eventually(func() int {
return client.FetchCount(ctx, "/users")
}, ctx).Should(BeNumerically(">=", 17))
}, SpecTimeout(time.Second))
```
now when the spec times out both the `client.FetchCount` function and `Eventually` will be signaled and told to exit. you can also use `Eventually().WithContext(ctx)` to provide the context.
Since functions that take a context.Context as a first-argument are common in Go, `Eventually` supports automatically injecting the provided context into the function. This plays nicely with `WithArguments()` as well. You can rewrite the above example as:
```go
It("fetches the correct count", func(ctx SpecContext) {
Eventually(client.FetchCount).WithContext(ctx).WithArguments("/users").Should(BeNumerically(">=", 17))
}, SpecTimeout(time.Second))
```
now the `ctx` `SpecContext` is used both by `Eventually` and `client.FetchCount` and the `"/users"` argument is passed in after the `ctx` argument.
The use of a context also allows you to specify a single timeout across a collection of `Eventually` assertions:
```go
It("adds a few books and checks the count", func(ctx SpecContext) {
intialCount := client.FetchCount(ctx, "/items")
client.AddItem(ctx, "foo")
client.AddItem(ctx, "bar")
//note that there are several supported ways to pass in the context. All are equivalent:
Eventually(ctx, client.FetchCount).WithArguments("/items").Should(BeNumerically("==", initialCount + 2))
Eventually(client.FetchItems).WithContext(ctx).Should(ContainElement("foo"))
Eventually(client.FetchItems, ctx).Should(ContainElement("foo"))
}, SpecTimeout(time.Second * 5))
```
In addition, Gingko's `SpecContext` allows Gomega to tell Ginkgo about the status of a currently running `Eventually` whenever a Progress Report is generated. So, if a spec times out while running an `Eventually` Ginkgo will not only show you which `Eventually` was running when the timeout occurred, but will also include the failure the `Eventually` was hitting when the timeout occurred.
#### Category 3: Making assertions _in_ the function passed into `Eventually`
When testing complex systems it can be valuable to assert that a *set* of assertions passes `Eventually`. `Eventually` supports this by accepting functions that take **a single `Gomega` argument** and **return zero or more values**.
Here's an example that makes some assertions and returns a value and error:
```go
Eventually(func(g Gomega) (Widget, error) {
ids, err := client.FetchIDs()
g.Expect(err).NotTo(HaveOccurred())
g.Expect(ids).To(ContainElement(1138))
return client.FetchWidget(1138)
}).Should(Equal(expectedWidget))
```
will pass only if all the assertions in the polled function pass and the return value satisfied the matcher. Note that the assertions in the body of the polled function must be performed using the passed-in `g Gomega` object. If you use the global DSL expectations, `Eventually` will not intercept any failures and the test will fail.
`Eventually` also supports a special case polling function that takes a single `Gomega` argument and returns no values. `Eventually` assumes such a function is making assertions and is designed to work with the `Succeed` matcher to validate that all assertions have passed.
For example:
```go
Eventually(func(g Gomega) {
model, err := client.Find(1138)
g.Expect(err).NotTo(HaveOccurred())
g.Expect(model.Reticulate()).To(Succeed())
g.Expect(model.IsReticulated()).To(BeTrue())
g.Expect(model.Save()).To(Succeed())
}).Should(Succeed())
```
will rerun the function until all assertions pass.
You can also pass additional arguments to functions that take a Gomega. The only rule is that the Gomega argument must be first. If you also want to pass the context attached to `Eventually` you must ensure that is the second argument. For example:
```go
Eventually(func(g Gomega, ctx context.Context, path string, expected ...string){
tok, err := client.GetToken(ctx)
g.Expect(err).NotTo(HaveOccurred())
elements, err := client.Fetch(ctx, tok, path)
g.Expect(err).NotTo(HaveOccurred())
g.Expect(elements).To(ConsistOf(expected))
}).WithContext(ctx).WithArguments("/names", "Joe", "Jane", "Sam").Should(Succeed())
```
### Consistently
`Consistently` checks that an assertion passes for a period of time. It does this by polling its argument repeatedly during the period. It fails if the matcher ever fails during that period.
For example:
```go
Consistently(func() []int {
return thing.MemoryUsage()
}).Should(BeNumerically("<", 10))
```
`Consistently` will poll the passed in function repeatedly and check the return value against the `GomegaMatcher`. `Consistently` blocks and only returns when the desired duration has elapsed or if the matcher fails or if an (optional) passed-in context is cancelled. The default value for the wait-duration is 100 milliseconds. The default polling interval is 10 milliseconds. Like `Eventually`, you can change these values by passing them in just after your function:
```go
Consistently(ACTUAL, (DURATION), (POLLING_INTERVAL), (context.Context)).Should(MATCHER)
```
As with `Eventually`, the duration parameters can be `time.Duration`s, string representations of a `time.Duration` (e.g. `"200ms"`) or `float64`s that are interpreted as seconds.
Also as with `Eventually`, `Consistently` supports chaining `WithTimeout`, `WithPolling`, `WithContext` and `WithArguments` in the form of:
```go
Consistently(ACTUAL).WithTimeout(DURATION).WithPolling(POLLING_INTERVAL).WithContext(ctx).WithArguments(...).Should(MATCHER)
```
`Consistently` tries to capture the notion that something "does not eventually" happen. A common use-case is to assert that no goroutine writes to a channel for a period of time. If you pass `Consistently` an argument that is not a function, it simply passes that argument to the matcher. So we can assert that:
```go
Consistently(channel).ShouldNot(Receive())
```
To assert that nothing gets sent to a channel.
As with `Eventually`, you can also pass `Consistently` a function. In fact, `Consistently` works with the three categories of `ACTUAL` value outlined for `Eventually` in the section above.
If `Consistently` is passed a `context.Context` it will exit if the context is cancelled - however it will always register the cancellation of the context as a failure. That is, the context is not used to control the duration of `Consistently` - that is always done by the `DURATION` parameter; instead, the context is used to allow `Consistently` to bail out early if it's time for the spec to finish up (e.g. a timeout has elapsed, or the user has sent an interrupt signal).
When no explicit duration is provided, `Consistently` will use the default duration. Unlike `Eventually`, this behavior holds whether or not a context is provided.
> Developers often try to use `runtime.Gosched()` to nudge background goroutines to run. This can lead to flaky tests as it is not deterministic that a given goroutine will run during the `Gosched`. `Consistently` is particularly handy in these cases: it polls for 100ms which is typically more than enough time for all your Goroutines to run. Yes, this is basically like putting a time.Sleep() in your tests... Sometimes, when making negative assertions in a concurrent world, that's the best you can do!
### Bailing Out Early - Polling Functions
There are cases where you need to signal to `Eventually` and `Consistently` that they should stop trying. Gomega provides`StopTrying(message string)` to allow you to send that signal. There are two ways to use `StopTrying`.
First, you can return `StopTrying` as an error. Consider, for example, the case where `Eventually` is searching through a set of possible queries with a server:
```go
playerIndex, numPlayers := 0, 11
Eventually(func() (string, error) {
if playerIndex == numPlayers {
return "", StopTrying("no more players left")
}
name := client.FetchPlayer(playerIndex)
playerIndex += 1
return name, nil
}).Should(Equal("Patrick Mahomes"))
```
Here we return a `StopTrying` error to tell `Eventually` that we've looked through all possible players and that it should stop.
You can also call `StopTrying(...).Now()` to immediately end execution of the function. Consider, for example, the case of a client communicating with a server that experiences an irrevocable error:
```go
Eventually(func() []string {
names, err := client.FetchAllPlayers()
if err == client.IRRECOVERABLE_ERROR {
StopTrying("An irrecoverable error occurred").Now()
}
return names
}).Should(ContainElement("Patrick Mahomes"))
```
calling `.Now()` will trigger a panic that will signal to `Eventually` that it should stop trying.
You can also return `StopTrying()` errors and use `StopTrying().Now()` with `Consistently`.
Both `Eventually` and `Consistently` always treat the `StopTrying()` signal as a failure. The failure message will include the message passed in to `StopTrying()`.
You can add additional information to this failure message in a few ways. You can wrap an error via `StopTrying(message).Wrap(wrappedErr)` - now the output will read `: `.
You can also attach arbitrary objects to `StopTrying()` via `StopTrying(message).Attach(description string, object any)`. Gomega will run the object through Gomega's standard formatting library to build a consistent representation for end users. You can attach multiple objects in this way and the output will look like:
```
Told to stop trying after
:
:
:
```
### Bailing Out Early - Matchers
Just like functions being polled, matchers can also indicate if `Eventually`/`Consistently` should stop polling. Matchers implement a `Match` method with the following signature:
```go
Match(actual interface{}) (success bool, err error)
```
If a matcher returns `StopTrying` for `error`, or calls `StopTrying(...).Now()`, `Eventually` and `Consistently` will stop polling and fail: `StopTrying` **always** signifies a failure.
> Note: An alternative mechanism for having matchers bail out early is documented in the [custom matchers section below](#aborting-eventuallyconsistently). This mechanism, which entails implementing a `MatchMayChangeIntheFuture() bool` method, allows matchers to signify that no future change is possible out-of-band of the call to the matcher.
### Changing the Polling Interval Dynamically
You typically configure the polling interval for `Eventually` and `Consistently` using the `.WithPolling()` or `.ProbeEvery()` chaining methods. Sometimes, however, a polled function or matcher might want to signal that a service is unavailable but should be tried again after a certain duration.
You can signal this to both `Eventually` and `Consistently` using `TryAgainAfter()`. This error-signal operates like `StopTrying()`: you can return `TryAgainAfter()` as an error or throw a panic via `TryAgainAfter().Now()`. In either case, both `Eventually` and `Consistently` will wait for the specified duration before trying again.
If a timeout occurs after the `TryAgainAfter` signal is sent but _before_ the next poll occurs both `Eventually` _and_ `Consistently` will always fail and print out the content of `TryAgainAfter`. The default message is `"told to try again after "` however, as with `StopTrying` you can use `.Wrap()` and `.Attach()` to wrap an error and attach additional objects to include in the message, respectively.
### Modifying Default Intervals
By default, `Eventually` will poll every 10 milliseconds for up to 1 second and `Consistently` will monitor every 10 milliseconds for up to 100 milliseconds. You can modify these defaults across your test suite with:
```go
SetDefaultEventuallyTimeout(t time.Duration)
SetDefaultEventuallyPollingInterval(t time.Duration)
SetDefaultConsistentlyDuration(t time.Duration)
SetDefaultConsistentlyPollingInterval(t time.Duration)
```
You can also adjust these global timeouts by setting the `GOMEGA_DEFAULT_EVENTUALLY_TIMEOUT`, `GOMEGA_DEFAULT_EVENTUALLY_POLLING_INTERVAL`, `GOMEGA_DEFAULT_CONSISTENTLY_DURATION`, and `GOMEGA_DEFAULT_CONSISTENTLY_POLLING_INTERVAL` environment variables to a parseable duration string. The environment variables have a lower precedence than `SetDefault...()`.
## Making Assertions in Helper Functions
While writing [custom matchers](#adding-your-own-matchers) is an expressive way to make assertions against your code, it is often more convenient to write one-off helper functions like so:
```go
var _ = Describe("Turbo-encabulator", func() {
...
func assertTurboEncabulatorContains(components ...string) {
teComponents, err := turboEncabulator.GetComponents()
Expect(err).NotTo(HaveOccurred())
Expect(teComponents).To(HaveLen(components))
for _, component := range components {
Expect(teComponents).To(ContainElement(component))
}
}
It("should have components", func() {
assertTurboEncabulatorContains("semi-boloid slots", "grammeters")
})
})
```
This makes your tests more expressive and reduces boilerplate. However, when an assertion in the helper fails the line numbers provided by Gomega are unhelpful. Instead of pointing you to the line in your test that failed, they point you the line in the helper.
To fix this, Ginkgo and Gomega provide two options. If you are on a recent version of Ginkgo you can register your helper with Ginkgo via `GinkgoHelper()`:
```go
func assertTurboEncabulatorContains(components ...string) {
GinkgoHelper()
teComponents, err := turboEncabulator.GetComponents()
Expect(err).NotTo(HaveOccurred())
Expect(teComponents).To(HaveLen(components))
for _, component := range components {
Expect(teComponents).To(ContainElement(component))
}
}
```
now, line numbers generated by Ginkgo will skip `assertTurboEncabulatorContains` and point to the calling site instead. `GinkgoHelper()` is the recommended way to solve this problem as it allows for straightforward nesting and reuse of helper functions.
If, for some reason, you can't use `GinkgoHelper()` Gomega does provide an alternative: versions of `Expect`, `Eventually` and `Consistently` named `ExpectWithOffset`, `EventuallyWithOffset` and `ConsistentlyWithOffset` that allow you to specify an *offset* in the call stack. The offset is the first argument to these functions.
With this, we can rewrite our helper as:
```go
func assertTurboEncabulatorContains(components ...string) {
teComponents, err := turboEncabulator.GetComponents()
ExpectWithOffset(1, err).NotTo(HaveOccurred())
ExpectWithOffset(1, teComponents).To(HaveLen(components))
for _, component := range components {
ExpectWithOffset(1, teComponents).To(ContainElement(component))
}
}
```
Now, failed assertions will point to the correct call to the helper in the test.
Alternatively, you can just use the baseline versions of `Expect`, `Eventually` and `Consistently` and combine them with `WithOffset`:
```go
func assertTurboEncabulatorContains(components ...string) {
teComponents, err := turboEncabulator.GetComponents()
Expect(err).WithOffset(1).NotTo(HaveOccurred())
Expect(teComponents).WithOffset(1).To(HaveLen(components))
for _, component := range components {
Expect(teComponents).WithOffset(1).To(ContainElement(component))
}
}
```
Again, we recommend using `GinkgoHelper()` instead of `WithOffset(...)`.
## Provided Matchers
Gomega comes with a bunch of `GomegaMatcher`s. They're all documented here. If there's one you'd like to see written either [send a pull request or open an issue](http://github.com/onsi/gomega).
A number of community-supported matchers have appeared as well. A list is maintained on the Gomega [wiki](https://github.com/onsi/gomega/wiki).
These docs only go over the positive assertion case (`Should`), the negative case (`ShouldNot`) is simply the negation of the positive case. They also use the `Ω` notation, but - as mentioned above - the `Expect` notation is equivalent.
### Asserting Equivalence
#### Equal(expected interface{})
```go
Ω(ACTUAL).Should(Equal(EXPECTED))
```
uses [`reflect.DeepEqual`](http://golang.org/pkg/reflect#deepequal) to compare `ACTUAL` with `EXPECTED`.
`reflect.DeepEqual` is awesome. It will use `==` when appropriate (e.g. when comparing primitives) but will recursively dig into maps, slices, arrays, and even your own structs to ensure deep equality. `reflect.DeepEqual`, however, is strict about comparing types. Both `ACTUAL` and `EXPECTED` *must* have the same type. If you want to compare across different types (e.g. if you've defined a type alias) you should use `BeEquivalentTo`.
It is an error for both `ACTUAL` and `EXPECTED` to be nil, you should use `BeNil()` instead.
When both `ACTUAL` and `EXPECTED` are a very long strings, it will attempt to pretty-print the diff and display exactly where they differ.
> For asserting equality between numbers of different types, you'll want to use the [`BeNumerically()`](#benumericallycomparator-string-compareto-interface) matcher.
#### BeComparableTo(expected interface{}, options ...cmp.Option)
```go
Ω(ACTUAL).Should(BeComparableTo(EXPECTED, options ...cmp.Option))
```
uses [`gocmp.Equal`](http://github.com/google/go-cmp) from `github.com/google/go-cmp` to compare `ACTUAL` with `EXPECTED`. This performs a deep object comparison like `reflect.DeepEqual` but offers a few additional configuration options. Learn more at the [go-cmp godocs](https://pkg.go.dev/github.com/google/go-cmp).
#### BeEquivalentTo(expected interface{})
```go
Ω(ACTUAL).Should(BeEquivalentTo(EXPECTED))
```
Like `Equal`, `BeEquivalentTo` uses `reflect.DeepEqual` to compare `ACTUAL` with `EXPECTED`. Unlike `Equal`, however, `BeEquivalentTo` will first convert `ACTUAL`'s type to that of `EXPECTED` before making the comparison with `reflect.DeepEqual`.
This means that `BeEquivalentTo` will successfully match equivalent values of different types. This is particularly useful, for example, with type aliases:
```go
type FoodSrce string
Ω(FoodSrce("Cheeseboard Pizza")
).Should(Equal("Cheeseboard Pizza")) //will fail
Ω(FoodSrce("Cheeseboard Pizza")
).Should(BeEquivalentTo("Cheeseboard Pizza")) //will pass
```
As with `Equal` it is an error for both `ACTUAL` and `EXPECTED` to be nil, you should use `BeNil()` instead.
As a rule, you **should not** use `BeEquivalentTo` with numbers. Both of the following assertions are true:
```go
Ω(5.1).Should(BeEquivalentTo(5))
Ω(5).ShouldNot(BeEquivalentTo(5.1))
```
the first assertion passes because 5.1 will be cast to an integer and will get rounded down! Such false positives are terrible and should be avoided. Use [`BeNumerically()`](#benumericallycomparator-string-compareto-interface) to compare numbers instead.
#### BeIdenticalTo(expected interface{})
```go
Ω(ACTUAL).Should(BeIdenticalTo(EXPECTED))
```
Like `Equal`, `BeIdenticalTo` compares `ACTUAL` to `EXPECTED` for equality. Unlike `Equal`, however, it uses `==` to compare values. In practice, this means that primitive values like strings, integers and floats are identical to, as well as pointers to values.
`BeIdenticalTo` is most useful when you want to assert that two pointers point to the exact same location in memory.
As with `Equal` it is an error for both `ACTUAL` and `EXPECTED` to be nil, you should use `BeNil()` instead.
#### BeAssignableToTypeOf(expected interface)
```go
Ω(ACTUAL).Should(BeAssignableToTypeOf(EXPECTED interface))
```
succeeds if `ACTUAL` is a type that can be assigned to a variable with the same type as `EXPECTED`. It is an error for either `ACTUAL` or `EXPECTED` to be `nil`.
### Asserting Presence
#### BeNil()
```go
Ω(ACTUAL).Should(BeNil())
```
succeeds if `ACTUAL` is, in fact, `nil`.
#### BeZero()
```go
Ω(ACTUAL).Should(BeZero())
```
succeeds if `ACTUAL` is the zero value for its type *or* if `ACTUAL` is `nil`.
### Asserting Truthiness
#### BeTrue()
```go
Ω(ACTUAL).Should(BeTrue())
```
succeeds if `ACTUAL` is `bool` typed and has the value `true`. It is an error for `ACTUAL` to not be a `bool`.
> Some matcher libraries have a notion of "truthiness" to assert that an object is present. Gomega is strict, and `BeTrue()` only works with `bool`s. You can use `Ω(ACTUAL).ShouldNot(BeZero())` or `Ω(ACTUAL).ShouldNot(BeNil())` to verify object presence.
#### BeFalse()
```go
Ω(ACTUAL).Should(BeFalse())
```
succeeds if `ACTUAL` is `bool` typed and has the value `false`. It is an error for `ACTUAL` to not be a `bool`.
### Asserting on Errors
#### HaveOccurred()
```go
Ω(ACTUAL).Should(HaveOccurred())
```
succeeds if `ACTUAL` is a non-nil `error`. Thus, the typical Go error checking pattern looks like:
```go
err := SomethingThatMightFail()
Ω(err).ShouldNot(HaveOccurred())
```
#### Succeed()
```go
Ω(ACTUAL).Should(Succeed())
```
succeeds if `ACTUAL` is `nil`. The intended usage is
```go
Ω(FUNCTION()).Should(Succeed())
```
where `FUNCTION()` is a function call that returns an error-type as its *first or only* return value. See [Handling Errors](#handling-errors) for a more detailed discussion.
#### MatchError(expected interface{})
```go
Ω(ACTUAL).Should(MatchError(EXPECTED))
```
succeeds if `ACTUAL` is a non-nil `error` that matches `EXPECTED`. `EXPECTED` must be one of the following:
- A string, in which case `ACTUAL.Error()` will be compared against `EXPECTED`.
- A matcher, in which case `ACTUAL.Error()` is tested against the matcher.
- An error, in which case any of the following is satisfied:
- `errors.Is(ACTUAL, EXPECTED)` returns `true`
- `ACTUAL` or any of the errors it wraps (directly or indirectly) equals `EXPECTED` in terms of `reflect.DeepEqual()`.
Any other type for `EXPECTED` is an error. It is also an error for `ACTUAL` to be nil.
### Working with Channels
#### BeClosed()
```go
Ω(ACTUAL).Should(BeClosed())
```
succeeds if `ACTUAL` is a closed channel. It is an error to pass a non-channel to `BeClosed`, it is also an error to pass `nil`.
In order to check whether or not the channel is closed, Gomega must try to read from the channel (even in the `ShouldNot(BeClosed())` case). You should keep this in mind if you wish to make subsequent assertions about values coming down the channel.
Also, if you are testing that a *buffered* channel is closed you must first read all values out of the channel before asserting that it is closed (it is not possible to detect that a buffered-channel has been closed until all its buffered values are read).
Finally, as a corollary: it is an error to check whether or not a send-only channel is closed.
#### Receive()
```go
Ω(ACTUAL).Should(Receive())
```
succeeds if there is a message to be received on actual. Actual must be a channel (and cannot be a send-only channel) -- anything else is an error.
`Receive` returns *immediately*. It *never* blocks:
- If there is nothing on the channel `c` then `Ω(c).Should(Receive())` will fail and `Ω(c).ShouldNot(Receive())` will pass.
- If there is something on the channel `c` ready to be read, then `Ω(c).Should(Receive())` will pass and `Ω(c).ShouldNot(Receive())` will fail.
- If the channel `c` is closed then `Ω(c).Should(Receive())` will fail and `Ω(c).ShouldNot(Receive())` will pass.
If you have a go-routine running in the background that will write to channel `c`, for example:
```go
go func() {
time.Sleep(100 * time.Millisecond)
c <- true
}()
```
you can assert that `c` receives something (anything!) eventually:
```go
Eventually(c).Should(Receive())
```
This will timeout if nothing gets sent to `c` (you can modify the timeout interval as you normally do with `Eventually`).
A similar use-case is to assert that no go-routine writes to a channel (for a period of time). You can do this with `Consistently`:
```go
Consistently(c).ShouldNot(Receive())
```
`Receive` also allows you to make assertions on the received object. You do this by passing `Receive` a matcher:
```go
Eventually(c).Should(Receive(Equal("foo")))
```
This assertion will only succeed if `c` receives an object *and* that object satisfies `Equal("foo")`. Note that `Eventually` will continually poll `c` until this condition is met. If there are objects coming down the channel that do not satisfy the passed in matcher, they will be pulled off and discarded until an object that *does* satisfy the matcher is received.
In addition, there are occasions when you need to grab the object sent down the channel (e.g. to make several assertions against the object). To do this, you can ask the `Receive` matcher for the value passed to the channel by passing it a pointer to a variable of the appropriate type:
```go
var receivedBagel Bagel
Eventually(bagelChan).Should(Receive(&receivedBagel))
Ω(receivedBagel.Contents()).Should(ContainElement("cream cheese"))
Ω(receivedBagel.Kind()).Should(Equal("sesame"))
```
Of course, this could have been written as `receivedBagel := <-bagelChan` - however using `Receive` makes it easy to avoid hanging the test suite should nothing ever come down the channel. The pointer can point to any variable whose type is assignable from the channel element type, or if the channel type is an interface and the underlying type is assignable to the pointer.
Finally, `Receive` *never* blocks. `Eventually(c).Should(Receive())` repeatedly polls `c` in a non-blocking fashion. That means that you cannot use this pattern to verify that a *non-blocking send* has occurred on the channel - [more details at this GitHub issue](https://github.com/onsi/gomega/issues/82).
#### BeSent(value interface{})
```go
Ω(ACTUAL).Should(BeSent(VALUE))
```
attempts to send `VALUE` to the channel `ACTUAL` without blocking. It succeeds if this is possible.
`ACTUAL` must be a channel (and cannot be a receive-only channel) that can be sent the type of the `VALUE` passed into `BeSent` -- anything else is an error. In addition, `ACTUAL` must not be closed.
`BeSent` never blocks:
- If the channel `c` is not ready to receive then `Ω(c).Should(BeSent("foo"))` will fail immediately.
- If the channel `c` is eventually ready to receive then `Eventually(c).Should(BeSent("foo"))` will succeed... presuming the channel becomes ready to receive before `Eventually`'s timeout.
- If the channel `c` is closed then `Ω(c).Should(BeSent("foo"))` and `Ω(c).ShouldNot(BeSent("foo"))` will both fail immediately.
Of course, `VALUE` is actually sent to the channel. The point of `BeSent` is less to make an assertion about the availability of the channel (which is typically an implementation detail that your test should not be concerned with). Rather, the point of `BeSent` is to make it possible to easily and expressively write tests that can timeout on blocked channel sends.
### Working with files
#### BeAnExistingFile
```go
Ω(ACTUAL).Should(BeAnExistingFile())
```
succeeds if a file located at `ACTUAL` exists.
`ACTUAL` must be a string representing the filepath.
#### BeARegularFile
```go
Ω(ACTUAL).Should(BeARegularFile())
```
succeeds IFF a file located at `ACTUAL` exists and is a regular file.
`ACTUAL` must be a string representing the filepath.
#### BeADirectory
```go
Ω(ACTUAL).Should(BeADirectory())
```
succeeds IFF a file is located at `ACTUAL` exists and is a directory.
`ACTUAL` must be a string representing the filepath.
### Working with Strings, JSON and YAML
#### ContainSubstring(substr string, args ...interface{})
```go
Ω(ACTUAL).Should(ContainSubstring(STRING, ARGS...))
```
succeeds if `ACTUAL` contains the substring generated by:
```go
fmt.Sprintf(STRING, ARGS...)
```
`ACTUAL` must either be a `string`, `[]byte` or a `Stringer` (a type implementing the `String()` method). Any other input is an error.
> Note, of course, that the `ARGS...` are not required. They are simply a convenience to allow you to build up strings programmatically inline in the matcher.
#### HavePrefix(prefix string, args ...interface{})
```go
Ω(ACTUAL).Should(HavePrefix(STRING, ARGS...))
```
succeeds if `ACTUAL` has the string prefix generated by:
```go
fmt.Sprintf(STRING, ARGS...)
```
`ACTUAL` must either be a `string`, `[]byte` or a `Stringer` (a type implementing the `String()` method). Any other input is an error.
> Note, of course, that the `ARGS...` are not required. They are simply a convenience to allow you to build up strings programmatically inline in the matcher.
#### HaveSuffix(suffix string, args ...interface{})
```go
Ω(ACTUAL).Should(HaveSuffix(STRING, ARGS...))
```
succeeds if `ACTUAL` has the string suffix generated by:
```go
fmt.Sprintf(STRING, ARGS...)
```
`ACTUAL` must either be a `string`, `[]byte` or a `Stringer` (a type implementing the `String()` method). Any other input is an error.
> Note, of course, that the `ARGS...` are not required. They are simply a convenience to allow you to build up strings programmatically inline in the matcher.
#### MatchRegexp(regexp string, args ...interface{})
```go
Ω(ACTUAL).Should(MatchRegexp(STRING, ARGS...))
```
succeeds if `ACTUAL` is matched by the regular expression string generated by:
```go
fmt.Sprintf(STRING, ARGS...)
```
`ACTUAL` must either be a `string`, `[]byte` or a `Stringer` (a type implementing the `String()` method). Any other input is an error. It is also an error for the regular expression to fail to compile.
> Note, of course, that the `ARGS...` are not required. They are simply a convenience to allow you to build up strings programmatically inline in the matcher.
#### MatchJSON(json interface{})
```go
Ω(ACTUAL).Should(MatchJSON(EXPECTED))
```
Both `ACTUAL` and `EXPECTED` must be a `string`, `[]byte` or a `Stringer`. `MatchJSON` succeeds if both `ACTUAL` and `EXPECTED` are JSON representations of the same object. This is verified by parsing both `ACTUAL` and `EXPECTED` and then asserting equality on the resulting objects with `reflect.DeepEqual`. By doing this `MatchJSON` avoids any issues related to white space, formatting, and key-ordering.
It is an error for either `ACTUAL` or `EXPECTED` to be invalid JSON.
In some cases it is useful to match two JSON strings while ignoring list order. For this you can use the community maintained [MatchUnorderedJSON](https://github.com/Benjamintf1/Expanded-Unmarshalled-Matchers) matcher.
#### MatchXML(xml interface{})
```go
Ω(ACTUAL).Should(MatchXML(EXPECTED))
```
Both `ACTUAL` and `EXPECTED` must be a `string`, `[]byte` or a `Stringer`. `MatchXML` succeeds if both `ACTUAL` and `EXPECTED` are XML representations of the same object. This is verified by parsing both `ACTUAL` and `EXPECTED` and then asserting equality on the resulting objects with `reflect.DeepEqual`. By doing this `MatchXML` avoids any issues related to white space or formatting.
It is an error for either `ACTUAL` or `EXPECTED` to be invalid XML.
#### MatchYAML(yaml interface{})
```go
Ω(ACTUAL).Should(MatchYAML(EXPECTED))
```
Both `ACTUAL` and `EXPECTED` must be a `string`, `[]byte` or a `Stringer`. `MatchYAML` succeeds if both `ACTUAL` and `EXPECTED` are YAML representations of the same object. This is verified by parsing both `ACTUAL` and `EXPECTED` and then asserting equality on the resulting objects with `reflect.DeepEqual`. By doing this `MatchYAML` avoids any issues related to white space, formatting, and key-ordering.
It is an error for either `ACTUAL` or `EXPECTED` to be invalid YAML.
### Working with Collections
#### BeEmpty()
```go
Ω(ACTUAL).Should(BeEmpty())
```
succeeds if `ACTUAL` is, in fact, empty. `ACTUAL` must be of type `string`, `array`, `map`, `chan`, or `slice`. It is an error for it to have any other type.
#### HaveLen(count int)
```go
Ω(ACTUAL).Should(HaveLen(INT))
```
succeeds if the length of `ACTUAL` is `INT`. `ACTUAL` must be of type `string`, `array`, `map`, `chan`, or `slice`. It is an error for it to have any other type.
#### HaveCap(count int)
```go
Ω(ACTUAL).Should(HaveCap(INT))
```
succeeds if the capacity of `ACTUAL` is `INT`. `ACTUAL` must be of type `array`, `chan`, or `slice`. It is an error for it to have any other type.
#### ContainElement(element interface{})
```go
Ω(ACTUAL).Should(ContainElement(ELEMENT))
```
or
```go
Ω(ACTUAL).Should(ContainElement(ELEMENT, ))
```
succeeds if `ACTUAL` contains an element that equals `ELEMENT`. `ACTUAL` must be an `array`, `slice`, or `map` -- anything else is an error. For `map`s `ContainElement` searches through the map's values (not keys!).
By default `ContainElement()` uses the `Equal()` matcher under the hood to assert equality between `ACTUAL`'s elements and `ELEMENT`. You can change this, however, by passing `ContainElement` a `GomegaMatcher`. For example, to check that a slice of strings has an element that matches a substring:
```go
Ω([]string{"Foo", "FooBar"}).Should(ContainElement(ContainSubstring("Bar")))
```
In addition, there are occasions when you need to grab (all) matching contained elements, for instance, to make several assertions against the matching contained elements. To do this, you can ask the `ContainElement()` matcher for the matching contained elements by passing it a pointer to a variable of the appropriate type. If multiple matching contained elements are expected, then a pointer to either a slice or a map should be passed (but not a pointer to an array), otherwise a pointer to a scalar (non-slice, non-map):
```go
var findings []string
Ω([]string{"foo", "foobar", "bar"}).Should(ContainElement(ContainSubstring("foo"), &findings))
var finding string
Ω([]string{"foo", "foobar", "bar"}).Should(ContainElement("foobar", &finding))
```
The `ContainElement` matcher will fail with a descriptive error message in case of multiple matches when the pointer references a scalar type.
In case of maps, the matching contained elements will be returned with their keys in the map referenced by the pointer.
```go
var findings map[int]string
Ω(map[int]string{
1: "bar",
2: "foobar",
3: "foo",
}).Should(ContainElement(ContainSubstring("foo"), &findings))
```
#### ContainElements(element ...interface{})
```go
Ω(ACTUAL).Should(ContainElements(ELEMENT1, ELEMENT2, ELEMENT3, ...))
```
or
```go
Ω(ACTUAL).Should(ContainElements([]SOME_TYPE{ELEMENT1, ELEMENT2, ELEMENT3, ...}))
```
succeeds if `ACTUAL` contains the elements passed into the matcher. The ordering of the elements does not matter.
By default `ContainElements()` uses `Equal()` to match the elements, however custom matchers can be passed in instead. Here are some examples:
```go
Ω([]string{"Foo", "FooBar"}).Should(ContainElements("FooBar"))
Ω([]string{"Foo", "FooBar"}).Should(ContainElements(ContainSubstring("Bar"), "Foo"))
```
Actual must be an `array`, `slice` or `map`. For maps, `ContainElements` matches against the `map`'s values.
You typically pass variadic arguments to `ContainElements` (as in the examples above). However, if you need to pass in a slice you can provided that it
is the only element passed in to `ContainElements`:
```go
Ω([]string{"Foo", "FooBar"}).Should(ContainElements([]string{"FooBar", "Foo"}))
```
Note that Go's type system does not allow you to write this as `ContainElements([]string{"FooBar", "Foo"}...)` as `[]string` and `[]interface{}` are different types - hence the need for this special rule.
The difference between the `ContainElements` and `ConsistOf` matchers is that the latter is more restrictive because the `ConsistOf` matcher checks additionally that the `ACTUAL` elements and the elements passed into the matcher have the same length.
#### BeElementOf(elements ...interface{})
```go
Ω(ACTUAL).Should(BeElementOf(ELEMENT1, ELEMENT2, ELEMENT3, ...))
```
succeeds if `ACTUAL` equals one of the elements passed into the matcher. When a single element `ELEMENT` of type `array` or `slice` is passed into the matcher, `BeElementOf` succeeds if `ELEMENT` contains an element that equals `ACTUAL` (reverse of `ContainElement`). `BeElementOf` always uses the `Equal()` matcher under the hood to assert equality.
#### BeKeyOf(m interface{})
```go
Ω(ACTUAL).Should(BeKeyOf(MAP))
```
succeeds if `ACTUAL` equals one of the keys of `MAP`. It is an error for `MAP` to be of any type other than a map. `BeKeyOf` always uses the `Equal()` matcher under the hood to assert equality of `ACTUAL` with a map key.
`BeKeyOf` can be used in situations where it is not possible to rewrite an assertion to use the more idiomatic `HaveKey`: one use is in combination with `ContainElement` doubling as a filter. For instance, the following example asserts that all expected specific sprockets are present in a larger list of sprockets:
```go
var names = map[string]struct {
detail string
}{
"edgy_emil": {detail: "sprocket_project_A"},
"furious_freddy": {detail: "sprocket_project_B"},
}
var canaries []Sprocket
Expect(projects).To(ContainElement(HaveField("Name", BeKeyOf(names)), &canaries))
Expect(canaries).To(HaveLen(len(names)))
```
#### ConsistOf(element ...interface{})
```go
Ω(ACTUAL).Should(ConsistOf(ELEMENT1, ELEMENT2, ELEMENT3, ...))
```
or
```go
Ω(ACTUAL).Should(ConsistOf([]SOME_TYPE{ELEMENT1, ELEMENT2, ELEMENT3, ...}))
```
succeeds if `ACTUAL` contains precisely the elements passed into the matcher. The ordering of the elements does not matter.
By default `ConsistOf()` uses `Equal()` to match the elements, however custom matchers can be passed in instead. Here are some examples:
```go
Ω([]string{"Foo", "FooBar"}).Should(ConsistOf("FooBar", "Foo"))
Ω([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Bar"), "Foo"))
Ω([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Foo"), ContainSubstring("Foo")))
```
Actual must be an `array`, `slice` or `map`. For maps, `ConsistOf` matches against the `map`'s values.
You typically pass variadic arguments to `ConsistOf` (as in the examples above). However, if you need to pass in a slice you can provided that it
is the only element passed in to `ConsistOf`:
```go
Ω([]string{"Foo", "FooBar"}).Should(ConsistOf([]string{"FooBar", "Foo"}))
```
Note that Go's type system does not allow you to write this as `ConsistOf([]string{"FooBar", "Foo"}...)` as `[]string` and `[]interface{}` are different types - hence the need for this special rule.
#### HaveExactElements(element ...interface{})
```go
Expect(ACTUAL).To(HaveExactElements(ELEMENT1, ELEMENT2, ELEMENT3, ...))
```
or
```go
Expect(ACTUAL).To(HaveExactElements([]SOME_TYPE{ELEMENT1, ELEMENT2, ELEMENT3, ...}))
```
succeeds if `ACTUAL` contains precisely the elements and ordering passed into the matchers.
By default `HaveExactElements()` uses `Equal()` to match the elements, however custom matchers can be passed in instead. Here are some examples:
```go
Expect([]string{"Foo", "FooBar"}).To(HaveExactElements("Foo", "FooBar"))
Expect([]string{"Foo", "FooBar"}).To(HaveExactElements("Foo", ContainSubstring("Bar")))
Expect([]string{"Foo", "FooBar"}).To(HaveExactElements(ContainSubstring("Foo"), ContainSubstring("Foo")))
```
Actual must be an `array` or `slice`.
You typically pass variadic arguments to `HaveExactElements` (as in the examples above). However, if you need to pass in a slice you can provided that it
is the only element passed in to `HaveExactElements`:
```go
Expect([]string{"Foo", "FooBar"}).To(HaveExactElements([]string{"FooBar", "Foo"}))
```
Note that Go's type system does not allow you to write this as `HaveExactElements([]string{"FooBar", "Foo"}...)` as `[]string` and `[]interface{}` are different types - hence the need for this special rule.
#### HaveEach(element ...interface{})
```go
Ω(ACTUAL).Should(HaveEach(ELEMENT))
```
succeeds if `ACTUAL` solely consists of elements that equal `ELEMENT`. `ACTUAL` must be an `array`, `slice`, or `map` -- anything else is an error. For `map`s `HaveEach` searches through the map's values (not keys!).
In order to avoid ambiguity it is an error for `ACTUAL` to be an empty `array`, `slice`, or `map` (or a correctly typed `nil`) -- in these cases it cannot be decided if `HaveEach` should match, or should not match. If in your test it is acceptable for `ACTUAL` to be empty, you can use `Or(BeEmpty(), HaveEach(ELEMENT))` instead.
By default `HaveEach()` uses the `Equal()` matcher under the hood to assert equality between `ACTUAL`'s elements and `ELEMENT`. You can change this, however, by passing `HaveEach` a `GomegaMatcher`. For example, to check that a slice of strings has an element that matches a substring:
```go
Ω([]string{"Foo", "FooBar"}).Should(HaveEach(ContainSubstring("Foo")))
```
#### HaveKey(key interface{})
```go
Ω(ACTUAL).Should(HaveKey(KEY))
```
succeeds if `ACTUAL` is a map with a key that equals `KEY`. It is an error for `ACTUAL` to not be a `map`.
By default `HaveKey()` uses the `Equal()` matcher under the hood to assert equality between `ACTUAL`'s keys and `KEY`. You can change this, however, by passing `HaveKey` a `GomegaMatcher`. For example, to check that a map has a key that matches a regular expression:
```go
Ω(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKey(MatchRegexp(`.+Foo$`)))
```
#### HaveKeyWithValue(key interface{}, value interface{})
```go
Ω(ACTUAL).Should(HaveKeyWithValue(KEY, VALUE))
```
succeeds if `ACTUAL` is a map with a key that equals `KEY` mapping to a value that equals `VALUE`. It is an error for `ACTUAL` to not be a `map`.
By default `HaveKeyWithValue()` uses the `Equal()` matcher under the hood to assert equality between `ACTUAL`'s keys and `KEY` and between the associated value and `VALUE`. You can change this, however, by passing `HaveKeyWithValue` a `GomegaMatcher` for either parameter. For example, to check that a map has a key that matches a regular expression and which is also associated with a value that passes some numerical threshold:
```go
Ω(map[string]int{"Foo": 3, "BazFoo": 4}).Should(HaveKeyWithValue(MatchRegexp(`.+Foo$`), BeNumerically(">", 3)))
```
#### HaveField(field interface{}, value interface{})
```go
Ω(ACTUAL).Should(HaveField(FIELD, VALUE))
```
succeeds if `ACTUAL` is a struct with a value that can be traversed via `FIELD` that equals `VALUE`. It is an error for `ACTUAL` to not be a `struct`.
By default `HaveField()` uses the `Equal()` matcher under the hood to assert equality between the extracted value and `VALUE`. You can change this, however, by passing `HaveField` a `GomegaMatcher` for `VALUE`.
`FIELD` allows you to access fields within the `ACTUAL` struct. Nested structs can be accessed using the `.` delimiter. `HaveField()` also allows you to invoke methods on the struct by adding a `()` suffix to the `FIELD` - these methods must take no arguments and return exactly one value. For example consider the following types:
```go
type Book struct {
Title string
Author Person
}
type Person struct {
Name string
DOB time.Time
}
```
and an instance book `var book = Book{...}` - you can use `HaveField` to make assertions like:
```go
Ω(book).Should(HaveField("Title", "Les Miserables"))
Ω(book).Should(HaveField("Title", ContainSubstring("Les Mis")))
Ω(book).Should(HaveField("Author.Name", "Victor Hugo"))
Ω(book).Should(HaveField("Author.DOB.Year()", BeNumerically("<", 1900)))
```
`HaveField` can pair powerfully with a collection matcher like `ContainElement`. To assert that a list of books as at least one element with an author born in February you could write:
```go
Ω(books).Should(ContainElement(HaveField("Author.DOB.Month()", Equal(2))))
```
If you want to make lots of complex assertions against the fields of a struct take a look at the [`gstruct`package](#gstruct-testing-complex-data-types) package documented below.
#### HaveExistingField(field interface{})
While `HaveField()` considers a missing field to be an error (instead of non-success), combining it with `HaveExistingField()` allows `HaveField()` to be reused in test contexts other than assertions: for instance, as filters to [`ContainElement(ELEMENT, )`](#containelementelement-interface) or in detecting resource leaks (like leaked file descriptors).
```go
Ω(ACTUAL).Should(HaveExistingField(FIELD))
```
succeeds if `ACTUAL` is a struct with a field `FIELD`, regardless of this field's value. It is an error for `ACTUAL` to not be a `struct`. Like `HaveField()`, `HaveExistingField()` supports accessing nested structs using the `.` delimiter. Methods on the struct are invoked by adding a `()` suffix to the `FIELD` - these methods must take no arguments and return exactly one value.
To assert a particular field value, but only if such a field exists in an `ACTUAL` struct, use the composing [`And`](#andmatchers-gomegamatcher) matcher:
```go
Ω(ACTUAL).Should(And(HaveExistingField(FIELD), HaveField(FIELD, VALUE)))
```
### Working with Numbers and Times
#### BeNumerically(comparator string, compareTo ...interface{})
```go
Ω(ACTUAL).Should(BeNumerically(COMPARATOR_STRING, EXPECTED, ))
```
performs numerical assertions in a type-agnostic way. `ACTUAL` and `EXPECTED` should be numbers, though the specific type of number is irrelevant (`float32`, `float64`, `uint8`, etc...). It is an error for `ACTUAL` or `EXPECTED` to not be a number.
There are six supported comparators:
- `Ω(ACTUAL).Should(BeNumerically("==", EXPECTED))`:
asserts that `ACTUAL` and `EXPECTED` are numerically equal.
- `Ω(ACTUAL).Should(BeNumerically("~", EXPECTED, ))`:
asserts that `ACTUAL` and `EXPECTED` are within `` of one another. By default `` is `1e-8` but you can specify a custom value.
- `Ω(ACTUAL).Should(BeNumerically(">", EXPECTED))`:
asserts that `ACTUAL` is greater than `EXPECTED`.
- `Ω(ACTUAL).Should(BeNumerically(">=", EXPECTED))`:
asserts that `ACTUAL` is greater than or equal to `EXPECTED`.
- `Ω(ACTUAL).Should(BeNumerically("<", EXPECTED))`:
asserts that `ACTUAL` is less than `EXPECTED`.
- `Ω(ACTUAL).Should(BeNumerically("<=", EXPECTED))`:
asserts that `ACTUAL` is less than or equal to `EXPECTED`.
Any other comparator is an error.
#### BeTemporally(comparator string, compareTo time.Time, threshold ...time.Duration)
```go
Ω(ACTUAL).Should(BeTemporally(COMPARATOR_STRING, EXPECTED_TIME, ))
```
performs time-related assertions. `ACTUAL` must be a `time.Time`.
There are six supported comparators:
- `Ω(ACTUAL).Should(BeTemporally("==", EXPECTED_TIME))`:
asserts that `ACTUAL` and `EXPECTED_TIME` are identical `time.Time`s.
- `Ω(ACTUAL).Should(BeTemporally("~", EXPECTED_TIME, ))`:
asserts that `ACTUAL` and `EXPECTED_TIME` are within `` of one another. By default `` is `time.Millisecond` but you can specify a custom value.
- `Ω(ACTUAL).Should(BeTemporally(">", EXPECTED_TIME))`:
asserts that `ACTUAL` is after `EXPECTED_TIME`.
- `Ω(ACTUAL).Should(BeTemporally(">=", EXPECTED_TIME))`:
asserts that `ACTUAL` is after or at `EXPECTED_TIME`.
- `Ω(ACTUAL).Should(BeTemporally("<", EXPECTED_TIME))`:
asserts that `ACTUAL` is before `EXPECTED_TIME`.
- `Ω(ACTUAL).Should(BeTemporally("<=", EXPECTED_TIME))`:
asserts that `ACTUAL` is before or at `EXPECTED_TIME`.
Any other comparator is an error.
### Working with Values
#### HaveValue(matcher types.GomegaMatcher)
`HaveValue` applies `MATCHER` to the value that results from dereferencing `ACTUAL` in case of a pointer or an interface, or otherwise `ACTUAL` itself. Pointers and interfaces are dereferenced multiple times as necessary, with a limit of at most 31 dereferences. It will fail if the pointer value is `nil`:
```go
Expect(ACTUAL).To(HaveValue(MATCHER))
```
For instance:
```go
i := 42
Expect(&i).To(HaveValue(Equal(42)))
Expect(i).To(HaveValue(Equal(42)))
```
`HaveValue` can be used, for instance, in tests and custom matchers where the it doesn't matter (as opposed to `PointTo`) if a value first needs to be dereferenced or not. This is especially useful to custom matchers that are to be used in mixed contexts of pointers as well as non-pointers.
Please note that negating the outcome of `HaveValue(nil)` won't suppress any error; for instance, in order to assert not having a specific value while still accepting `nil` the following matcher expression might be used:
```go
Or(BeNil(), Not(HaveValue(...)))
```
### Working with HTTP responses
#### HaveHTTPStatus(expected interface{})
```go
Expect(ACTUAL).To(HaveHTTPStatus(EXPECTED, ...))
```
succeeds if the `Status` or `StatusCode` field of an HTTP response matches.
`ACTUAL` must be either a `*http.Response` or `*httptest.ResponseRecorder`.
`EXPECTED` must be one or more `int` or `string` types. An `int` is compared
to `StatusCode` and a `string` is compared to `Status`.
The matcher succeeds if any of the `EXPECTED` values match.
Here are some examples:
- `Expect(resp).To(HaveHTTPStatus(http.StatusOK, http.StatusNoContext))`:
asserts that `resp.StatusCode == 200` or `resp.StatusCode == 204`
- `Expect(resp).To(HaveHTTPStatus("404 Not Found"))`:
asserts that `resp.Status == "404 Not Found"`.
#### HaveHTTPBody(expected interface{})
```go
Expect(ACTUAL).To(HaveHTTPBody(EXPECTED))
```
Succeeds if the body of an HTTP Response matches.
`ACTUAL` must be either a `*http.Response` or `*httptest.ResponseRecorder`.
`EXPECTED` must be one of the following:
- A `string`
- A `[]byte`
- A matcher, in which case the matcher will be called with the body as a `[]byte`.
Here are some examples:
- `Expect(resp).To(HaveHTTPBody("bar"))`:
asserts that when `resp.Body` is read, it will equal `bar`.
- `Expect(resp).To(HaveHTTPBody(MatchJSON("{\"some\":\"json\""))`:
asserts that when `resp.Body` is read, the `MatchJSON` matches it to `{"some":"json"}`.
Note that the body is an `io.ReadCloser` and the `HaveHTTPBody()` will read it and the close it.
This means that subsequent attempts to read the body may have unexpected results.
#### HaveHTTPHeaderWithValue(key string, value interface{})
```go
Expect(ACTUAL).To(HaveHTTPHeaderWithValue(KEY, VALUE))
```
Succeeds if the HTTP Response has a matching header and value.
`ACTUAL` must be either a `*http.Response` or `*httptest.ResponseRecorder`.
`KEY` must be a `string`. It is passed to
[`http.Header.Get(key string)`](https://pkg.go.dev/net/http#Header.Get),
and will have the same behaviors regarding order of headers and capitalization.
`VALUE` must be one of the following:
- A `string`
- A matcher, in which case the matcher will be called to match the value.
Here are some examples:
- `Expect(resp).To(HaveHTTPHeaderWithValue("Content-Type", "application/json"))`:
asserts that the `Content-Type` header has exactly the value `application/json`.
- `Expect(resp).To(HaveHTTPHeaderWithValue(ContainSubstring("json")))`:
asserts that the `Content-Type` header contains the substring `json`.
### Asserting on Panics
#### Panic()
```go
Ω(ACTUAL).Should(Panic())
```
succeeds if `ACTUAL` is a function that, when invoked, panics. `ACTUAL` must be a function that takes no arguments and returns no result -- any other type for `ACTUAL` is an error.
#### PanicWith()
```go
Ω(ACTUAL).Should(PanicWith(VALUE))
```
succeeds if `ACTUAL` is a function that, when invoked, panics with a value of `VALUE`. `ACTUAL` must be a function that takes no arguments and returns no result -- any other type for `ACTUAL` is an error.
By default `PanicWith()` uses the `Equal()` matcher under the hood to assert equality between `ACTUAL`'s panic value and `VALUE`. You can change this, however, by passing `PanicWith` a `GomegaMatcher`. For example, to check that the panic value matches a regular expression:
```go
Ω(func() { panic("FooBarBaz") }).Should(PanicWith(MatchRegexp(`.+Baz$`)))
```
### Composing Matchers
You may form larger matcher expressions using the following operators: `And()`, `Or()`, `Not()` and `WithTransform()`.
Note: `And()` and `Or()` can also be referred to as `SatisfyAll()` and `SatisfyAny()`, respectively.
With these operators you can express multiple requirements in a single `Expect()` or `Eventually()` statement. For example:
```go
Expect(number).To(SatisfyAll(
BeNumerically(">", 0),
BeNumerically("<", 10)))
Expect(msg).To(SatisfyAny(
Equal("Success"),
MatchRegexp(`^Error .+$`)))
```
It can also provide a lightweight syntax to create new matcher types from existing ones. For example:
```go
func BeBetween(min, max int) GomegaMatcher {
return SatisfyAll(
BeNumerically(">", min),
BeNumerically("<", max))
}
Ω(number).Should(BeBetween(0, 10))
```
#### And(matchers ...GomegaMatcher)
#### SatisfyAll(matchers ...GomegaMatcher)
```go
Ω(ACTUAL).Should(And(MATCHER1, MATCHER2, ...))
```
or
```go
Ω(ACTUAL).Should(SatisfyAll(MATCHER1, MATCHER2, ...))
```
succeeds if `ACTUAL` satisfies all of the specified matchers (similar to a logical AND).
Tests the given matchers in order, returning immediately if one fails, without needing to test the remaining matchers.
#### Or(matchers ...GomegaMatcher)
#### SatisfyAny(matchers ...GomegaMatcher)
```go
Ω(ACTUAL).Should(Or(MATCHER1, MATCHER2, ...))
```
or
```go
Ω(ACTUAL).Should(SatisfyAny(MATCHER1, MATCHER2, ...))
```
succeeds if `ACTUAL` satisfies any of the specified matchers (similar to a logical OR).
Tests the given matchers in order, returning immediately if one succeeds, without needing to test the remaining matchers.
#### Not(matcher GomegaMatcher)
```go
Ω(ACTUAL).Should(Not(MATCHER))
```
succeeds if `ACTUAL` does **not** satisfy the specified matcher (similar to a logical NOT).
#### WithTransform(transform interface{}, matcher GomegaMatcher)
```go
Ω(ACTUAL).Should(WithTransform(TRANSFORM, MATCHER))
```
succeeds if applying the `TRANSFORM` function to `ACTUAL` (i.e. the value of `TRANSFORM(ACTUAL)`) will satisfy the given `MATCHER`. For example:
```go
GetColor := func(e Element) Color { return e.Color }
Ω(element).Should(WithTransform(GetColor, Equal(BLUE)))
```
Or the same thing expressed by introducing a new, lightweight matcher:
```go
// HaveColor returns a matcher that expects the element to have the given color.
func HaveColor(c Color) GomegaMatcher {
return WithTransform(func(e Element) Color {
return e.Color
}, Equal(c))
}
Ω(element).Should(HaveColor(BLUE)))
```
`TRANSFORM` functions optionally can return an additional error value in case a transformation is not possible, avoiding the need to `panic`. Returning errors can be useful when using `WithTransform` to build lightweight matchers that accept different value types and that can gracefully fail when presented the wrong value type.
As before, such a `TRANSFORM` expects a single actual value. But now it returns the transformed value together with an error value. This follows the common Go idiom to communicate errors via an explicit, separate return value.
The following lightweight matcher expects to be used either on a `Sprocket` value or `*Sprocket` pointer. It gracefully fails when the actual value is something else.
```go
// HaveSprocketName returns a matcher that expects the actual value to be
// either a Sprocket or a *Sprocket, having the specified name.
func HaveSprocketName(name string) GomegaMatcher {
return WithTransform(
func(actual interface{}) (string, error) {
switch sprocket := actual.(type) {
case *Sprocket:
return Sprocket.Name, nil
case Sprocket:
return Sprocket.Name, nil
default:
return "", fmt.Errorf("HaveSprocketName expects a Sprocket or *Sprocket, but got %T", actual)
}
}, Equal(name))
}
Ω(element).Should(HaveSprocketName("gomega")))
```
#### Satisfy(predicate interface{})
```go
Ω(ACTUAL).Should(Satisfy(PREDICATE))
```
succeeds if applying the `PREDICATE` function to `ACTUAL` (i.e. the value of `PREDICATE(ACTUAL)`) will return `true`. For example:
```go
IsEven := func(i int) bool { return i%2==0 }
Ω(number).Should(Satisfy(IsEven))
```
## Adding Your Own Matchers
A matcher, in Gomega, is any type that satisfies the `GomegaMatcher` interface:
```go
type GomegaMatcher interface {
Match(actual interface{}) (success bool, err error)
FailureMessage(actual interface{}) (message string)
NegatedFailureMessage(actual interface{}) (message string)
}
```
For the simplest cases, new matchers can be [created by composition](#composing-matchers). Please also take a look at the [Building Custom Matchers](https://onsi.github.io/ginkgo/#building-custom-matchers) section of the Ginkgo and Gomega patterns chapter in the Ginkgo docs for additional examples.
In addition to composition, however, it is fairly straightforward to build domain-specific custom matchers. You can create new types that satisfy the `GomegaMatcher` interface *or* you can use the `gcustom` package to build matchers out of simple functions.
Let's work through an example and illustrate both approaches.
### A Custom Matcher: RepresentJSONifiedObject(EXPECTED interface{})
Say you're working on a JSON API and you want to assert that your server returns the correct JSON representation. Rather than marshal/unmarshal JSON in your tests, you want to write an expressive matcher that checks that the received response is a JSON representation for the object in question. This is what the `RepresentJSONifiedObject` matcher could look like:
```go
package json_response_matcher
import (
"github.com/onsi/gomega/types"
"encoding/json"
"fmt"
"net/http"
"reflect"
)
func RepresentJSONifiedObject(expected interface{}) types.GomegaMatcher {
return &representJSONMatcher{
expected: expected,
}
}
type representJSONMatcher struct {
expected interface{}
}
func (matcher *representJSONMatcher) Match(actual interface{}) (success bool, err error) {
response, ok := actual.(*http.Response)
if !ok {
return false, fmt.Errorf("RepresentJSONifiedObject matcher expects an http.Response")
}
pointerToObjectOfExpectedType := reflect.New(reflect.TypeOf(matcher.expected)).Interface()
err = json.NewDecoder(response.Body).Decode(pointerToObjectOfExpectedType)
if err != nil {
return false, fmt.Errorf("Failed to decode JSON: %s", err.Error())
}
decodedObject := reflect.ValueOf(pointerToObjectOfExpectedType).Elem().Interface()
return reflect.DeepEqual(decodedObject, matcher.expected), nil
}
func (matcher *representJSONMatcher) FailureMessage(actual interface{}) (message string) {
return fmt.Sprintf("Expected\n\t%#v\nto contain the JSON representation of\n\t%#v", actual, matcher.expected)
}
func (matcher *representJSONMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return fmt.Sprintf("Expected\n\t%#v\nnot to contain the JSON representation of\n\t%#v", actual, matcher.expected)
}
```
Let's break this down:
- Most matchers have a constructor function that returns an instance of the matcher. In this case we've created `RepresentJSONifiedObject`. Where possible, your constructor function should take explicit types or interfaces. For our use case, however, we need to accept any possible expected type so `RepresentJSONifiedObject` takes an argument with the generic `interface{}` type.
- The constructor function then initializes and returns an instance of our matcher: the `representJSONMatcher`. These rarely need to be exported outside of your matcher package.
- The `representJSONMatcher` must satisfy the `GomegaMatcher` interface. It does this by implementing the `Match`, `FailureMessage`, and `NegatedFailureMessage` method:
- If the `GomegaMatcher` receives invalid inputs `Match` returns a non-nil error explaining the problems with the input. This allows Gomega to fail the assertion whether the assertion is for the positive or negative case.
- If the `actual` and `expected` values match, `Match` should return `true`.
- Similarly, if the `actual` and `expected` values do not match, `Match` should return `false`.
- If the `GomegaMatcher` was testing the `Should` case, and `Match` returned `false`, `FailureMessage` will be called to print a message explaining the failure.
- Likewise, if the `GomegaMatcher` was testing the `ShouldNot` case, and `Match` returned `true`, `NegatedFailureMessage` will be called.
- It is guaranteed that `FailureMessage` and `NegatedFailureMessage` will only be called *after* `Match`, so you can save off any state you need to compute the messages in `Match`.
- Finally, it is common for matchers to make extensive use of the `reflect` library to interpret the generic inputs they receive. In this case, the `representJSONMatcher` goes through some `reflect` gymnastics to create a pointer to a new object with the same type as the `expected` object, read and decode JSON from `actual` into that pointer, and then deference the pointer and compare the result to the `expected` object.
### gcustom: A convenient mechanism for building custom matchers
[`gcustom`](https://github.com/onsi/gomega/tree/master/gcustom) is a package that makes building custom matchers easy. Rather than define new types, you can simply provide `gcustom.MakeMatcher` with a function. The [godocs](https://pkg.go.dev/github.com/onsi/gomega/gcustom) for `gcustom` have all the details but here's how `RepresentJSONifiedObject` could be implemented with `gcustom`:
```go
package json_response_matcher
import (
"github.com/onsi/gomega/types"
"github.com/onsi/gomega/gcustom"
"encoding/json"
"fmt"
"net/http"
"reflect"
)
func RepresentJSONifiedObject(expected interface{}) types.GomegaMatcher {
return gcustom.MakeMatcher(func(response *http.Response) (bool, err) {
pointerToObjectOfExpectedType := reflect.New(reflect.TypeOf(matcher.expected)).Interface()
err = json.NewDecoder(response.Body).Decode(pointerToObjectOfExpectedType)
if err != nil {
return false, fmt.Errorf("Failed to decode JSON: %w", err.Error())
}
decodedObject := reflect.ValueOf(pointerToObjectOfExpectedType).Elem().Interface()
return reflect.DeepEqual(decodedObject, matcher.expected), nil
}).WithTemplate("Expected:\n{{.FormattedActual}}\n{{.To}} contain the JSON representation of\n{{format .Data 1}}").WithTemplateData(expected)
}
```
The [`gcustom` godocs](https://pkg.go.dev/github.com/onsi/gomega/gcustom) go into much more detail but we can point out a few of the convenient features of `gcustom` here:
- `gcustom` can take a matcher function that accepts a concrete type. In our case `func(response *https.Response) (bool, err)` - when this is done, the matcher built by `gcustom` takes care of all the type-checking for you and will only call your match function if an object of the correct type is asserted against. If you want to do your own type-checking (or want to build a matcher that works with multiple types) you can use `func(actual any) (bool, err)` instead.
- Rather than implement different functions for the two different failure messages you can provide a single template. `gcustom` provides template variables to help you render the failure messages depending on positive failures vs negative failures. For example, the variable `{{.To}}` will render "to" for positive failures and "not to" for negative failures.
- You can pass additional data to your template with `WithTemplateData()` - in this case we pass in the expected object so that the template can include it in the output. We do this with the expression `{{format .Data 1}}`. gcustom provides the `format` template function to render objects using Ginkgo's object formatting system (the `1` here denotes the level of indentation).
`gcustom` also supports a simpler mechanism for generating messages: `.WithMessage()` simply takes a string and builds a canned message out of that string. You can also provide precompiled templates if you want to avoid the cost of compiling a template every time the matcher is called.
### Testing Custom Matchers
Whether you create a new `representJSONMatcher` type, or use `gcustom` you might test drive this matcher while writing it using Ginkgo. Your test might look like:
```go
package json_response_matcher_test
import (
. "github.com/onsi/ginkgo"
. "github.com/onsi/gomega"
. "jsonresponsematcher"
"bytes"
"encoding/json"
"io/ioutil"
"net/http"
"strings"
"testing"
)
func TestCustomMatcher(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Custom Matcher Suite")
}
type Book struct {
Title string `json:"title"`
Author string `json:"author"`
}
var _ = Describe("RepresentJSONified Object", func() {
var (
book Book
bookJSON []byte
response *http.Response
)
BeforeEach(func() {
book = Book{
Title: "Les Miserables",
Author: "Victor Hugo",
}
var err error
bookJSON, err = json.Marshal(book)
Ω(err).ShouldNot(HaveOccurred())
})
Context("when actual is not an http response", func() {
It("should error", func() {
_, err := RepresentJSONifiedObject(book).Match("not a response")
Ω(err).Should(HaveOccurred())
})
})
Context("when actual is an http response", func() {
BeforeEach(func() {
response = &http.Response{}
})
Context("with a body containing the JSON representation of actual", func() {
BeforeEach(func() {
response.ContentLength = int64(len(bookJSON))
response.Body = ioutil.NopCloser(bytes.NewBuffer(bookJSON))
})
It("should succeed", func() {
Ω(response).Should(RepresentJSONifiedObject(book))
})
})
Context("with a body containing the JSON representation of something else", func() {
BeforeEach(func() {
reader := strings.NewReader(`{}`)
response.ContentLength = int64(reader.Len())
response.Body = ioutil.NopCloser(reader)
})
It("should fail", func() {
Ω(response).ShouldNot(RepresentJSONifiedObject(book))
})
})
Context("with a body containing invalid JSON", func() {
BeforeEach(func() {
reader := strings.NewReader(`floop`)
response.ContentLength = int64(reader.Len())
response.Body = ioutil.NopCloser(reader)
})
It("should error", func() {
_, err := RepresentJSONifiedObject(book).Match(response)
Ω(err).Should(HaveOccurred())
})
})
})
})
```
This also offers an example of what using the matcher would look like in your tests. Note that testing the cases when the matcher returns an error involves creating the matcher and invoking `Match` manually (instead of using an `Ω` or `Expect` assertion).
### Aborting Eventually/Consistently
**Note: This section documents the `MatchMayChangeInTheFuture` method for aborting `Eventually`/`Consistently`. A more up-to-date approach that uses the `StopTrying` error is documented [earlier](#bailing-out-early--matchers).**
There are sometimes instances where `Eventually` or `Consistently` should stop polling a matcher because the result of the match simply cannot change.
For example, consider a test that looks like:
```go
Eventually(myChannel).Should(Receive(Equal("bar")))
```
`Eventually` will repeatedly invoke the `Receive` matcher against `myChannel` until the match succeeds. However, if the channel becomes *closed* there is *no way* for the match to ever succeed. Allowing `Eventually` to continue polling is inefficient and slows the test suite down.
To get around this, a matcher can optionally implement:
```go
MatchMayChangeInTheFuture(actual interface{}) bool
```
This is not part of the `GomegaMatcher` interface and, in general, most matchers do not need to implement `MatchMayChangeInTheFuture`.
If implemented, however, `MatchMayChangeInTheFuture` will be called with the appropriate `actual` value by `Eventually` and `Consistently` *after* the call to `Match` during every polling interval. If `MatchMayChangeInTheFuture` returns `true`, `Eventually` and `Consistently` will continue polling. If, however, `MatchMayChangeInTheFuture` returns `false`, `Eventually` and `Consistently` will stop polling and either fail or pass as appropriate.
If you'd like to look at a simple example of `MatchMayChangeInTheFuture` check out [`gexec`'s `Exit` matcher](https://github.com/onsi/gomega/tree/master/gexec/exit_matcher.go). Here, `MatchMayChangeInTheFuture` returns true if the `gexec.Session` under test has not exited yet, but returns false if it has. Because of this, if a process exits with status code 3, but an assertion is made of the form:
```go
Eventually(session, 30).Should(gexec.Exit(0))
```
`Eventually` will not block for 30 seconds but will return (and fail, correctly) as soon as the mismatched exit code arrives!
> Note: `Eventually` and `Consistently` only exercise the `MatchMayChangeInTheFuture` method *if* they are passed a bare value. If they are passed functions to be polled it is not possible to guarantee that the return value of the function will not change between polling intervals. In this case, `MatchMayChangeInTheFuture` is not called and the polling continues until either a match is found or the timeout elapses.
### Contributing to Gomega
Contributions are more than welcome. Either [open an issue](http://github.com/onsi/gomega/issues) for a matcher you'd like to see or, better yet, test drive the matcher and [send a pull request](https://github.com/onsi/gomega/pulls).
When adding a new matcher please mimic the style use in Gomega's current matchers: you should use the `format` package to format your output, put the matcher and its tests in the `matchers` package, and the constructor in the `matchers.go` file in the top-level package.
## Extending Gomega
The default Gomega can be wrapped by replacing it with an object that implements both the `gomega.Gomega` interface and the `inner` interface:
```go
type inner interface {
Inner() Gomega
}
```
The `Inner()` method must return the actual `gomega.Default`. For Gomega to function properly your wrapper methods must call the same method on the real `gomega.Default` This allows you to wrap every Gomega method call (e.g. `Expect()`) with your own code across your test suite. You can use this to add random delays, additional logging, or just for tracking the number of `Expect()` calls made.
```go
func init() {
gomega.Default = &gomegaWrapper{
inner: gomega.Default,
}
}
type gomegaWrapper struct {
inner gomega.Gomega
}
func (g *gomegaWrapper) Inner() gomega.Gomega {
return g.inner
}
func (g *gomegaWrapper) Ω(actual interface{}, extra ...interface{}) types.Assertion {
// You now have an opportunity to add a random delay to help identify any timing
// dependencies in your tests or can add additional logging.
return g.inner.Ω(actual, extra...)
}
...
```
## `ghttp`: Testing HTTP Clients
The `ghttp` package provides support for testing http *clients*. The typical pattern in Go for testing http clients entails spinning up an `httptest.Server` using the `net/http/httptest` package and attaching test-specific handlers that perform assertions.
`ghttp` provides `ghttp.Server` - a wrapper around `httptest.Server` that allows you to easily build up a stack of test handlers. These handlers make assertions against the incoming request and return a pre-fabricated response. `ghttp` provides a number of prebuilt handlers that cover the most common assertions. You can combine these handlers to build out full-fledged assertions that test multiple aspects of the incoming requests.
The goal of this documentation is to provide you with an adequate mental model to use `ghttp` correctly. For a full reference of all the available handlers and the various methods on `ghttp.Server` look at the [godoc](https://godoc.org/github.com/onsi/gomega/ghttp) documentation.
### Making assertions against an incoming request
Let's start with a simple example. Say you are building an API client that provides a `FetchSprockets(category string)` method that makes an http request to a remote server to fetch sprockets of a given category.
For now, let's not worry about the values returned by `FetchSprockets` but simply assert that the correct request was made. Here's the setup for our `ghttp`-based Ginkgo test:
```go
Describe("The sprockets client", func() {
var server *ghttp.Server
var client *sprockets.Client
BeforeEach(func() {
server = ghttp.NewServer()
client = sprockets.NewClient(server.URL())
})
AfterEach(func() {
//shut down the server between tests
server.Close()
})
})
```
Note that the server's URL is auto-generated and varies between test runs. Because of this, you must always inject the server URL into your client. Let's add a simple test that asserts that `FetchSprockets` hits the correct endpoint with the correct HTTP verb:
```go
Describe("The sprockets client", func() {
//...see above
Describe("fetching sprockets", func() {
BeforeEach(func() {
server.AppendHandlers(
ghttp.VerifyRequest("GET", "/sprockets"),
)
})
It("should make a request to fetch sprockets", func() {
client.FetchSprockets("")
Ω(server.ReceivedRequests()).Should(HaveLen(1))
})
})
})
```
Here we append a `VerifyRequest` handler to the `server` and call `client.FetchSprockets`. This call (assuming it's a blocking call) will make a round-trip to the test `server` before returning. The test `server` receives the request and passes it through the `VerifyRequest` handler which will validate that the request is a `GET` request hitting the `/sprockets` endpoint. If it's not, the test will fail.
Note that the test can pass trivially if `client.FetchSprockets()` doesn't actually make a request. To guard against this you can assert that the `server` has actually received a request. All the requests received by the server are saved off and made available via `server.ReceivedRequests()`. We use this to assert that there should have been exactly one received requests.
> Guarding against the trivial "false positive" case outlined above isn't really necessary. Just good practice when test *driving*.
Let's add some more to our example. Let's make an assertion that `FetchSprockets` can request sprockets filtered by a particular category:
```go
Describe("The sprockets client", func() {
//...see above
Describe("fetching sprockets", func() {
BeforeEach(func() {
server.AppendHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
)
})
It("should make a request to fetch sprockets", func() {
client.FetchSprockets("encabulators")
Ω(server.ReceivedRequests()).Should(HaveLen(1))
})
})
})
```
`ghttp.VerifyRequest` takes an optional third parameter that is matched against the request `URL`'s `RawQuery`.
Let's extend the example some more. In addition to asserting that the request is a `GET` request to the correct endpoint with the correct query params, let's also assert that it includes the correct `BasicAuth` information and a correct custom header. Here's the complete example:
```go
Describe("The sprockets client", func() {
var (
server *ghttp.Server
client *sprockets.Client
username, password string
)
BeforeEach(func() {
username, password = "gopher", "tacoshell"
server = ghttp.NewServer()
client = sprockets.NewClient(server.URL(), username, password)
})
AfterEach(func() {
server.Close()
})
Describe("fetching sprockets", func() {
BeforeEach(func() {
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
ghttp.VerifyBasicAuth(username, password),
ghttp.VerifyHeader(http.Header{
"X-Sprocket-API-Version": []string{"1.0"},
}),
)
)
})
It("should make a request to fetch sprockets", func() {
client.FetchSprockets("encabulators")
Ω(server.ReceivedRequests()).Should(HaveLen(1))
})
})
})
```
This example *combines* multiple `ghttp` verify handlers using `ghttp.CombineHandlers`. Under the hood, this returns a new handler that wraps and invokes the three passed in verify handlers. The request sent by the client will pass through each of these verify handlers and must pass them all for the test to pass.
Note that you can easily add your own verify handler into the mix. Just pass in a regular `http.HandlerFunc` and make assertions against the received request.
> It's important to understand that you must pass `AppendHandlers` **one** handler *per* incoming request (see [below](#handling-multiple-requests)). In order to apply multiple handlers to a single request we must first combine them with `ghttp.CombineHandlers` and then pass that *one* wrapper handler in to `AppendHandlers`.
### Providing responses
So far, we've only made assertions about the outgoing request. Clients are also responsible for parsing responses and returning valid data. Let's say that `FetchSprockets()` returns two things: a slice `[]Sprocket` and an `error`. Here's what a happy path test that asserts the correct data is returned might look like:
```go
Describe("The sprockets client", func() {
//...
Describe("fetching sprockets", func() {
BeforeEach(func() {
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
ghttp.VerifyBasicAuth(username, password),
ghttp.VerifyHeader(http.Header{
"X-Sprocket-API-Version": []string{"1.0"},
}),
ghttp.RespondWith(http.StatusOK, `[
{"name": "entropic decoupler", "color": "red"},
{"name": "defragmenting ramjet", "color": "yellow"}
]`),
)
)
})
It("should make a request to fetch sprockets", func() {
sprockets, err := client.FetchSprockets("encabulators")
Ω(err).ShouldNot(HaveOccurred())
Ω(sprockets).Should(Equal([]Sprocket{
sprockets.Sprocket{Name: "entropic decoupler", Color: "red"},
sprockets.Sprocket{Name: "defragmenting ramjet", Color: "yellow"},
}))
})
})
})
```
We use `ghttp.RespondWith` to specify the response return by the server. In this case we're passing back a status code of `200` (`http.StatusOK`) and a pile of JSON. We then assert, in the test, that the client succeeds and returns the correct set of sprockets.
The fact that details of the JSON encoding are bleeding into this test is somewhat unfortunate, and there's a lot of repetition going on. `ghttp` provides a `RespondWithJSONEncoded` handler that accepts an arbitrary object and JSON encodes it for you. Here's a cleaner test:
```go
Describe("The sprockets client", func() {
//...
Describe("fetching sprockets", func() {
var returnedSprockets []Sprocket
BeforeEach(func() {
returnedSprockets = []Sprocket{
sprockets.Sprocket{Name: "entropic decoupler", Color: "red"},
sprockets.Sprocket{Name: "defragmenting ramjet", Color: "yellow"},
}
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
ghttp.VerifyBasicAuth(username, password),
ghttp.VerifyHeader(http.Header{
"X-Sprocket-API-Version": []string{"1.0"},
}),
ghttp.RespondWithJSONEncoded(http.StatusOK, returnedSprockets),
)
)
})
It("should make a request to fetch sprockets", func() {
sprockets, err := client.FetchSprockets("encabulators")
Ω(err).ShouldNot(HaveOccurred())
Ω(sprockets).Should(Equal(returnedSprockets))
})
})
})
```
### Testing different response scenarios
Our test currently only handles the happy path where the server returns a `200`. We should also test a handful of sad paths. In particular, we'd like to return a `SprocketsErrorNotFound` error when the server `404`s and a `SprocketsErrorUnauthorized` error when the server returns a `401`. But how to do this without redefining our server handler three times?
`ghttp` provides `RespondWithPtr` and `RespondWithJSONEncodedPtr` for just this use case. Both take *pointers* to status codes and respond bodies (objects for the `JSON` case). Here's the more complete test:
```go
Describe("The sprockets client", func() {
//...
Describe("fetching sprockets", func() {
var returnedSprockets []Sprocket
var statusCode int
BeforeEach(func() {
returnedSprockets = []Sprocket{
sprockets.Sprocket{Name: "entropic decoupler", Color: "red"},
sprockets.Sprocket{Name: "defragmenting ramjet", Color: "yellow"},
}
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
ghttp.VerifyBasicAuth(username, password),
ghttp.VerifyHeader(http.Header{
"X-Sprocket-API-Version": []string{"1.0"},
}),
ghttp.RespondWithJSONEncodedPtr(&statusCode, &returnedSprockets),
)
)
})
Context("when the request succeeds", func() {
BeforeEach(func() {
statusCode = http.StatusOK
})
It("should return the fetched sprockets without erroring", func() {
sprockets, err := client.FetchSprockets("encabulators")
Ω(err).ShouldNot(HaveOccurred())
Ω(sprockets).Should(Equal(returnedSprockets))
})
})
Context("when the response is unauthorized", func() {
BeforeEach(func() {
statusCode = http.StatusUnauthorized
})
It("should return the SprocketsErrorUnauthorized error", func() {
sprockets, err := client.FetchSprockets("encabulators")
Ω(sprockets).Should(BeEmpty())
Ω(err).Should(MatchError(SprocketsErrorUnauthorized))
})
})
Context("when the response is not found", func() {
BeforeEach(func() {
statusCode = http.StatusNotFound
})
It("should return the SprocketsErrorNotFound error", func() {
sprockets, err := client.FetchSprockets("encabulators")
Ω(sprockets).Should(BeEmpty())
Ω(err).Should(MatchError(SprocketsErrorNotFound))
})
})
})
})
```
In this way, the status code and returned value (not shown here) can be changed in sub-contexts without having to modify the original test setup.
### Handling multiple requests
So far, we've only seen examples where one request is made per test. `ghttp` supports handling *multiple* requests too. `server.AppendHandlers` can be passed multiple handlers and these handlers are evaluated in order as requests come in.
This can be helpful in cases where it is not possible (or desirable) to have calls to the client under test only generate *one* request. A common example is pagination. If the sprockets API is paginated it may be desirable for `FetchSprockets` to provide a simpler interface that simply fetches all available sprockets.
Here's what a test might look like:
```go
Describe("fetching sprockets from a paginated endpoint", func() {
var returnedSprockets []Sprocket
var firstResponse, secondResponse PaginatedResponse
BeforeEach(func() {
returnedSprockets = []Sprocket{
sprockets.Sprocket{Name: "entropic decoupler", Color: "red"},
sprockets.Sprocket{Name: "defragmenting ramjet", Color: "yellow"},
sprockets.Sprocket{Name: "parametric demuxer", Color: "blue"},
}
firstResponse = sprockets.PaginatedResponse{
Sprockets: returnedSprockets[0:2], //first batch
PaginationToken: "get-second-batch", //some opaque non-empty token
}
secondResponse = sprockets.PaginatedResponse{
Sprockets: returnedSprockets[2:], //second batch
PaginationToken: "", //signifies the last batch
}
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
ghttp.RespondWithJSONEncoded(http.StatusOK, firstResponse),
),
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators&pagination-token=get-second-batch"),
ghttp.RespondWithJSONEncoded(http.StatusOK, secondResponse),
),
)
})
It("should fetch all the sprockets", func() {
sprockets, err := client.FetchSprockets("encabulators")
Ω(err).ShouldNot(HaveOccurred())
Ω(sprockets).Should(Equal(returnedSprockets))
})
})
```
By default the `ghttp` server fails the test if the number of requests received exceeds the number of handlers registered, so this test ensures that the `client` stops sending requests after receiving the second (and final) set of paginated data.
### MUXing Routes to Handlers
`AppendHandlers` allows you to make ordered assertions about incoming requests. This places a strong constraint on all incoming requests: namely that exactly the right requests have to arrive in exactly the right order and that no additional requests are allowed.
One can take a different testing strategy, however. Instead of asserting that requests come in in a predefined order, you may which to build a test server that can handle arbitrarily many requests to a set of predefined routes. In fact, there may be some circumstances where you want to make ordered assertions on *some* requests (via `AppendHandlers`) but still support sending particular responses to *other* requests that may interleave the ordered assertions.
`ghttp` supports these sorts of usecases via `server.RouteToHandler(method, path, handler)`.
Let's cook up an example. Perhaps, instead of authenticating via basic auth our sprockets client logs in and fetches a token from the server when performing requests that require authentication. We could pepper our `AppendHandlers` calls with a handler that handles these requests (this is not a terrible idea, of course!) *or* we could set up a single route at the top of our tests.
Here's what such a test might look like:
```go
Describe("CRUDing sprockes", func() {
BeforeEach(func() {
server.RouteToHandler("POST", "/login", ghttp.CombineHandlers(
ghttp.VerifyRequest("POST", "/login", "user=bob&password=password"),
ghttp.RespondWith(http.StatusOK, "your-auth-token"),
))
})
Context("GETting sprockets", func() {
var returnedSprockets []Sprocket
BeforeEach(func() {
returnedSprockets = []Sprocket{
sprockets.Sprocket{Name: "entropic decoupler", Color: "red"},
sprockets.Sprocket{Name: "defragmenting ramjet", Color: "yellow"},
sprockets.Sprocket{Name: "parametric demuxer", Color: "blue"},
}
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets", "category=encabulators"),
ghttp.RespondWithJSONEncoded(http.StatusOK, returnedSprockets),
),
)
})
It("should fetch all the sprockets", func() {
sprockets, err := client.FetchSprockes("encabulators")
Ω(err).ShouldNot(HaveOccurred())
Ω(sprockets).Should(Equal(returnedSprockets))
})
})
Context("POSTing sprockets", func() {
var sprocketToSave Sprocket
BeforeEach(func() {
sprocketToSave = sprockets.Sprocket{Name: "endothermic penambulator", Color: "purple"}
server.AppendHandlers(
ghttp.CombineHandlers(
ghttp.VerifyRequest("POST", "/sprocket", "token=your-auth-token"),
ghttp.VerifyJSONRepresenting(sprocketToSave)
ghttp.RespondWithJSONEncoded(http.StatusOK, nil),
),
)
})
It("should save the sprocket", func() {
err := client.SaveSprocket(sprocketToSave)
Ω(err).ShouldNot(HaveOccurred())
})
})
})
```
Here, saving a sprocket triggers authentication, which is handled by the registered `RouteToHandler` handler whereas fetching the list of sprockets does not.
> `RouteToHandler` can take either a string as a route (as seen in this example) or a `regexp.Regexp`.
### Allowing unhandled requests
By default, `ghttp`'s server marks the test as failed if a request is made for which there is no registered handler.
It is sometimes useful to have a fake server that simply returns a fixed status code for all unhandled incoming requests. `ghttp` supports this: just call `server.SetAllowUnhandledRequests(true)` and `server.SetUnhandledRequestStatusCode(statusCode)`, passing whatever status code you'd like to return.
In addition to returning the registered status code, `ghttp`'s server will also save all received requests. These can be accessed by calling `server.ReceivedRequests()`. This is useful for cases where you may want to make assertions against requests *after* they've been made.
To bring it all together: there are three ways to instruct a `ghttp` server to handle requests: you can map routes to handlers using `RouteToHandler`, you can append handlers via `AppendHandlers`, and you can `SetAllowUnhandledRequests` and specify the status code by calling `SetUnhandledRequestStatusCode`.
When a `ghttp` server receives a request it first checks against the set of handlers registered via `RouteToHandler` if there is no such handler it proceeds to pop an `AppendHandlers` handler off the stack, if the stack of ordered handlers is empty, it will check whether `GetAllowUnhandledRequests` returns `true` or `false`. If `false` the test fails. If `true`, a response is sent with whatever `GetUnhandledRequestStatusCode` returns.
## `gbytes`: Testing Streaming Buffers
`gbytes` implements `gbytes.Buffer` - an `io.WriteCloser` that captures all input to an in-memory buffer.
When used in concert with the `gbytes.Say` matcher, the `gbytes.Buffer` allows you make *ordered* assertions against streaming data.
What follows is a contrived example. `gbytes` is best paired with [`gexec`](#gexec-testing-external-processes).
Say you have an integration test that is streaming output from an external API. You can feed this stream into a `gbytes.Buffer` and make ordered assertions like so:
```go
Describe("attach to the data stream", func() {
var (
client *apiclient.Client
buffer *gbytes.Buffer
)
BeforeEach(func() {
buffer = gbytes.NewBuffer()
client := apiclient.New()
go client.AttachToDataStream(buffer)
})
It("should stream data", func() {
Eventually(buffer).Should(gbytes.Say(`Attached to stream as client \d+`))
client.ReticulateSplines()
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
client.EncabulateRetros(7)
Eventually(buffer).Should(gbytes.Say(`encabulating 7 retros`))
})
})
```
These assertions will only pass if the strings passed to `Say` (which are interpreted as regular expressions - make sure to escape characters appropriately!) appear in the buffer. An opaque read cursor (that you cannot access or modify) is fast-forwarded as successful assertions are made. So, for example:
```go
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
Consistently(buffer).ShouldNot(gbytes.Say(`reticulating splines`))
```
will (counterintuitively) pass. This allows you to write tests like:
```go
client.ReticulateSplines()
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
client.ReticulateSplines()
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
```
and ensure that the test is correctly asserting that `reticulating splines` appears *twice*.
At any time, you can access the entire contents written to the buffer via `buffer.Contents()`. This includes *everything* ever written to the buffer regardless of the current position of the read cursor.
### Handling branches
Sometimes (rarely!) you must write a test that must perform different actions depending on the output streamed to the buffer. This can be accomplished using `buffer.Detect`. Here's a contrived example:
```go
func LoginIfNecessary() {
client.Authorize()
select {
case <-buffer.Detect("You are not logged in"):
client.Login()
case <-buffer.Detect("Success"):
return
case <-time.After(time.Second):
ginkgo.Fail("timed out waiting for output")
}
buffer.CancelDetects()
}
```
`buffer.Detect` takes a string (interpreted as a regular expression) and returns a channel that will fire *once* if the requested string is detected. Upon detection, the buffer's opaque read cursor is fast-forwarded so subsequent uses of `gbytes.Say` will pick up from where the succeeding `Detect` left off. You *must* call `buffer.CancelDetects()` to clean up afterwards (`buffer` spawns one goroutine per call to `Detect`).
### Testing `io.Reader`s, `io.Writer`s, and `io.Closer`s
Implementations of `io.Reader`, `io.Writer`, and `io.Closer` are expected to be blocking. This makes the following class of tests unsafe:
```go
It("should read something", func() {
p := make([]byte, 5)
_, err := reader.Read(p) //unsafe! this could block forever
Ω(err).ShouldNot(HaveOccurred())
Ω(p).Should(Equal([]byte("abcde")))
})
```
It is safer to wrap `io.Reader`s, `io.Writer`s, and `io.Closer`s with explicit timeouts. You can do this with `gbytes.TimeoutReader`, `gbytes.TimeoutWriter`, and `gbytes.TimeoutCloser` like so:
```go
It("should read something", func() {
p := make([]byte, 5)
_, err := gbytes.TimeoutReader(reader, time.Second).Read(p)
Ω(err).ShouldNot(HaveOccurred())
Ω(p).Should(Equal([]byte("abcde")))
})
```
The `gbytes` wrappers will return `gbytes.ErrTimeout` if a timeout occurs.
In the case of `io.Reader`s you can leverage the `Say` matcher and the functionality of `gbytes.Buffer` by building a `gbytes.Buffer` that reads from the `io.Reader` asynchronously. You can do this with the `gbytes` package like so:
```go
It("should read something", func() {
Eventually(gbytes.BufferReader(reader)).Should(gbytes.Say("abcde"))
})
```
`gbytes.BufferReader` takes an `io.Reader` and returns a `gbytes.Buffer`. Under the hood an `io.Copy` goroutine is launched to copy data from the `io.Reader` into the `gbytes.Buffer`. The `gbytes.Buffer` is closed when the `io.Copy` completes. Because the `io.Copy` is launched asynchronously you *must* make assertions against the reader using `Eventually`.
## `gexec`: Testing External Processes
`gexec` simplifies testing external processes. It can help you [compile go binaries](#compiling-external-binaries), [start external processes](#starting-external-processes), [send signals and wait for them to exit](#sending-signals-and-waiting-for-the-process-to-exit), make [assertions against the exit code](#asserting-against-exit-code), and stream output into `gbytes.Buffer`s to allow you [make assertions against output](#making-assertions-against-the-process-output).
### Compiling external binaries
You use `gexec.Build()` to compile Go binaries. These are built using `go build` and are stored off in a temporary directory. You'll want to `gexec.CleanupBuildArtifacts()` when you're done with the test.
A common pattern is to compile binaries once at the beginning of the test using `BeforeSuite` and to clean up once at the end of the test using `AfterSuite`:
```go
var pathToSprocketCLI string
BeforeSuite(func() {
var err error
pathToSprocketCLI, err = gexec.Build("github.com/spacely/sprockets")
Ω(err).ShouldNot(HaveOccurred())
})
AfterSuite(func() {
gexec.CleanupBuildArtifacts()
})
```
> By default, `gexec.Build` uses the GOPATH specified in your environment. You can also use `gexec.BuildIn(gopath string, packagePath string)` to specify a custom GOPATH for the build command. This is useful to, for example, build a binary against its vendored Go dependencies.
> You can specify arbitrary environment variables for the build command – such as GOOS and GOARCH for building on other platforms – using `gexec.BuildWithEnvironment(packagePath string, envs []string)`.
### Starting external processes
`gexec` provides a `Session` that wraps `exec.Cmd`. `Session` includes a number of features that will be explored in the next few sections. You create a `Session` by instructing `gexec` to start a command:
```go
command := exec.Command(pathToSprocketCLI, "-api=127.0.0.1:8899")
session, err := gexec.Start(command, GinkgoWriter, GinkgoWriter)
Ω(err).ShouldNot(HaveOccurred())
```
`gexec.Start` calls `command.Start` for you and forwards the command's `stdout` and `stderr` to `io.Writer`s that you provide. In the code above, we pass in Ginkgo's `GinkgoWriter`. This makes working with external processes quite convenient: when a test passes no output is printed to screen, however if a test fails then any output generated by the command will be provided.
> If you want to see all your output regardless of test status, just run `ginkgo` in verbose mode (`-v`) - now everything written to `GinkgoWriter` makes it onto the screen.
### Sending signals and waiting for the process to exit
`gexec.Session` makes it easy to send signals to your started command:
```go
session.Kill() //sends SIGKILL
session.Interrupt() //sends SIGINT
session.Terminate() //sends SIGTERM
session.Signal(signal) //sends the passed in os.Signal signal
```
If the process has already exited these signal calls are no-ops.
In addition to starting the wrapped command, `gexec.Session` also *monitors* the command until it exits. You can ask `gexec.Session` to `Wait` until the process exits:
```go
session.Wait()
```
this will block until the session exits and will *fail* if it does not exit within the default `Eventually` timeout. You can override this timeout by specifying a custom one:
```go
session.Wait(5 * time.Second)
```
> Though you can access the wrapped command using `session.Command` you should not attempt to `Wait` on it yourself. `gexec` has already called `Wait` in order to monitor your process for you.
> Under the hood `session.Wait` simply uses `Eventually`.
Since the signaling methods return the session you can chain calls together:
```go
session.Terminate().Wait()
```
will send `SIGTERM` and then wait for the process to exit.
### Asserting against exit code
Once a session has exited you can fetch its exit code with `session.ExitCode()`. You can subsequently make assertions against the exit code.
A more idiomatic way to assert that a command has exited is to use the `gexec.Exit()` matcher:
```go
Eventually(session).Should(Exit())
```
Will verify that the `session` exits within `Eventually`'s default timeout. You can assert that the process exits with a specified exit code too:
```go
Eventually(session).Should(Exit(0))
```
> If the process has not exited yet, `session.ExitCode()` returns `-1`
### Making assertions against the process output
In addition to streaming output to the passed in `io.Writer`s (the `GinkgoWriter` in our example above), `gexec.Start` attaches `gbytes.Buffer`s to the command's output streams. These are available on the `session` object via:
```go
session.Out //a gbytes.Buffer connected to the command's stdout
session.Err //a gbytes.Buffer connected to the command's stderr
```
This allows you to make assertions against the stream of output:
```go
Eventually(session.Out).Should(gbytes.Say("hello [A-Za-z], nice to meet you"))
Eventually(session.Err).Should(gbytes.Say("oops!"))
```
Since `gexec.Session` is a `gbytes.BufferProvider` that provides the `Out` buffer you can write assertions against `stdout` output like so:
```go
Eventually(session).Should(gbytes.Say("hello [A-Za-z], nice to meet you"))
```
Using the `Say` matcher is convenient when making *ordered* assertions against a stream of data generated by a live process. Sometimes, however, all you need is to
wait for the process to exit and then make assertions against the entire contents of its output. Since `Wait()` returns `session` you can wait for the process to exit, then grab all its stdout as a `[]byte` buffer with a simple one-liner:
```go
Ω(session.Wait().Out.Contents()).Should(ContainSubstring("finished successfully"))
```
### Signaling all processes
`gexec` provides methods to track and send signals to all processes that it starts.
```go
gexec.Kill() //sends SIGKILL to all processes
gexec.Terminate() //sends SIGTERM to all processes
gexec.Signal(int) //sends the passed in os.Signal signal to all the processes
gexec.Interrupt() //sends SIGINT to all processes
```
If the any of the processes have already exited these signal calls are no-ops.
`gexec` also provides methods to cleanup and wait for all the processes it started.
```go
gexec.KillAndWait()
gexec.TerminateAndWait()
```
You can specify a custom timeout by:
```go
gexec.KillAndWait(5 * time.Second)
gexec.TerminateAndWait(2 * time.Second)
```
The timeout is applied for each of the processes.
It is considered good practice to ensure all of your processes have been killed before the end of the test suite. If you are using `ginkgo` you can use:
```go
AfterSuite(func(){
gexec.KillAndWait()
})
```
Due to the global nature of these methods, keep in mind that signaling processes will affect all processes started by `gexec`, in any context. For example if these methods where used in an `AfterEach`, then processes started in `BeforeSuite` would also be signaled.
## `gstruct`: Testing Complex Data Types
`gstruct` simplifies testing large and nested structs and slices. It is used for building up complex matchers that apply different tests to each field or element.
### Testing type `struct`
`gstruct` provides the `FieldsMatcher` through the `MatchAllFields` and `MatchFields` functions for applying a separate matcher to each field of a struct:
```go
actual := struct{
A int
B bool
C string
}{5, true, "foo"}
Expect(actual).To(MatchAllFields(Fields{
"A": BeNumerically("<", 10),
"B": BeTrue(),
"C": Equal("foo"),
}))
```
`MatchAllFields` requires that every field is matched, and each matcher is mapped to a field. To match a subset or superset of a struct, you should use the `MatchFields` function with the `IgnoreExtras` and `IgnoreMissing` options. `IgnoreExtras` will ignore fields that don't map to a matcher, e.g.
```go
Expect(actual).To(MatchFields(IgnoreExtras, Fields{
"A": BeNumerically("<", 10),
"B": BeTrue(),
// Ignore lack of "C" in the matcher.
}))
```
`IgnoreMissing` will ignore matchers that don't map to a field, e.g.
```go
Expect(actual).To(MatchFields(IgnoreMissing, Fields{
"A": BeNumerically("<", 10),
"B": BeTrue(),
"C": Equal("foo"),
"D": Equal("bar"), // Ignored, since actual.D does not exist.
}))
```
The options can be combined with the binary or: `IgnoreMissing|IgnoreExtras`.
### Testing type slice
`gstruct` provides the `ElementsMatcher` through the `MatchAllElements` and `MatchElements` function for applying a separate matcher to each element, identified by an `Identifier` function:
```go
actual := []string{
"A: foo bar baz",
"B: once upon a time",
"C: the end",
}
id := func(element interface{}) string {
return string(element.(string)[0])
}
Expect(actual).To(MatchAllElements(id, Elements{
"A": Not(BeZero()),
"B": MatchRegexp("[A-Z]: [a-z ]+"),
"C": ContainSubstring("end"),
}))
```
`MatchAllElements` requires that there is a 1:1 mapping from every element to every matcher. To match a subset or superset of elements, you should use the `MatchElements` function with the `IgnoreExtras` and `IgnoreMissing` options. `IgnoreExtras` will ignore elements that don't map to a matcher, e.g.
```go
Expect(actual).To(MatchElements(id, IgnoreExtras, Elements{
"A": Not(BeZero()),
"B": MatchRegexp("[A-Z]: [a-z ]+"),
// Ignore lack of "C" in the matcher.
}))
```
`IgnoreMissing` will ignore matchers that don't map to an element, e.g.
```go
Expect(actual).To(MatchElements(id, IgnoreMissing, Elements{
"A": Not(BeZero()),
"B": MatchRegexp("[A-Z]: [a-z ]+"),
"C": ContainSubstring("end"),
"D": Equal("bar"), // Ignored, since actual.D does not exist.
}))
```
You can also use the flag `AllowDuplicates` to permit multiple elements in your slice to map to a single key and matcher in your fields (this flag is not meaningful when applied to structs).
```go
everyElementID := func(element interface{}) string {
return "a constant" // Every element will map to the same key in this case; you can group them into multiple keys, however.
}
Expect(actual).To(MatchElements(everyElementID, AllowDuplicates, Elements{
"a constant": ContainSubstring(": "), // Because every element passes this test
}))
Expect(actual).NotTo(MatchElements(everyElementID, AllowDuplicates, Elements{
"a constant": ContainSubstring("foo bar baz"), // Only the first element passes this test
}))
```
The options can be combined with the binary or: `IgnoreMissing|IgnoreExtras|AllowDuplicates`.
Additionally, `gstruct` provides `MatchAllElementsWithIndex` and `MatchElementsWithIndex` function for applying a matcher with index to each element, identified by an `IdentifierWithIndex` function. A helper function is also included with `gstruct` called `IndexIdentity` that provides the functionality of the just using the index as your identifier as seen below.
```go
actual := []string{
"A: foo bar baz",
"B: once upon a time",
"C: the end",
}
id := func(index int, _ interface{}) string {
return strconv.Itoa(index)
}
Expect(actual).To(MatchAllElementsWithIndex(id, Elements{
"0": Not(BeZero()),
"1": MatchRegexp("[A-Z]: [a-z ]+"),
"2": ContainSubstring("end"),
}))
// IndexIdentity is a helper function equivalent to id in this example
Expect(actual).To(MatchAllElementsWithIndex(IndexIdentity, Elements{
"0": Not(BeZero()),
"1": MatchRegexp("[A-Z]: [a-z ]+"),
"2": ContainSubstring("end"),
}))
```
The `WithIndex` variants take the same options as the other functions.
### Testing type `map`
All of the `*Fields` functions and types have a corresponding definitions `*Keys` which can perform analogous tests against map types:
```go
actual := map[string]string{
"A": "correct",
"B": "incorrect",
}
// fails, because `actual` includes the key B
Expect(actual).To(MatchAllKeys(Keys{
"A": Equal("correct"),
}))
// passes
Expect(actual).To(MatchAllKeys(Keys{
"A": Equal("correct"),
"B": Equal("incorrect"),
}))
// passes
Expect(actual).To(MatchKeys(IgnoreMissing, Keys{
"A": Equal("correct"),
"B": Equal("incorrect"),
"C": Equal("whatever"), // ignored, because `actual` doesn't have this key
}))
```
### Testing pointer values
`gstruct` provides the `PointTo` function to apply a matcher to the value pointed-to. It will fail if the pointer value is `nil`:
foo := 5
Expect(&foo).To(PointTo(Equal(5)))
var bar *int
Expect(bar).NotTo(PointTo(BeNil()))
### Putting it all together: testing complex structures
The `gstruct` matchers are intended to be composable, and can be combined to apply fuzzy-matching to large and deeply nested structures. The additional `Ignore()` and `Reject()` matchers are provided for ignoring (always succeed) fields and elements, or rejecting (always fail) fields and elements.
Example:
```go
coreID := func(element interface{}) string {
return strconv.Itoa(element.(CoreStats).Index)
}
Expect(actual).To(MatchAllFields(Fields{
"Name": Ignore(),
"StartTime": BeTemporally(">=", time.Now().Add(-100 * time.Hour)),
"CPU": PointTo(MatchAllFields(Fields{
"Time": BeTemporally(">=", time.Now().Add(-time.Hour)),
"UsageNanoCores": BeNumerically("~", 1E9, 1E8),
"UsageCoreNanoSeconds": BeNumerically(">", 1E6),
"Cores": MatchElements(coreID, IgnoreExtras, Elements{
"0": MatchAllFields(Fields{
Index: Ignore(),
"UsageNanoCores": BeNumerically("<", 1E9),
"UsageCoreNanoSeconds": BeNumerically(">", 1E5),
}),
"1": MatchAllFields(Fields{
Index: Ignore(),
"UsageNanoCores": BeNumerically("<", 1E9),
"UsageCoreNanoSeconds": BeNumerically(">", 1E5),
}),
}),
})),
"Memory": PointTo(MatchAllFields(Fields{
"Time": BeTemporally(">=", time.Now().Add(-time.Hour)),
"AvailableBytes": BeZero(),
"UsageBytes": BeNumerically(">", 5E6),
"WorkingSetBytes": BeNumerically(">", 5E6),
"RSSBytes": BeNumerically("<", 1E9),
"PageFaults": BeNumerically("~", 1000, 100),
"MajorPageFaults": BeNumerically("~", 100, 50),
})),
"Rootfs": m.Ignore(),
"Logs": m.Ignore(),
}))
```
## `gmeasure`: Benchmarking Code
`gmeasure` provides support for measuring and recording benchmarks of your code and tests. It can be used as a simple standalone benchmarking framework, or as part of your code's test suite. `gmeasure` integrates cleanly with Ginkgo V2 to enable rich benchmarking of code alongside your tests.
### A Mental Model for `gmeasure`
`gmeasure` is organized around the metaphor of `Experiment`s that can each record multiple `Measurement`s. To use `gmeasure` you create a `NewExperiment` and use the resulting `experiment` object to record values and durations. You can then print out the `experiment` to get a report of all measurements or access specific measurements and their statistical aggregates to perform comparisons and/or make assertions.
An `experiment` can record _multiple_ `Measurement`s. Each `Measurement` has a `Name`, a `Type` (either `MeasurementTypeDuration` or `MeasurementTypeValue`), and a collection of recorded data points (of type `float64` for Value measurements and `time.Duration` for Duration measurements). In this way an experiment might describe a system or context being measured and can contain multiple measurements - one for each aspect of the system in question.
`Experiment`s can either record values and durations that the user passes in directly. Or they can invoke callbacks and accept their return values as Value data points, or measure their runtimes to compute Duration data points. `Experiment`s can also _sample_ callbacks, calling them repeatedly to get an ensemble of data points.
A `Measurement` is created when its first data point is recorded by an `Experiment`. Subsequent data points with the same measurement name are appended to the measurement:
```go
experiment := gmeasure.NewExperiment("My Experiment")
experiment.RecordDuration("runtime", 3*time.Second) //creates a new Measurement called "runtime"
experiment.RecordDuration("runtime", 5*time.Second) //appends a data point to "runtime"
```
As described below, Measurements can be decorated with additional information. This includes information about the `Units` for the measurement, the `Precision` with which to render the measurement, and any `Style` to apply when rendering the measurement. Individual data points can also be decorated with an `Annotation` - an arbitrary string that is associated with that data point and gives it context. Decorations are applied as typed variadic arguments:
```go
experiment := gmeasure.NewExperiment("My Experiment")
// The first call to `RecordValue` for a measurement must set up any units, style, or precision decorations
experiment.RecordValue("length", 3.141, gmeasure.Units("inches"), gmeasure.Style("{{blue}}"), gmeasure.Precision(2), gmeasure.Annotation("box A)"))
// Subsequent calls can attach an annotation. In this call a new data-point of `2.71` is added to the `length` measurement with the annotation `box B`.
experiment.RecordValue("length", 2.71, gmeasure.Annotation("box B"))
```
Once recorded, `Measurements` can be fetched from the `experiment` by name via `experiment.Get("name")`. The returned `Measurement` object includes all the data points. To get a statistical summary of the data points (that includes the min, max, median, mean, and standard deviation) call `measurement.Stats()` or `experiment.GetStats("name")`. These statistical summaries can also be rank-ordered with `RankStats()`.
`gmeasure` is designed to integrate with Ginkgo. This is done by registering `Experiment`s, `Measurement`s and `Ranking`s as `ReportEntry`s via Ginkgo's `AddReportEntry`. This will cause Ginkgo to emit nicely formatted and styled summaries of each of these objects when generating the test report.
Finally, `gmeasure` provides a mechanism to cache `Experiment`s to disk with a specified version number. This enables multiple use-cases. You can cache expensive experiments to avoid rerunning them while you iterate on other experiments. You can also compare experiments to cached experiments to explore whether changes in performance have been introduced to the codebase under test.
`gmeasure` includes detailed [godoc documentation](https://pkg.go.dev/github.com/onsi/gomega/gmeasure) - this narrative documentation is intended to help you get started with `gmeasure`.
### Measuring Values
`Experiment`s can record arbitrary `float64` values. You can do this by directly providing a `float64` via `experiment.RecordValue(measurementName string, value float64, decorators ...interface{})` or by providing a callback that returns a float64 via `experiment.MeasureValue(measurementName string, callback func() float64, decorators ...interface{})`.
You can apply `Units`, `Style`, and `Precision` decorators to control the appearance of the `Measurement` when reports are generated. These decorators must be applied when the first data point is recorded but can be elided thereafter. You can also associate an `Annotation` decoration with any recorded data point.
`Experiment`s are thread-safe so you can call `RecordValue` and `MeasureValue` from any goroutine.
### Measuring Durations
`Experiment`s can record arbitrary `time.Duration` durations. You can do this by directly providing a `time.Duration` via `experiment.RecordDuration(measurementName string, duration time.Duration, decorators ...interface{})` or by providing a callback via `experiment.MeasureDuration(measurementName string, callback func(), decorators ...interface{})`. `gmeasure` will run the callback and measure how long it takes to complete.
You can apply `Style` and `Precision` decorators to control the appearance of the `Measurement` when reports are generated. These decorators must be applied when the first data point is recorded but can be elided thereafter. You can also associate an `Annotation` decoration with any recorded data point.
`Experiment`s are thread-safe so you can call `RecordDuration` and `MeasureDuration` from any goroutine.
### Sampling
`Experiment`s support sampling callback functions repeatedly to build an ensemble of data points. All the sampling methods are configured by passing in a `SamplingConfig`:
```go
type SamplingConfig struct {
N int
Duration time.Duration
NumParallel int
MinSamplingInterval time.Duration
}
```
Setting `SamplingConfig.N` limits the total number of samples to perform to `N`. Setting `SamplingConfig.Duration` limits the total time spent sampling to `Duration`. At least one of these fields must be set. If both are set then `gmeasure` will `sample` until the first limiting condition is met. Setting `SamplingConfig.MinSamplingInterval` causes `gmeasure` to wait until at least `MinSamplingInterval` has elapsed between subsequent samples.
By default, the `Experiment`'s sampling methods will run their callbacks serially within the calling goroutine. If `NumParallel` greater than `1`, however, the sampling methods will spin up `NumParallel` goroutines and farm the work among them. You cannot use `NumParallel` with `MinSamplingInterval`.
The basic sampling method is `experiment.Sample(callback func(idx int), samplingConfig SamplingConfig)`. This will call the callback function repeatedly, passing in an `idx` counter that increments between each call. The sampling will end based on the conditions provided in `SamplingConfig`. Note that `experiment.Sample` is not explicitly associated with a measurement. You can use `experiment.Sample` whenever you want to repeatedly invoke a callback up to a limit of `N` and/or `Duration`. You can then record arbitrarily many value or duration measurements in the body of the callback.
A common use-case, however, is to invoke a callback repeatedly to measure its duration or record its returned value and thereby generate an ensemble of data-points. This is supported via the `SampleX` family of methods built on top of `Sample`:
```go
experiment.SampleValue(measurementName string, callback func(idx int) float64, samplingConfig SamplingConfig, decorations ...interface{})
experiment.SampleDuration(measurementName string, callback func(idx int), samplingConfig SamplingConfig, decorations ...interface{})
experiment.SampleAnnotatedValue(measurementName string, callback func(idx int) (float64, Annotation), samplingConfig SamplingConfig, decorations ...interface{})
experiment.SampleAnnotatedDuration(measurementName string, callback func(idx int) Annotation, samplingConfig SamplingConfig, decorations ...interface{})
```
each of these will contribute data points to the `Measurement` with name `measurementName`. `SampleValue` records the `float64` values returned by its callback. `SampleDuration` times each invocation of its callback and records the measured duration. `SampleAnnotatedValue` and `SampleAnnotatedDuration` expect their callbacks to return `Annotation`s. These are attached to each generated data point.
All these methods take the same decorators as their corresponding `RecordX` methods.
### Measuring Durations with `Stopwatch`
In addition to `RecordDuration` and `MeasureDuration`, `gmeasure` also provides a `Stopwatch`-based abstraction for recording durations. To motivate `Stopwatch` consider the following example. Let's say we want to measure the end-to-end performance of a web-server. Here's the code we'd like to measure:
```go
It("measures the end-to-end performance of the web-server", func() {
model, err := client.Fetch("model-id-17")
Expect(err).NotTo(HaveOccurred())
err = model.ReticulateSpines()
Expect(err).NotTo(HaveOccurred())
Expect(client.Save(model)).To(Succeed())
reticulatedModels, err := client.List("reticulated-models")
Expect(err).NotTo(HaveOccurred())
Expect(reticulatedModels).To(ContainElement(model))
})
```
One approach would be to use `MeasureDuration`:
```go
It("measures the end-to-end performance of the web-server", func() {
experiment := gmeasure.NewExperiment("end-to-end web-server performance")
AddReportEntry(experiment.Name, experiment)
var model Model
var err error
experiment.MeasureDuration("fetch", func() {
model, err = client.Fetch("model-id-17")
})
Expect(err).NotTo(HaveOccurred())
err = model.ReticulateSpines()
Expect(err).NotTo(HaveOccurred())
experiment.MeasureDuration("save", func() {
Expect(client.Save(model)).To(Succeed())
})
var reticulatedModels []Models
experiment.MeasureDuration("list", func() {
reticulatedModels, err = client.List("reticulated-models")
})
Expect(err).NotTo(HaveOccurred())
Expect(reticulatedModels).To(ContainElement(model))
})
```
this... _works_. But all those closures and local variables make the test a bit harder to read. We can clean it up with a `Stopwatch`:
```go
It("measures the end-to-end performance of the web-server", func() {
experiment := gmeasure.NewExperiment("end-to-end web-server performance")
AddReportEntry(experiment.Name, experiment)
stopwatch := experiment.NewStopwatch() // start the stopwatch
model, err := client.Fetch("model-id-17")
stopwatch.Record("fetch") // record the amount of time elapsed and store it in a Measurement named fetch
Expect(err).NotTo(HaveOccurred())
err = model.ReticulateSpines()
Expect(err).NotTo(HaveOccurred())
stopwatch.Reset() // reset the stopwatch
Expect(client.Save(model)).To(Succeed())
stopwatch.Record("save").Reset() // record the amount of time elapsed since the last Reset and store it in a Measurement named save, then reset the stopwatch
reticulatedModels, err := client.List("reticulated-models")
stopwatch.Record("list")
Expect(err).NotTo(HaveOccurred())
Expect(reticulatedModels).To(ContainElement(model))
})
```
that's now much cleaner and easier to reason about. If we wanted to sample the server's performance concurrently we could now simply wrap the relevant code in an `experiment.Sample`:
```go
It("measures the end-to-end performance of the web-server", func() {
experiment := gmeasure.NewExperiment("end-to-end web-server performance")
AddReportEntry(experiment.Name, experiment)
experiment.Sample(func(idx int) {
defer GinkgoRecover() // necessary since these will launch as goroutines and contain assertions
stopwatch := experiment.NewStopwatch() // we make a new stopwatch for each sample. Experiments are threadsafe, but Stopwatches are not.
model, err := client.Fetch("model-id-17")
stopwatch.Record("fetch")
Expect(err).NotTo(HaveOccurred())
err = model.ReticulateSpines()
Expect(err).NotTo(HaveOccurred())
stopwatch.Reset()
Expect(client.Save(model)).To(Succeed())
stopwatch.Record("save").Reset()
reticulatedModels, err := client.List("reticulated-models")
stopwatch.Record("list")
Expect(err).NotTo(HaveOccurred())
Expect(reticulatedModels).To(ContainElement(model))
}, gmeasure.SamplingConfig{N:100, Duration:time.Minute, NumParallel:8})
})
```
Check out the [godoc documentation](https://pkg.go.dev/github.com/onsi/gomega/gmeasure#Stopwatch) for more details about `Stopwatch` including support for `Pause`ing and `Resume`ing the stopwatch.
### Stats and Rankings: Comparing Measurements
Once you've recorded a few measurements you'll want to try to understand and interpret them. `gmeasure` allows you to quickly compute statistics for a given measurement. Consider the following example. Let's say we have two different ideas for how to implement a sorting algorithm and want to hone in on the algorithm with the shortest median runtime. We could run an experiment:
```go
It("identifies the fastest algorithm", func() {
experiment := gmeasure.NewExperiment("dueling algorithms")
AddReportEntry(experiment.Name, experiment)
experiment.SampleDuration("runtime: algorithm 1", func(_ int) {
RunAlgorithm1()
}, gmeasure.SamplingConfig{N:1000})
experiment.SampleDuration("runtime: algorithm 2", func(_ int) {
RunAlgorithm2()
}, gmeasure.SamplingConfig{N:1000})
})
```
This will sample the two competing tables and print out a tabular representation of the resulting statistics. (Note - you don't need to use Ginkgo here, you could just use `gmeasure` in your code directly and then `fmt.Println` the `experiment` to get the tabular report).
We could compare the tables by eye manually - or ask `gmeasure` to pick the winning algorithm for us:
```go
It("identifies the fastest algorithm", func() {
experiment := gmeasure.NewExperiment("dueling algorithms")
AddReportEntry(experiment.Name, experiment)
experiment.SampleDuration("runtime: algorithm 1", func(_ int) {
RunAlgorithm1()
}, gmeasure.SamplingConfig{N:1000})
experiment.SampleDuration("runtime: algorithm 2", func(_ int) {
RunAlgorithm2()
}, gmeasure.SamplingConfig{N:1000})
ranking := gmeasure.RankStats(gmeasure.LowerMedianIsBetter, experiment.GetStats("runtime: algorithm 1"), experiment.GetStats("runtime: algorithm 2"))
AddReportEntry("Ranking", ranking)
})
```
This will now emit a ranking result that will highlight the winning algorithm (in this case, the algorithm with the lower Median). `RankStats` supports the following `RankingCriteria`:
- `LowerMeanIsBetter`
- `HigherMeanIsBetter`
- `LowerMedianIsBetter`
- `HigherMedianIsBetter`
- `LowerMinIsBetter`
- `HigherMinIsBetter`
- `LowerMaxIsBetter`
- `HigherMaxIsBetter`
We can also inspect the statistics of the two algorithms programatically. `experiment.GetStats` returns a `Stats` object that provides access to the following `Stat`s:
- `StatMin` - the data point with the smallest value
- `StatMax` - the data point with the highest values
- `StatMedian` - the median data point
- `StatMean` - the mean of all the data points
- `StatStdDev` - the standard deviation of all the data points
`Stats` can represent either Value Measurements or Duration Measurements. When inspecting a Value Measurement you can pull out the requested `Stat` (say, `StatMedian`) via `stats.ValueFor(StatMedian)` - this returns a `float64`. When inspecting Duration Measurements you can fetch `time.Duration` statistics via `stats.DurationFor(StatX)`. For either type you can fetch an appropriately formatted string representation of the stat via `stats.StringFor(StatX)`. You can also get a `float64` for either type by calling `stats.FloatFor(StatX)` (this simply returns a `float64(time.Duration)` for Duration Measurements and can be useful when you need to do some math with the stats).
Going back to our dueling algorithms example. Lets say we find that Algorithm 2 is the winner with a median runtime of around 3 seconds - and we want to be alerted by a failing test should the winner ever change, or the median runtime vary substantially. We can do that by writing a few assertions:
```go
It("identifies the fastest algorithm", func() {
experiment := gmeasure.NewExperiment("dueling algorithms")
AddReportEntry(experiment.Name, experiment)
experiment.SampleDuration("runtime: algorithm 1", func(_ int) {
RunAlgorithm1()
}, gmeasure.SamplingConfig{N:1000})
experiment.SampleDuration("runtime: algorithm 2", func(_ int) {
RunAlgorithm2()
}, gmeasure.SamplingConfig{N:1000})
ranking := gmeasure.RankStats(gmeasure.LowerMedianIsBetter, experiment.GetStats("runtime: algorithm 1"), experiment.GetStats("runtime: algorithm 2"))
AddReportEntry("Ranking", ranking)
//assert that algorithm 2 is the winner
Expect(ranking.Winner().MeasurementName).To(Equal("runtime: algorithm 2"))
//assert that algorithm 2's median is within 0.5 seconds of 3 seconds
Expect(experiment.GetStats("runtime: algorithm 2").DurationFor(gmeasure.StatMedian)).To(BeNumerically("~", 3*time.Second, 500*time.Millisecond))
})
```
### Formatting Experiment and Measurement Output
`gmeasure` can produce formatted tabular output for `Experiment`s, `Measurement`s, and `Ranking`s. Each of these objects provides a `String()` method and a `ColorableString()` method. The `String()` method returns a string that does not include any styling tags whereas the `ColorableString()` method returns a string that includes Ginkgo's console styling tags (e.g. Ginkgo will render a string like `{{blue}}{{bold}}hello{{/}} there` as a bold blue "hello" followed by a default-styled " there"). `ColorableString()` is called for you automatically when you register any of these `gmeasure` objects as Ginkgo `ReportEntry`s.
When printing out `Experiment`s, `gmeasure` will produce a table whose columns correspond to the key statistics provided by `gmeasure.Stats` and whose rows are the various `Measurement`s recorded by the `Experiment`. Users can also record and emit notes - contextual information about the experiment - by calling `experiment.RecordNote(note string)`. Each note will get its own row in the table.
When printing out `Measurement`s, `gmeasure` will produce a table that includes _all_ the data points and annotations for the `Measurement`.
When printing out `Ranking`s, `gmeasure` will produce a table similar to the `Experiment` table with the `Measurement`s sorted by `RankingCriteria`.
Users can adjust a few aspects of `gmeasure`s output. This is done by providing decorators to the `Experiment` methods that record data points:
- `Units(string)` - the `Units` decorator allows you to associate a set of units with a measurement. Subsequent renderings of the measurement's name will include the units in `[]` square brackets.
- `Precision(int or time.Duration)` - the `Precision` decorator controls the rendering of numerical information. For Value Measurements an `int` is used to express the number of decimal points to print. For example `Precision(3)` will render values with `fmt.Sprintf("%.3f", value)`. For Duration Measurements a `time.Duration` is used to round durations before rendering them. For example `Precision(time.Second)` will render durations via `duration.Round(time.Second).String()`.
- `Style(string)` - the `Style` decorator allows you to associate a Ginkgo console style to a measurement. The measurement's row will be rendered with this style. For example `Style("{{green}}")` will emit a green row.
These formatting decorators **must** be applied to the _first_ data point recorded for a given Measurement (this is when the Measurement object is initialized and its style, precision, and units fields are populated).
Just to get concrete here's a fleshed out example that uses all the things:
```go
It("explores a complex object", func() {
experiment := gmeasure.NewExperiment("exploring the encabulator")
AddReportEntry(experiment.Name, experiment)
experiment.RecordNote("Encabulation Properties")
experiment.Sample(func(idx int) {
stopwatch := experiment.NewStopwatch()
encabulator.Encabulate()
stopwatch.Record("Encabulate Runtime", gmeasure.Style("{{green}}"), gmeasure.Precision(time.Millisecond))
var m runtime.MemStats
runtime.ReadMemStats(&m)
experiment.RecordValue("Encabulate Memory Usage", float64(m.Alloc / 1024 / 1024), gmeasure.Style("{{red}}"), gmeasure.Precision(3), gmeasure.Units("MB"), gmeasure.Annotation(fmt.Sprintf("%d", idx)))
}, gmeasure.SamplingConfig{N:1000, NumParallel:4})
experiment.RecordNote("Encabulation Teardown")
experiment.MeasureDuration("Teardown Runtime", func() {
encabulator.Teardown()
}, gmeasure.Style("{{yellow}}"))
memoryStats := experiment.GetStats("Encabulate Memory Usage")
minMemory := memoryStats.ValueFor(gmeasure.StatMin)
maxMemory := memoryStats.ValueFor(gmeasure.StatMax)
Expect(maxMemory - minMemory).To(BeNumerically("<=", 10), "Should not see memory fluctuations exceeding 10 megabytes")
})
```
### Ginkgo Integration
The examples throughout this documentation have illustrated how `gmeasure` interoperates with Ginkgo. In short - you can emit output for `Experiment`, `Measurement`s, and `Ranking`s by registering them as Ginkgo `ReportEntry`s via `AddReportEntry()`.
This simple connection point ensures that the output is appropriately formatted and associated with the spec in question. It also ensures that Ginkgo's machine readable reports will include appropriately encoded versions of these `gmeasure` objects. So, for example, `ginkgo --json-report=report.json` will include JSON encoded `Experiment`s in `report.json` if you remember to `AddReportEntry` the `Experiment`s.
### Caching Experiments
`gmeasure` supports caching experiments to local disk. Experiments can be stored and retrieved from the cache by name and version number. Caching allows you to skip rerunning expensive experiments and versioned caching allows you to bust the cache by incrementing the version number. Under the hood, the cache is simply a set of files in a directory. Each file contains a JSON encoded header with the experiment's name and version number followed by the JSON-encoded experiment. The various cache methods are documented over at [pkg.go.dev](https://pkg.go.dev/github.com/onsi/gomega/gmeasure#ExperimentCache).
Using an `ExperimentCache` with Ginkgo takes a little bit of wiring. Here's an example:
```go
const EXPERIMENT_VERSION = 1 //bump this to bust the cache and recompute _all_ experiments
Describe("some experiments", func() {
var cache gmeasure.ExperimentCache
var experiment *gmeasure.Experiment
BeforeEach(func() {
cache = gmeasure.NewExperimentCache("./gmeasure-cache")
name := CurrentSpecReport().LeafNodeText // we use the text in each It block as the name of the experiment
experiment = cache.Load(name, EXPERIMENT_VERSION) // we try to load the experiment from the cache
if experiment != nil {
// we have a cache hit - report on the experiment and skip this test.
AddReportEntry(experiment)
Skip("cached")
}
//we have a cache miss, make a new experiment and proceed with the test.
experiment = gmeasure.NewExperiment(name)
AddReportEntry(experiment)
})
It("measures foo runtime", func() {
experiment.SampleDuration("runtime", func() {
//do stuff
}, gmeasure.SamplingConfig{N:100})
})
It("measures bar runtime", func() {
experiment.SampleDuration("runtime", func() {
//do stuff
}, gmeasure.SamplingConfig{N:100})
})
AfterEach(func() {
// AfterEaches always run, even for tests that call `Skip`. So we make sure we aren't a skipped test then save the experiment to the cache
if !CurrentSpecReport().State.Is(types.SpecStateSkipped) {
cache.Save(experiment.Name, EXPERIMENT_VERSION, experiment)
}
})
})
```
this test will load the experiment from the cache if it's available or run the experiment and store it in the cache if it is not. Incrementing `EXPERIMENT_VERSION` will force all experiments to rerun.
Another usecase for `ExperimentCache` is to cache and commit experiments to source control for use as future baselines. Your code can assert that measurements are within a certain range of the stored baseline. For example:
```go
Describe("server performance", func() {
It("ensures a performance regression has not been introduced", func() {
// make an experiment
experiment := gmeasure.NewExperiment("performance regression test")
AddReportEntry(experiment.Name, experiment)
// measure the performance of one endpoint
experiment.SampleDuration("fetching one", func() {
model, err := client.Get("id-1")
Expect(err).NotTo(HaveOccurred())
Expect(model.Id).To(Equal("id-1"))
}, gmeasure.SamplingConfig{N:100})
// measure the performance of another endpoint
experiment.SampleDuration("listing", func() {
models, err := client.List()
Expect(err).NotTo(HaveOccurred())
Expect(models).To(HaveLen(30))
}, gmeasure.SamplingConfig{N:100})
cache := gmeasure.NewExperimentCache("./gemasure-cache")
baseline := cache.Load("performance regression test", 1)
if baseline == nil {
// this is the first run, let's store a baseline
cache.Save("performacne regression test", 1, experiment)
} else {
for _, m := range []string{"fetching one", "listing"} {
baselineStats := baseline.GetStats(m)
currentStats := experiment.GetStats(m)
//make sure the mean of the current performance measure is within one standard deviation of the baseline
Expect(currentStats.DurationFor(gmeasure.StatMean)).To(BeNumerically("~", baselineStats.DurationFor(gmeasure.StatsMean), baselineStats.DurationFor(gmeasure.StatsStdDev)), m)
}
}
})
})
```
## `gleak`: Finding Leaked Goroutines
The `gleak` package provides support for goroutine leak detection.
> **Please note:** gleak is an experimental new Gomega package.
### Basics
Calling `Goroutines` returns information about all goroutines of a program at
this moment. `Goroutines` typically gets invoked in the form of
`Eventually(Goroutines).ShouldNot(...)`. Please note the missing `()` after
`Goroutines`, as it must be called by `Eventually` and **not before it** with
its results passed to `Eventually` only once. This does not preclude calling
`Goroutines()`, such as for taking goroutines snapshots.
Leaked goroutines are then detected by using `gleak`'s `HaveLeaked` matcher on
the goroutines information. `HaveLeaked` checks the actual list of goroutines
against a built-in list of well-known runtime and testing framework goroutines,
as well as against any optionally additional goroutines specifications passed to
`HaveLeaked`. Good, and thus "non-leaky", Goroutines can be identified in
multiple ways: such as by the name of a topmost function on a goroutine stack or
a snapshot of goroutine information taken before a test. Non-leaky goroutines
can also be identified using basically any Gomega matcher, with `HaveField` or
`WithTransform` being highly useful in test-specific situations.
The `HaveLeaked` matcher _succeeds_ if it finds any goroutines that are neither
in the integrated list of well-known goroutines nor in the optionally specified
`HaveLeaked` arguments. In consequence, any _success_ of `HaveLeaked` actually
is meant to be a _failure_, because of leaked goroutines. `HaveLeaked` is thus
mostly used in combination with `ShouldNot` and `NotTo`/`ToNot`.
### Testing for Goroutine Leaks
In its most simple form, just run a goroutine discovery with a leak check right
_after_ each test in `AfterEach`:
> **Important:** always use `Goroutines` and not `Goroutines()` in the call to
> `Eventually`. This ensures that the goroutine discovery is correctly done
> repeatedly as needed and not just a single time before calling `Eventually`.
```go
AfterEach(func() {
Eventually(Goroutines).ShouldNot(HaveLeaked())
})
```
Using `Eventually` instead of `Ω`/`Expect` has the benefit of retrying the leak
check periodically until there is no leak or until a timeout occurs. This
ensures that goroutines that are (still) in the process of winding down can
correctly terminate without triggering false positives. Please refer to the
[`Eventually`](#eventually) section for details on how to change the timeout
interval (which defaults to 1s) and the polling interval (which defaults to
10ms).
Please note that this simplest form of goroutine leak test can cause false
positives in situations where a test suite or dependency module uses additional
goroutines. This simple form only looks at all goroutines _after_ a test has run
and filters out all _well-known_ "non-leaky" goroutines, such as goroutines from
Go's runtime and the testing frameworks (such as Go's own testing package and
Gomega).
### Ginkgo -p
In case you intend to run multiple package tests in parallel using `ginkgo -p
...`, you'll need to update any existing `BeforeSuite` or add new `BeforeSuite`s
in each of your packages. Calling `gleak.IgnoreGinkgoParallelClient` at the
beginning of `BeforeSuite` ensures that `gleak` updates its internal ignore list
to ignore a background goroutine related to the communication between Ginkgo and
the parallel packages under test.
```go
var _ = BeforeSuite(func() {
IgnoreGinkgoParallelClient()
})
```
### Using Goroutine Snapshots in Leak Testing
Often, it might be sufficient to cover for additional "non-leaky" goroutines by
taking a "snapshot" of goroutines _before_ a test and then _afterwards_ use the
snapshot to filter out the supposedly "non-leaky" goroutines.
Using Ginkgo's v2 `DeferCleanup` this can be expressed in a compact manner and
without the need for explicitly declaring a variable to carry the list of known
goroutines over from `BeforeEach` to `AfterEach`. This keeps all things declared
neatly in a single place.
```go
BeforeEach(func() {
goods := Goroutines()
DeferCleanup(func() {
Eventually(Goroutines).ShouldNot(HaveLeaked(goods))
})
})
```
### `HaveLeaked` Matcher
```go
Eventually(ACTUAL).ShouldNot(HaveLeaked(NONLEAKY1, NONLEAKY2, NONLEAKY3, ...))
```
causes a test to fail if `ACTUAL` after filtering out the well-known "good" (and
non-leaky) goroutines of the Go runtime and test frameworks, as well as
filtering out the additional non-leaky goroutines passed to the matcher, still
results in one or more goroutines. The ordering of the goroutines does not
matter.
`HaveLeaked` always takes the built-in list of well-known good goroutines into
consideration and this list can neither be overridden nor disabled. Additional
known non-leaky goroutines `NONLEAKY1`, ... can be passed to `HaveLeaks` either
in form of `GomegaMatcher`s or in shorthand notation:
- `"foo.bar"` is shorthand for `IgnoringTopFunction("foo.bar")` and filters out
any (non-leaky) goroutine with its topmost function on the backtrace stack
having the exact name `foo.bar`.
- `"foo.bar..."` is shorthand for `IgnoringTopFunction("foo.bar...")` and
filters out any (non-leaky) goroutine with its topmost function on the
backtrace stack beginning with the prefix `foo.bar.`; please notice the
trailing `.` dot.
- `"foo.bar [chan receive]"` is shorthand for `IgnoringTopFunction("foo.bar
[chan receive]")` and filters out any (non-leaky) goroutine where its topmost
function on the backtrace stack has the exact name `foo.bar` _and_ the
goroutine is in a state beginning with `chan receive`.
- `[]Goroutine` is shorthand for
`IgnoringGoroutines()`: it filters out the specified
goroutines, considering them to be non-leaky. The goroutines are identified by
their [goroutine IDs](#goroutine-ids).
- `IgnoringInBacktrace("foo.bar.baz")` filters out any (non-leaky) goroutine
with `foo.bar.baz` _anywhere_ in its backtrace.
- additionally, any other `GomegaMatcher` can be passed to `HaveLeaked()`, as
long as this matcher can work on a passed-in actual value of type
`Goroutine`.
### Goroutine Matchers
The `gleak` packages comes with a set of predefined Goroutine matchers, to be
used with `HaveLeaked`. If these matchers succeed (that is, they match on a
certain `Goroutine`), then `HaveLeaked` considers the matched goroutine to be
non-leaky.
#### IgnoringTopFunction(topfname string)
```go
Eventually(ACTUAL).ShouldNot(HaveLeaked(IgnoringTopFunction(TOPFNAME)))
```
In its most basic form, `IgnoringTopFunction` succeeds if `ACTUAL` contains a
goroutine where the name of the topmost function on its call stack (backtrace)
is `TOPFNAME`, causing `HaveLeaked` to filter out the matched goroutine as
non-leaky. Different forms of `TOPFNAME` describe different goroutine matching
criteria:
- `"foo.bar"` matches only if a goroutine's topmost function has this exact name
(ignoring any function parameters).
- `"foo.bar..."` matches if a goroutine's topmost function name starts with the
prefix `"foo.bar."`; it doesn't match `"foo.bar"` though.
- `"foo.bar [state]"` matches if a goroutine's topmost function has this exact
name and the goroutine's state begins with the specified state string.
`ACTUAL` must be an array or slice of `Goroutine`s.
#### IgnoringGoroutines(goroutines []Goroutine)
```go
Eventually(ACTUAL).ShouldNot(HaveLeaked(IgnoringGoroutines(GOROUTINES)))
```
`IgnoringGoroutines` succeeds if `ACTUAL` contains one or more goroutines which
are elements of `GOROUTINES`, causing `HaveLeaked` to filter out the matched
goroutine(s) as non-leaky. `IgnoringGoroutines` compares goroutines by their
`ID`s (see [Goroutine IDs](#gorotuine-ids) for background information).
`ACTUAL` must be an array or slice of `Goroutine`s.
#### IgnoringInBacktrace(fname string)
```go
Eventually(Goroutines).ShouldNot(HaveLeaked(IgnoringInBacktrace(FNAME)))
```
`IgnoringInBacktrace` succeeds if `ACTUAL` contains a goroutine where `FNAME` is
contained anywhere within its call stack (backtrace), causing `HaveLeaked` to
filter out the matched goroutine as non-leaky. Please note that
`IgnoringInBacktrace` uses a (somewhat lazy) `strings.Contains` to check for any
occurrence of `FNAME` in backtraces.
`ACTUAL` must be an array or slice of `Goroutine`s.
#### IgnoringCreator(creatorname string)
```go
Eventually(Goroutines).ShouldNot(HaveLeaked(IgnoringCreator(CREATORNAME)))
```
In its most basic form, `IgnoringCreator` succeeds if `ACTUAL` contains a
goroutine where the name of the function creating the goroutine matches
`CREATORNAME`, causing `HaveLeaked` to filter out the matched goroutine(s) as
non-leaky. `IgnoringCreator` uses `==` for comparing the creator function name.
Different forms of `CREATORNAME` describe different goroutine matching
criteria:
- `"foo.bar"` matches only if a goroutine's creator function has this exact name
(ignoring any function parameters).
- `"foo.bar..."` matches if a goroutine's creator function name starts with the
prefix `"foo.bar."`; it doesn't match `"foo.bar"` though.
### Adjusting Leaky Goroutine Reporting
When `HaveLeaked` finds leaked goroutines, `gleak` prints out a description of
(only) the _leaked_ goroutines. This is different from panic output that
contains backtraces of all goroutines.
However, `noleak`'s goroutine dump deliberately is not subject to Gomega's usual
object rendition controls, such as `format.MaxLength` (see also [Adjusting
Output](#adjusting-output)).
`noleak` will print leaked goroutine backtraces in a more compact form, with
function calls and locations combined into single lines. Additionally, `noleak`
defaults to reporting only the package plus file name and line number, but not
the full file path. For instance:
main.foo.func1() at foo/bar.go:123
Setting `noleak.ReportFilenameWithPath` to `true` will instead report full
source code file paths:
main.foo.func1() at /home/coolprojects/ohmyleak/mymodule/foo/bar.go:123
### Well-Known Non-Leaky Goroutines
The well-known good (and therefore "non-leaky") goroutines are identified by the
names of the topmost functions on their stacks (backtraces):
- signal handling:
- `os/signal.signal_recv` and `os/signal.loop` (covering
varying state),
- as well as `runtime.ensureSigM`.
- Go's built-in [`testing`](https://pkg.go.dev/testing) framework:
- `testing.RunTests [chan receive]`,
- `testing.(*T).Run [chan receive]`,
- and `testing.(*T).Parallel [chan receive]`.
- the [Ginkgo testing framework](https://onsi.github.io/ginkgo/):
- `github.com/onsi/ginkgo/v2/internal.(*Suite).runNode` (including anonymous
inner functions),
- the anonymous inner functions of
`github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts`,
- the creators `github.com/onsi/ginkgo/v2/internal.(*genericOutputInterceptor).ResumeIntercepting` and `github.com/onsi/ginkgo/v2/internal.(*genericOutputInterceptor).ResumeIntercepting...`,
- the creator `github.com/onsi/ginkgo/v2/internal.RegisterForProgressSignal`,
- and finally
`github.com/onsi/ginkgo/internal/specrunner.(*SpecRunner).registerForInterrupts`
(for v1 support).
Additionally, any goroutines with `runtime.ReadTrace` in their backtrace stack
are also considered to be non-leaky.
### Goroutine IDs
In order to detect goroutine identities, we use what is generally termed
"goroutine IDs". These IDs appear in runtime stack dumps ("backtrace"). But …
are these goroutine IDs even unambiguous? What are their "guarantees", if there
are any at all?
First, Go's runtime code uses the identifier (and thus term) [`goid` for
Goroutine
IDs](https://github.com/golang/go/search?q=goidgen&unscoped_q=goidgen). Good to
know in case you need to find your way around Go's runtime code.
Now, based on [Go's `goid` runtime allocation
code](https://github.com/golang/go/blob/release-branch.go1.18/src/runtime/proc.go#L4130),
goroutine IDs never get reused – unless you manage to make the 64bit "master
counter" of the Go runtime scheduler to wrap around. However, not all goroutine
IDs up to the largest one currently seen might ever be used, because as an
optimization goroutine IDs are always assigned to Go's "P" processors for
assignment to newly created "G" goroutines in batches of 16. In consequence,
there may be gaps and later goroutines might have lower goroutine IDs if they
get created from a different P.
Finally, there's [Scott Mansfield's blog post on Goroutine
IDs](https://blog.sgmansfield.com/2015/12/goroutine-ids/). To sum up Scott's
point of view: don't use goroutine IDs. He spells out good reasons for why you
should not use them. Yet, logging, debugging and testing looks like a sane and
solid exemption from his rule, not least `runtime.Stack` includes the `goids`
for
some reason.
### Credits
The _Leakiee the gopher_ mascot clearly has been inspired by the Go gopher art
work of [Renee French](http://reneefrench.blogspot.com/).
The `gleak` package was heavily inspired by Uber's fine
[goleak](https://github.com/uber-go/goleak) goroutine leak detector package.
While `goleak` can be used with Gomega and Ginkgo in a very specific form, it
unfortunately was never designed to be (optionally) used with a matcher library
to unlock the full potential of reasoning about leaky goroutines. In fact, the
crucial element of discovering goroutines is kept internal in `goleak`. In
consequence, Gomega's `gleak` package uses its own goroutine discovery and is
explicitly designed to perfectly blend in with Gomega (and Ginkgo).
{% endraw %}
golang-gomega-1.27.10/docs/js/ 0000775 0000000 0000000 00000000000 14462163431 0015736 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/docs/js/docs.js 0000664 0000000 0000000 00000004256 14462163431 0017233 0 ustar 00root root 0000000 0000000 (() => {
let sidebar = document.getElementById("sidebar")
let headings = document.querySelectorAll("#content h2,h3")
let headingsLookup = {}
let currentHeadingGroup = null
let collapsibleGroup = null
for (let heading of headings) {
let el = document.createElement("a")
el.href = `#${heading.id}`
el.id = `${heading.id}-item`
el.innerText = heading.innerText
if (heading.tagName == "H2") {
currentHeadingGroup = heading.id
el.classList = "sidebar-heading"
sidebar.appendChild(el)
collapsibleGroup = document.createElement("div")
collapsibleGroup.classList = "sidebar-section"
sidebar.appendChild(collapsibleGroup)
} else {
el.classList = "sidebar-item"
collapsibleGroup.appendChild(el)
}
headingsLookup[heading.id] = currentHeadingGroup
}
let ticking = false;
document.getElementById("content").addEventListener("scroll", (e) => {
if (!ticking) {
window.requestAnimationFrame(function () {
let viewportHeight = window.visualViewport.height;
let winner = null;
for (let heading of headings) {
let rect = heading.getBoundingClientRect();
if (rect.top > viewportHeight) { break }
winner = heading.id
if (rect.top > 0) { break }
}
if (winner != null) {
document.querySelectorAll("#sidebar .active").forEach(e => e.classList.remove("active"))
document.getElementById(`${winner}-item`).classList.add("active")
document.getElementById(`${headingsLookup[winner]}-item`).classList.add("active");
}
ticking = false;
});
ticking = true;
}
})
document.querySelector("img[alt=Gomega]").id = "top"
document.querySelectorAll("div.highlight").forEach(el => {
if (el.innerText.includes("/* === INVALID === */")) {
el.classList.add("invalid")
}
})
document.getElementById("disclosure").addEventListener("click", (e) => {
document.getElementById("container").classList.toggle("reveal-sidebar")
})
document.getElementById("mask").addEventListener("click", (e) => {
document.getElementById("container").classList.toggle("reveal-sidebar")
})
})()
golang-gomega-1.27.10/format/ 0000775 0000000 0000000 00000000000 14462163431 0015662 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/format/format.go 0000664 0000000 0000000 00000035061 14462163431 0017506 0 ustar 00root root 0000000 0000000 /*
Gomega's format package pretty-prints objects. It explores input objects recursively and generates formatted, indented output with type information.
*/
// untested sections: 4
package format
import (
"context"
"fmt"
"reflect"
"strconv"
"strings"
"time"
)
// Use MaxDepth to set the maximum recursion depth when printing deeply nested objects
var MaxDepth = uint(10)
// MaxLength of the string representation of an object.
// If MaxLength is set to 0, the Object will not be truncated.
var MaxLength = 4000
/*
By default, all objects (even those that implement fmt.Stringer and fmt.GoStringer) are recursively inspected to generate output.
Set UseStringerRepresentation = true to use GoString (for fmt.GoStringers) or String (for fmt.Stringer) instead.
Note that GoString and String don't always have all the information you need to understand why a test failed!
*/
var UseStringerRepresentation = false
/*
Print the content of context objects. By default it will be suppressed.
Set PrintContextObjects = true to enable printing of the context internals.
*/
var PrintContextObjects = false
// TruncatedDiff choose if we should display a truncated pretty diff or not
var TruncatedDiff = true
// TruncateThreshold (default 50) specifies the maximum length string to print in string comparison assertion error
// messages.
var TruncateThreshold uint = 50
// CharactersAroundMismatchToInclude (default 5) specifies how many contextual characters should be printed before and
// after the first diff location in a truncated string assertion error message.
var CharactersAroundMismatchToInclude uint = 5
var contextType = reflect.TypeOf((*context.Context)(nil)).Elem()
var timeType = reflect.TypeOf(time.Time{})
// The default indentation string emitted by the format package
var Indent = " "
var longFormThreshold = 20
// GomegaStringer allows for custom formating of objects for gomega.
type GomegaStringer interface {
// GomegaString will be used to custom format an object.
// It does not follow UseStringerRepresentation value and will always be called regardless.
// It also ignores the MaxLength value.
GomegaString() string
}
/*
CustomFormatters can be registered with Gomega via RegisterCustomFormatter()
Any value to be rendered by Gomega is passed to each registered CustomFormatters.
The CustomFormatter signals that it will handle formatting the value by returning (formatted-string, true)
If the CustomFormatter does not want to handle the object it should return ("", false)
Strings returned by CustomFormatters are not truncated
*/
type CustomFormatter func(value interface{}) (string, bool)
type CustomFormatterKey uint
var customFormatterKey CustomFormatterKey = 1
type customFormatterKeyPair struct {
CustomFormatter
CustomFormatterKey
}
/*
RegisterCustomFormatter registers a CustomFormatter and returns a CustomFormatterKey
You can call UnregisterCustomFormatter with the returned key to unregister the associated CustomFormatter
*/
func RegisterCustomFormatter(customFormatter CustomFormatter) CustomFormatterKey {
key := customFormatterKey
customFormatterKey += 1
customFormatters = append(customFormatters, customFormatterKeyPair{customFormatter, key})
return key
}
/*
UnregisterCustomFormatter unregisters a previously registered CustomFormatter. You should pass in the key returned by RegisterCustomFormatter
*/
func UnregisterCustomFormatter(key CustomFormatterKey) {
formatters := []customFormatterKeyPair{}
for _, f := range customFormatters {
if f.CustomFormatterKey == key {
continue
}
formatters = append(formatters, f)
}
customFormatters = formatters
}
var customFormatters = []customFormatterKeyPair{}
/*
Generates a formatted matcher success/failure message of the form:
Expected
If expected is omitted, then the message looks like:
Expected
*/
func Message(actual interface{}, message string, expected ...interface{}) string {
if len(expected) == 0 {
return fmt.Sprintf("Expected\n%s\n%s", Object(actual, 1), message)
}
return fmt.Sprintf("Expected\n%s\n%s\n%s", Object(actual, 1), message, Object(expected[0], 1))
}
/*
Generates a nicely formatted matcher success / failure message
Much like Message(...), but it attempts to pretty print diffs in strings
Expected
: "...aaaaabaaaaa..."
to equal |
: "...aaaaazaaaaa..."
*/
func MessageWithDiff(actual, message, expected string) string {
if TruncatedDiff && len(actual) >= int(TruncateThreshold) && len(expected) >= int(TruncateThreshold) {
diffPoint := findFirstMismatch(actual, expected)
formattedActual := truncateAndFormat(actual, diffPoint)
formattedExpected := truncateAndFormat(expected, diffPoint)
spacesBeforeFormattedMismatch := findFirstMismatch(formattedActual, formattedExpected)
tabLength := 4
spaceFromMessageToActual := tabLength + len(": ") - len(message)
paddingCount := spaceFromMessageToActual + spacesBeforeFormattedMismatch
if paddingCount < 0 {
return Message(formattedActual, message, formattedExpected)
}
padding := strings.Repeat(" ", paddingCount) + "|"
return Message(formattedActual, message+padding, formattedExpected)
}
actual = escapedWithGoSyntax(actual)
expected = escapedWithGoSyntax(expected)
return Message(actual, message, expected)
}
func escapedWithGoSyntax(str string) string {
withQuotes := fmt.Sprintf("%q", str)
return withQuotes[1 : len(withQuotes)-1]
}
func truncateAndFormat(str string, index int) string {
leftPadding := `...`
rightPadding := `...`
start := index - int(CharactersAroundMismatchToInclude)
if start < 0 {
start = 0
leftPadding = ""
}
// slice index must include the mis-matched character
lengthOfMismatchedCharacter := 1
end := index + int(CharactersAroundMismatchToInclude) + lengthOfMismatchedCharacter
if end > len(str) {
end = len(str)
rightPadding = ""
}
return fmt.Sprintf("\"%s\"", leftPadding+str[start:end]+rightPadding)
}
func findFirstMismatch(a, b string) int {
aSlice := strings.Split(a, "")
bSlice := strings.Split(b, "")
for index, str := range aSlice {
if index > len(bSlice)-1 {
return index
}
if str != bSlice[index] {
return index
}
}
if len(b) > len(a) {
return len(a) + 1
}
return 0
}
const truncateHelpText = `
Gomega truncated this representation as it exceeds 'format.MaxLength'.
Consider having the object provide a custom 'GomegaStringer' representation
or adjust the parameters in Gomega's 'format' package.
Learn more here: https://onsi.github.io/gomega/#adjusting-output
`
func truncateLongStrings(s string) string {
if MaxLength > 0 && len(s) > MaxLength {
var sb strings.Builder
for i, r := range s {
if i < MaxLength {
sb.WriteRune(r)
continue
}
break
}
sb.WriteString("...\n")
sb.WriteString(truncateHelpText)
return sb.String()
}
return s
}
/*
Pretty prints the passed in object at the passed in indentation level.
Object recurses into deeply nested objects emitting pretty-printed representations of their components.
Modify format.MaxDepth to control how deep the recursion is allowed to go
Set format.UseStringerRepresentation to true to return object.GoString() or object.String() when available instead of
recursing into the object.
Set PrintContextObjects to true to print the content of objects implementing context.Context
*/
func Object(object interface{}, indentation uint) string {
indent := strings.Repeat(Indent, int(indentation))
value := reflect.ValueOf(object)
commonRepresentation := ""
if err, ok := object.(error); ok && !isNilValue(value) { // isNilValue check needed here to avoid nil deref due to boxed nil
commonRepresentation += "\n" + IndentString(err.Error(), indentation) + "\n" + indent
}
return fmt.Sprintf("%s<%s>: %s%s", indent, formatType(value), commonRepresentation, formatValue(value, indentation))
}
/*
IndentString takes a string and indents each line by the specified amount.
*/
func IndentString(s string, indentation uint) string {
return indentString(s, indentation, true)
}
func indentString(s string, indentation uint, indentFirstLine bool) string {
result := &strings.Builder{}
components := strings.Split(s, "\n")
indent := strings.Repeat(Indent, int(indentation))
for i, component := range components {
if i > 0 || indentFirstLine {
result.WriteString(indent)
}
result.WriteString(component)
if i < len(components)-1 {
result.WriteString("\n")
}
}
return result.String()
}
func formatType(v reflect.Value) string {
switch v.Kind() {
case reflect.Invalid:
return "nil"
case reflect.Chan:
return fmt.Sprintf("%s | len:%d, cap:%d", v.Type(), v.Len(), v.Cap())
case reflect.Ptr:
return fmt.Sprintf("%s | 0x%x", v.Type(), v.Pointer())
case reflect.Slice:
return fmt.Sprintf("%s | len:%d, cap:%d", v.Type(), v.Len(), v.Cap())
case reflect.Map:
return fmt.Sprintf("%s | len:%d", v.Type(), v.Len())
default:
return v.Type().String()
}
}
func formatValue(value reflect.Value, indentation uint) string {
if indentation > MaxDepth {
return "..."
}
if isNilValue(value) {
return "nil"
}
if value.CanInterface() {
obj := value.Interface()
// if a CustomFormatter handles this values, we'll go with that
for _, customFormatter := range customFormatters {
formatted, handled := customFormatter.CustomFormatter(obj)
// do not truncate a user-provided CustomFormatter()
if handled {
return indentString(formatted, indentation+1, false)
}
}
// GomegaStringer will take precedence to other representations and disregards UseStringerRepresentation
if x, ok := obj.(GomegaStringer); ok {
// do not truncate a user-defined GomegaString() value
return indentString(x.GomegaString(), indentation+1, false)
}
if UseStringerRepresentation {
switch x := obj.(type) {
case fmt.GoStringer:
return indentString(truncateLongStrings(x.GoString()), indentation+1, false)
case fmt.Stringer:
return indentString(truncateLongStrings(x.String()), indentation+1, false)
}
}
}
if !PrintContextObjects {
if value.Type().Implements(contextType) && indentation > 1 {
return ""
}
}
switch value.Kind() {
case reflect.Bool:
return fmt.Sprintf("%v", value.Bool())
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
return fmt.Sprintf("%v", value.Int())
case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
return fmt.Sprintf("%v", value.Uint())
case reflect.Uintptr:
return fmt.Sprintf("0x%x", value.Uint())
case reflect.Float32, reflect.Float64:
return fmt.Sprintf("%v", value.Float())
case reflect.Complex64, reflect.Complex128:
return fmt.Sprintf("%v", value.Complex())
case reflect.Chan:
return fmt.Sprintf("0x%x", value.Pointer())
case reflect.Func:
return fmt.Sprintf("0x%x", value.Pointer())
case reflect.Ptr:
return formatValue(value.Elem(), indentation)
case reflect.Slice:
return truncateLongStrings(formatSlice(value, indentation))
case reflect.String:
return truncateLongStrings(formatString(value.String(), indentation))
case reflect.Array:
return truncateLongStrings(formatSlice(value, indentation))
case reflect.Map:
return truncateLongStrings(formatMap(value, indentation))
case reflect.Struct:
if value.Type() == timeType && value.CanInterface() {
t, _ := value.Interface().(time.Time)
return t.Format(time.RFC3339Nano)
}
return truncateLongStrings(formatStruct(value, indentation))
case reflect.Interface:
return formatInterface(value, indentation)
default:
if value.CanInterface() {
return truncateLongStrings(fmt.Sprintf("%#v", value.Interface()))
}
return truncateLongStrings(fmt.Sprintf("%#v", value))
}
}
func formatString(object interface{}, indentation uint) string {
if indentation == 1 {
s := fmt.Sprintf("%s", object)
components := strings.Split(s, "\n")
result := ""
for i, component := range components {
if i == 0 {
result += component
} else {
result += Indent + component
}
if i < len(components)-1 {
result += "\n"
}
}
return result
} else {
return fmt.Sprintf("%q", object)
}
}
func formatSlice(v reflect.Value, indentation uint) string {
if v.Kind() == reflect.Slice && v.Type().Elem().Kind() == reflect.Uint8 && isPrintableString(string(v.Bytes())) {
return formatString(v.Bytes(), indentation)
}
l := v.Len()
result := make([]string, l)
longest := 0
for i := 0; i < l; i++ {
result[i] = formatValue(v.Index(i), indentation+1)
if len(result[i]) > longest {
longest = len(result[i])
}
}
if longest > longFormThreshold {
indenter := strings.Repeat(Indent, int(indentation))
return fmt.Sprintf("[\n%s%s,\n%s]", indenter+Indent, strings.Join(result, ",\n"+indenter+Indent), indenter)
}
return fmt.Sprintf("[%s]", strings.Join(result, ", "))
}
func formatMap(v reflect.Value, indentation uint) string {
l := v.Len()
result := make([]string, l)
longest := 0
for i, key := range v.MapKeys() {
value := v.MapIndex(key)
result[i] = fmt.Sprintf("%s: %s", formatValue(key, indentation+1), formatValue(value, indentation+1))
if len(result[i]) > longest {
longest = len(result[i])
}
}
if longest > longFormThreshold {
indenter := strings.Repeat(Indent, int(indentation))
return fmt.Sprintf("{\n%s%s,\n%s}", indenter+Indent, strings.Join(result, ",\n"+indenter+Indent), indenter)
}
return fmt.Sprintf("{%s}", strings.Join(result, ", "))
}
func formatStruct(v reflect.Value, indentation uint) string {
t := v.Type()
l := v.NumField()
result := []string{}
longest := 0
for i := 0; i < l; i++ {
structField := t.Field(i)
fieldEntry := v.Field(i)
representation := fmt.Sprintf("%s: %s", structField.Name, formatValue(fieldEntry, indentation+1))
result = append(result, representation)
if len(representation) > longest {
longest = len(representation)
}
}
if longest > longFormThreshold {
indenter := strings.Repeat(Indent, int(indentation))
return fmt.Sprintf("{\n%s%s,\n%s}", indenter+Indent, strings.Join(result, ",\n"+indenter+Indent), indenter)
}
return fmt.Sprintf("{%s}", strings.Join(result, ", "))
}
func formatInterface(v reflect.Value, indentation uint) string {
return fmt.Sprintf("<%s>%s", formatType(v.Elem()), formatValue(v.Elem(), indentation))
}
func isNilValue(a reflect.Value) bool {
switch a.Kind() {
case reflect.Invalid:
return true
case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Ptr, reflect.Slice:
return a.IsNil()
}
return false
}
/*
Returns true when the string is entirely made of printable runes, false otherwise.
*/
func isPrintableString(str string) bool {
for _, runeValue := range str {
if !strconv.IsPrint(runeValue) {
return false
}
}
return true
}
golang-gomega-1.27.10/format/format_suite_test.go 0000664 0000000 0000000 00000000302 14462163431 0021744 0 ustar 00root root 0000000 0000000 package format_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"testing"
)
func TestFormat(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Format Suite")
}
golang-gomega-1.27.10/format/format_test.go 0000664 0000000 0000000 00000073572 14462163431 0020556 0 ustar 00root root 0000000 0000000 package format_test
import (
"context"
"fmt"
"strings"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
//recursive struct
const truncateHelpText = `
Gomega truncated this representation as it exceeds 'format.MaxLength'.
Consider having the object provide a custom 'GomegaStringer' representation
or adjust the parameters in Gomega's 'format' package.
Learn more here: https://onsi.github.io/gomega/#adjusting-output
`
type StringAlias string
type ByteAlias []byte
type IntAlias int
type AStruct struct {
Exported string
}
type SimpleStruct struct {
Name string
Enumeration int
Veritas bool
Data []byte
secret uint32
}
type ComplexStruct struct {
Strings []string
SimpleThings []*SimpleStruct
DataMaps map[int]ByteAlias
}
type SecretiveStruct struct {
boolValue bool
intValue int
uintValue uint
uintptrValue uintptr
floatValue float32
complexValue complex64
chanValue chan bool
funcValue func()
pointerValue *int
sliceValue []string
byteSliceValue []byte
stringValue string
arrValue [3]int
byteArrValue [3]byte
mapValue map[string]int
structValue AStruct
interfaceValue interface{}
}
type CustomFormatted struct {
Data string
Count int
}
type NotCustomFormatted struct {
Data string
Count int
}
type CustomError struct {
Details string
}
var _ error = &CustomError{}
func (c *CustomError) Error() string {
return c.Details
}
func customFormatter(obj interface{}) (string, bool) {
cf, ok := obj.(CustomFormatted)
if !ok {
return "", false
}
return fmt.Sprintf("%s (%d)", cf.Data, cf.Count), true
}
type GoStringer struct {
}
func (g GoStringer) GoString() string {
return "go-string"
}
func (g GoStringer) String() string {
return "string"
}
type Stringer struct {
}
func (g Stringer) String() string {
return "string"
}
type gomegaStringer struct {
}
func (g gomegaStringer) GomegaString() string {
return "gomegastring"
}
type gomegaStringerLong struct {
}
func (g gomegaStringerLong) GomegaString() string {
return strings.Repeat("s", MaxLength*2)
}
type gomegaStringerMultiline struct {
}
func (g gomegaStringerMultiline) GomegaString() string {
return "A\nB\nC"
}
var _ = Describe("Format", func() {
match := func(typeRepresentation string, valueRepresentation string, args ...interface{}) types.GomegaMatcher {
if len(args) > 0 {
valueRepresentation = fmt.Sprintf(valueRepresentation, args...)
}
return Equal(fmt.Sprintf("%s<%s>: %s", Indent, typeRepresentation, valueRepresentation))
}
matchRegexp := func(typeRepresentation string, valueRepresentation string, args ...interface{}) types.GomegaMatcher {
if len(args) > 0 {
valueRepresentation = fmt.Sprintf(valueRepresentation, args...)
}
return MatchRegexp(fmt.Sprintf("%s<%s>: %s", Indent, typeRepresentation, valueRepresentation))
}
hashMatchingRegexp := func(entries ...string) string {
entriesSwitch := "(" + strings.Join(entries, "|") + ")"
arr := make([]string, len(entries))
for i := range arr {
arr[i] = entriesSwitch
}
return "{\\s*" + strings.Join(arr, ",\\s* ") + ",?\\s*}"
}
Describe("Message", func() {
Context("with only an actual value", func() {
BeforeEach(func() {
MaxLength = 4000
})
It("should print out an indented formatted representation of the value and the message", func() {
Expect(Message(3, "to be three.")).Should(Equal("Expected\n : 3\nto be three."))
})
It("should print out an indented formatted representation of the value and the message, and trucate it when too long", func() {
tooLong := strings.Repeat("s", MaxLength+1)
tooLongResult := strings.Repeat("s", MaxLength) + "...\n" + truncateHelpText
Expect(Message(tooLong, "to be truncated")).Should(Equal("Expected\n : " + tooLongResult + "\nto be truncated"))
})
It("should print out an indented formatted representation of the value and the message, and not trucate it when MaxLength = 0", func() {
MaxLength = 0
tooLong := strings.Repeat("s", MaxLength+1)
Expect(Message(tooLong, "to be truncated")).Should(Equal("Expected\n : " + tooLong + "\nto be truncated"))
})
})
Context("with an actual and an expected value", func() {
It("should print out an indented formatted representatino of both values, and the message", func() {
Expect(Message(3, "to equal", 4)).Should(Equal("Expected\n : 3\nto equal\n : 4"))
})
})
})
Describe("MessageWithDiff", func() {
It("shows the exact point where two long strings differ", func() {
stringWithB := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
stringWithZ := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaazaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedLongStringFailureMessage))
})
It("truncates the start of long strings that differ only at their end", func() {
stringWithB := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab"
stringWithZ := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaz"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedTruncatedStartStringFailureMessage))
})
It("truncates the start of long strings that differ only in length", func() {
smallString := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
largeString := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Expect(MessageWithDiff(largeString, "to equal", smallString)).Should(Equal(expectedTruncatedStartSizeFailureMessage))
Expect(MessageWithDiff(smallString, "to equal", largeString)).Should(Equal(expectedTruncatedStartSizeSwappedFailureMessage))
})
It("truncates the end of long strings that differ only at their start", func() {
stringWithB := "baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
stringWithZ := "zaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedTruncatedEndStringFailureMessage))
})
It("handles multi-byte sequences correctly", func() {
stringA := "• abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz1"
stringB := "• abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
Expect(MessageWithDiff(stringA, "to equal", stringB)).Should(Equal(expectedTruncatedMultiByteFailureMessage))
})
It("prints special characters", func() {
stringA := "\n"
stringB := "something_else"
Expect(MessageWithDiff(stringA, "to equal", stringB)).Should(Equal(expectedSpecialCharacterFailureMessage))
})
It("handles negative padding length", func() {
stringWithB := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
stringWithZ := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaazaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
longMessage := "to equal very long message"
Expect(MessageWithDiff(stringWithB, longMessage, stringWithZ)).Should(Equal(expectedDiffLongMessage))
})
Context("With truncated diff disabled", func() {
BeforeEach(func() {
TruncatedDiff = false
})
AfterEach(func() {
TruncatedDiff = true
})
It("should show the full diff", func() {
stringWithB := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
stringWithZ := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaazaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedFullFailureDiff))
})
})
Context("With alternate diff lengths", func() {
initialValue := TruncateThreshold // 50 by default
BeforeEach(func() {
TruncateThreshold = 10000
})
AfterEach(func() {
TruncateThreshold = initialValue
})
It("should show the full diff when truncate threshold is increased beyond length of strings", func() {
stringWithB := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
stringWithZ := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaazaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedFullFailureDiff))
})
})
Context("with alternative number of characters to include around mismatch", func() {
initialValue := CharactersAroundMismatchToInclude // 5 by default
BeforeEach(func() {
CharactersAroundMismatchToInclude = 10
})
AfterEach(func() {
CharactersAroundMismatchToInclude = initialValue
})
It("it shows more characters around a line length mismatch", func() {
smallString := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
largeString := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Expect(MessageWithDiff(largeString, "to equal", smallString)).Should(Equal(expectedTruncatedStartSizeFailureMessageExtraDiff))
Expect(MessageWithDiff(smallString, "to equal", largeString)).Should(Equal(expectedTruncatedStartSizeSwappedFailureMessageExtraDiff))
})
})
Describe("At extremes of configurable values", func() {
Context("with zero-length threshold", func() {
initialValue := TruncateThreshold // 50 by default
BeforeEach(func() {
TruncateThreshold = 0
})
AfterEach(func() {
TruncateThreshold = initialValue
})
It("should show the full diff when truncate threshold is increased beyond length of strings", func() {
stringWithB := "aba"
stringWithZ := "aza"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedDiffSmallThreshold))
})
})
Context("with zero characters around mismatch", func() {
initialValue := CharactersAroundMismatchToInclude // 5 by default
BeforeEach(func() {
CharactersAroundMismatchToInclude = 0
})
AfterEach(func() {
CharactersAroundMismatchToInclude = initialValue
})
It("", func() {
stringWithB := "aba"
stringWithZ := "aza"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedDiffZeroMismatch))
})
})
Context("with zero-length threshold and zero characters around mismatch", func() {
initialCharactersAroundMismatch := CharactersAroundMismatchToInclude
initialTruncateThreshold := TruncateThreshold
BeforeEach(func() {
CharactersAroundMismatchToInclude = 0
TruncateThreshold = 0
})
AfterEach(func() {
CharactersAroundMismatchToInclude = initialCharactersAroundMismatch
TruncateThreshold = initialTruncateThreshold
})
It("", func() {
stringWithB := "aba"
stringWithZ := "aza"
Expect(MessageWithDiff(stringWithB, "to equal", stringWithZ)).Should(Equal(expectedDiffSmallThresholdZeroMismatch))
})
})
})
})
Describe("IndentString", func() {
It("should indent the string", func() {
Expect(IndentString("foo\n bar\nbaz", 2)).Should(Equal(" foo\n bar\n baz"))
})
})
Describe("Object", func() {
Describe("formatting boolean values", func() {
It("should give the type and format values correctly", func() {
Expect(Object(true, 1)).Should(match("bool", "true"))
Expect(Object(false, 1)).Should(match("bool", "false"))
})
})
Describe("formatting numbers", func() {
It("should give the type and format values correctly", func() {
Expect(Object(int(3), 1)).Should(match("int", "3"))
Expect(Object(int8(3), 1)).Should(match("int8", "3"))
Expect(Object(int16(3), 1)).Should(match("int16", "3"))
Expect(Object(int32(3), 1)).Should(match("int32", "3"))
Expect(Object(int64(3), 1)).Should(match("int64", "3"))
Expect(Object(uint(3), 1)).Should(match("uint", "3"))
Expect(Object(uint8(3), 1)).Should(match("uint8", "3"))
Expect(Object(uint16(3), 1)).Should(match("uint16", "3"))
Expect(Object(uint32(3), 1)).Should(match("uint32", "3"))
Expect(Object(uint64(3), 1)).Should(match("uint64", "3"))
})
It("should handle uintptr differently", func() {
Expect(Object(uintptr(3), 1)).Should(match("uintptr", "0x3"))
})
})
Describe("formatting channels", func() {
It("should give the type and format values correctly", func() {
c := make(chan<- bool, 3)
c <- true
c <- false
Expect(Object(c, 1)).Should(match("chan<- bool | len:2, cap:3", "%v", c))
})
})
Describe("formatting strings", func() {
It("should give the type and format values correctly", func() {
s := "a\nb\nc"
Expect(Object(s, 1)).Should(match("string", `a
b
c`))
})
})
Describe("formatting []byte slices", func() {
When("the slice is made of printable bytes", func() {
It("should present it as string", func() {
b := []byte("a b c")
Expect(Object(b, 1)).Should(matchRegexp(`\[\]uint8 \| len:5, cap:\d+`, `a b c`))
})
})
When("the slice contains non-printable bytes", func() {
It("should present it as slice", func() {
b := []byte("a b c\n\x01\x02\x03\xff\x1bH")
Expect(Object(b, 1)).Should(matchRegexp(`\[\]uint8 \| len:12, cap:\d+`, `\[97, 32, 98, 32, 99, 10, 1, 2, 3, 255, 27, 72\]`))
})
})
})
Describe("formatting functions", func() {
It("should give the type and format values correctly", func() {
f := func(a string, b []int) ([]byte, error) {
return []byte("abc"), nil
}
Expect(Object(f, 1)).Should(match("func(string, []int) ([]uint8, error)", "%v", f))
})
})
Describe("formatting pointers", func() {
It("should give the type and dereference the value to format it correctly", func() {
a := 3
Expect(Object(&a, 1)).Should(match(fmt.Sprintf("*int | %p", &a), "3"))
})
When("there are pointers to pointers...", func() {
It("should recursively deference the pointer until it gets to a value", func() {
a := 3
var b *int
var c **int
var d ***int
b = &a
c = &b
d = &c
Expect(Object(d, 1)).Should(match(fmt.Sprintf("***int | %p", d), "3"))
})
})
When("the pointer points to nil", func() {
It("should say nil and not explode", func() {
var a *AStruct
Expect(Object(a, 1)).Should(match("*format_test.AStruct | 0x0", "nil"))
})
})
})
Describe("formatting arrays", func() {
It("should give the type and format values correctly", func() {
w := [3]string{"Jed Bartlet", "Toby Ziegler", "CJ Cregg"}
Expect(Object(w, 1)).Should(match("[3]string", `["Jed Bartlet", "Toby Ziegler", "CJ Cregg"]`))
})
Context("with byte arrays", func() {
It("should give the type and format values correctly", func() {
w := [3]byte{17, 28, 19}
Expect(Object(w, 1)).Should(match("[3]uint8", `[17, 28, 19]`))
})
})
})
Describe("formatting slices", func() {
It("should include the length and capacity in the type information", func() {
s := make([]bool, 3, 4)
Expect(Object(s, 1)).Should(match("[]bool | len:3, cap:4", "[false, false, false]"))
})
When("the slice contains long entries", func() {
It("should format the entries with newlines", func() {
w := []string{"Josiah Edward Bartlet", "Toby Ziegler", "CJ Cregg"}
expected := `[
"Josiah Edward Bartlet",
"Toby Ziegler",
"CJ Cregg",
]`
Expect(Object(w, 1)).Should(match("[]string | len:3, cap:3", expected))
})
})
})
Describe("formatting maps", func() {
It("should include the length in the type information", func() {
m := make(map[int]bool, 5)
m[3] = true
m[4] = false
Expect(Object(m, 1)).Should(matchRegexp(`map\[int\]bool \| len:2`, hashMatchingRegexp("3: true", "4: false")))
})
When("the slice contains long entries", func() {
It("should format the entries with newlines", func() {
m := map[string][]byte{}
m["Josiah Edward Bartlet"] = []byte("Martin Sheen")
m["Toby Ziegler"] = []byte("Richard Schiff")
m["CJ Cregg"] = []byte("Allison Janney")
expected := `{
("Josiah Edward Bartlet": "Martin Sheen"|"Toby Ziegler": "Richard Schiff"|"CJ Cregg": "Allison Janney"),
("Josiah Edward Bartlet": "Martin Sheen"|"Toby Ziegler": "Richard Schiff"|"CJ Cregg": "Allison Janney"),
("Josiah Edward Bartlet": "Martin Sheen"|"Toby Ziegler": "Richard Schiff"|"CJ Cregg": "Allison Janney"),
}`
Expect(Object(m, 1)).Should(matchRegexp(`map\[string\]\[\]uint8 \| len:3`, expected))
})
})
})
Describe("formatting structs", func() {
It("should include the struct name and the field names", func() {
s := SimpleStruct{
Name: "Oswald",
Enumeration: 17,
Veritas: true,
Data: []byte("datum"),
secret: 1983,
}
Expect(Object(s, 1)).Should(match("format_test.SimpleStruct", `{Name: "Oswald", Enumeration: 17, Veritas: true, Data: "datum", secret: 1983}`))
})
When("the struct contains long entries", func() {
It("should format the entries with new lines", func() {
s := &SimpleStruct{
Name: "Mithrandir Gandalf Greyhame",
Enumeration: 2021,
Veritas: true,
Data: []byte("wizard"),
secret: 3,
}
Expect(Object(s, 1)).Should(match(fmt.Sprintf("*format_test.SimpleStruct | %p", s), `{
Name: "Mithrandir Gandalf Greyhame",
Enumeration: 2021,
Veritas: true,
Data: "wizard",
secret: 3,
}`))
})
})
})
Describe("formatting nil values", func() {
It("should print out nil", func() {
Expect(Object(nil, 1)).Should(match("nil", "nil"))
var typedNil *AStruct
Expect(Object(typedNil, 1)).Should(match("*format_test.AStruct | 0x0", "nil"))
var c chan<- bool
Expect(Object(c, 1)).Should(match("chan<- bool | len:0, cap:0", "nil"))
var s []string
Expect(Object(s, 1)).Should(match("[]string | len:0, cap:0", "nil"))
var m map[string]bool
Expect(Object(m, 1)).Should(match("map[string]bool | len:0", "nil"))
})
})
Describe("formatting aliased types", func() {
It("should print out the correct alias type", func() {
Expect(Object(StringAlias("alias"), 1)).Should(match("format_test.StringAlias", `alias`))
Expect(Object(ByteAlias("alias"), 1)).Should(matchRegexp(`format_test\.ByteAlias \| len:5, cap:\d+`, `alias`))
Expect(Object(IntAlias(3), 1)).Should(match("format_test.IntAlias", "3"))
})
})
Describe("handling nested things", func() {
It("should produce a correctly nested representation", func() {
s := ComplexStruct{
Strings: []string{"lots", "of", "short", "strings"},
SimpleThings: []*SimpleStruct{
{"short", 7, true, []byte("succinct"), 17},
{"something longer", 427, true, []byte("designed to wrap around nicely"), 30},
},
DataMaps: map[int]ByteAlias{
17: ByteAlias("some substantially longer chunks of data"),
1138: ByteAlias("that should make things wrap"),
},
}
expected := `{
Strings: \["lots", "of", "short", "strings"\],
SimpleThings: \[
{Name: "short", Enumeration: 7, Veritas: true, Data: "succinct", secret: 17},
{
Name: "something longer",
Enumeration: 427,
Veritas: true,
Data: "designed to wrap around nicely",
secret: 30,
},
\],
DataMaps: {
(17: "some substantially longer chunks of data"|1138: "that should make things wrap"),
(17: "some substantially longer chunks of data"|1138: "that should make things wrap"),
},
}`
Expect(Object(s, 1)).Should(matchRegexp(`format_test\.ComplexStruct`, expected))
})
})
Describe("formatting nested interface{} types", func() {
It("should print out the types of the container and value", func() {
Expect(Object([]interface{}{"foo"}, 1)).
To(match("[]interface {} | len:1, cap:1", `["foo"]`))
Expect(Object(map[string]interface{}{"foo": true}, 1)).
To(match("map[string]interface {} | len:1", `{"foo": true}`))
Expect(Object(struct{ A interface{} }{A: 1}, 1)).
To(match("struct { A interface {} }", "{A: 1}"))
v := struct{ A interface{} }{A: struct{ B string }{B: "foo"}}
Expect(Object(v, 1)).To(match(`struct { A interface {} }`, `{
A: {B: "foo"},
}`))
})
})
Describe("formatting times", func() {
It("should format time as RFC3339", func() {
t := time.Date(2016, 10, 31, 9, 57, 23, 12345, time.UTC)
Expect(Object(t, 1)).Should(match("time.Time", `2016-10-31T09:57:23.000012345Z`))
})
})
Describe("formatting errors", func() {
It("should include the error() representation", func() {
err := fmt.Errorf("whoops: %w", fmt.Errorf("welp: %w", fmt.Errorf("ruh roh")))
Expect(Object(err, 1)).Should(MatchRegexp(` \<\*fmt\.wrapError \| 0x[0-9a-f]*\>\:
whoops\: welp\: ruh roh
\{
msg\: "whoops\: welp\: ruh roh",
err\: \<\*fmt.wrapError \| 0x[0-9a-f]*\>\{
msg\: "welp\: ruh roh",
err\: \<\*errors.errorString \| 0x[0-9a-f]*\>\{s\: "ruh roh"\},
\},
\}`))
})
It("should not panic if the error is a boxed nil", func() {
var err *CustomError
Expect(Object(err, 1)).Should(Equal(" <*format_test.CustomError | 0x0>: nil"))
})
})
})
Describe("Handling unexported fields in structs", func() {
It("should handle all the various types correctly", func() {
a := int(5)
s := SecretiveStruct{
boolValue: true,
intValue: 3,
uintValue: 4,
uintptrValue: 5,
floatValue: 6.0,
complexValue: complex(5.0, 3.0),
chanValue: make(chan bool, 2),
funcValue: func() {},
pointerValue: &a,
sliceValue: []string{"string", "slice"},
byteSliceValue: []byte("bytes"),
stringValue: "a string",
arrValue: [3]int{11, 12, 13},
byteArrValue: [3]byte{17, 20, 32},
mapValue: map[string]int{"a key": 20, "b key": 30},
structValue: AStruct{"exported"},
interfaceValue: map[string]int{"a key": 17},
}
expected := fmt.Sprintf(`{
boolValue: true,
intValue: 3,
uintValue: 4,
uintptrValue: 0x5,
floatValue: 6,
complexValue: \(5\+3i\),
chanValue: %p,
funcValue: %p,
pointerValue: 5,
sliceValue: \["string", "slice"\],
byteSliceValue: "bytes",
stringValue: "a string",
arrValue: \[11, 12, 13\],
byteArrValue: \[17, 20, 32\],
mapValue: %s,
structValue: {Exported: "exported"},
interfaceValue: {"a key": 17},
}`, s.chanValue, s.funcValue, hashMatchingRegexp(`"a key": 20`, `"b key": 30`))
Expect(Object(s, 1)).Should(matchRegexp(`format_test\.SecretiveStruct`, expected))
})
})
Describe("Handling interfaces", func() {
It("should unpack the interface", func() {
outerHash := map[string]interface{}{}
innerHash := map[string]int{}
innerHash["inner"] = 3
outerHash["integer"] = 2
outerHash["map"] = innerHash
expected := hashMatchingRegexp(`"integer": 2`, `"map": {"inner": 3}`)
Expect(Object(outerHash, 1)).Should(matchRegexp(`map\[string\]interface {} \| len:2`, expected))
})
})
Describe("Handling recursive things", func() {
It("should not go crazy...", func() {
m := map[string]interface{}{}
m["integer"] = 2
m["map"] = m
Expect(Object(m, 1)).Should(ContainSubstring("..."))
})
It("really should not go crazy...", func() {
type complexKey struct {
Value map[interface{}]int
}
complexObject := complexKey{}
complexObject.Value = make(map[interface{}]int)
complexObject.Value[&complexObject] = 2
Expect(Object(complexObject, 1)).Should(ContainSubstring("..."))
})
})
Describe("When instructed to use the Stringer representation", func() {
BeforeEach(func() {
UseStringerRepresentation = true
})
AfterEach(func() {
UseStringerRepresentation = false
})
When("passed a GoStringer", func() {
It("should use what GoString() returns", func() {
Expect(Object(GoStringer{}, 1)).Should(ContainSubstring(": go-string"))
})
})
When("passed a stringer", func() {
It("should use what String() returns", func() {
Expect(Object(Stringer{}, 1)).Should(ContainSubstring(": string"))
})
})
When("passed a GomegaStringer", func() {
It("should use what GomegaString() returns", func() {
Expect(Object(gomegaStringer{}, 1)).Should(ContainSubstring(": gomegastring"))
UseStringerRepresentation = false
Expect(Object(gomegaStringer{}, 1)).Should(ContainSubstring(": gomegastring"))
})
It("should use what GomegaString() returns, disregarding MaxLength", func() {
Expect(Object(gomegaStringerLong{}, 1)).Should(Equal(" : " + strings.Repeat("s", MaxLength*2)))
UseStringerRepresentation = false
Expect(Object(gomegaStringerLong{}, 1)).Should(Equal(" : " + strings.Repeat("s", MaxLength*2)))
})
It("should indent what the GomegaString() returns", func() {
Expect(Object(gomegaStringerMultiline{}, 1)).Should(Equal(" : A\n B\n C"))
})
})
Describe("when used with a registered CustomFormatter", func() {
It("pases objects through the custom formatter and uses the returned format, if handled", func() {
cf := CustomFormatted{"bob", 17}
ncf := NotCustomFormatted{"bob", 17}
Expect(Object(cf, 0)).To(Equal(": {Data: bob, Count: 17}"))
Expect(Object(ncf, 0)).To(Equal(": {Data: bob, Count: 17}"))
key := RegisterCustomFormatter(customFormatter)
Expect(Object(cf, 0)).To(Equal(": bob (17)"))
Expect(Object(ncf, 0)).To(Equal(": {Data: bob, Count: 17}"))
UnregisterCustomFormatter(key)
Expect(Object(cf, 0)).To(Equal(": {Data: bob, Count: 17}"))
Expect(Object(ncf, 0)).To(Equal(": {Data: bob, Count: 17}"))
})
It("indents CustomFormatter output correctly", func() {
cf := CustomFormatted{"hey\nbob", 17}
DeferCleanup(UnregisterCustomFormatter, RegisterCustomFormatter(func(value interface{}) (string, bool) {
cf, ok := value.(CustomFormatted)
if !ok {
return "", false
}
return fmt.Sprintf("The Data:\n%s\nThe Count:%d", cf.Data, cf.Count), true
}))
Ω(Object(cf, 1)).Should(Equal(" : The Data:\n hey\n bob\n The Count:17"))
type Wrapped struct {
MyObject CustomFormatted
OuterCount int
}
wrapped := Wrapped{
MyObject: cf,
OuterCount: 10,
}
Ω(Object(wrapped, 1)).Should(Equal(" : {\n MyObject: The Data:\n hey\n bob\n The Count:17,\n OuterCount: 10,\n }"))
})
})
})
Describe("Printing a context.Context field", func() {
type structWithContext struct {
Context context.Context
Value string
}
objWithContext := structWithContext{Value: "some-value", Context: context.TODO()}
It("Suppresses the content by default", func() {
Expect(Object(objWithContext, 1)).Should(ContainSubstring(""))
})
It("Doesn't suppress the context if it's the object being printed", func() {
Expect(Object(context.TODO(), 1)).ShouldNot(MatchRegexp("^.*$"))
})
Context("PrintContextObjects is set", func() {
BeforeEach(func() {
PrintContextObjects = true
})
AfterEach(func() {
PrintContextObjects = false
})
It("Prints the context", func() {
Expect(Object(objWithContext, 1)).ShouldNot(ContainSubstring(""))
})
})
})
})
var expectedLongStringFailureMessage = strings.TrimSpace(`
Expected
: "...aaaaabaaaaa..."
to equal |
: "...aaaaazaaaaa..."
`)
var expectedTruncatedEndStringFailureMessage = strings.TrimSpace(`
Expected
: "baaaaa..."
to equal |
: "zaaaaa..."
`)
var expectedTruncatedStartStringFailureMessage = strings.TrimSpace(`
Expected
: "...aaaaab"
to equal |
: "...aaaaaz"
`)
var expectedTruncatedStartSizeFailureMessage = strings.TrimSpace(`
Expected
: "...aaaaaa"
to equal |
: "...aaaaa"
`)
var expectedTruncatedStartSizeFailureMessageExtraDiff = strings.TrimSpace(`
Expected
: "...aaaaaaaaaaa"
to equal |
: "...aaaaaaaaaa"
`)
var expectedTruncatedStartSizeSwappedFailureMessage = strings.TrimSpace(`
Expected
: "...aaaa"
to equal |
: "...aaaaa"
`)
var expectedTruncatedStartSizeSwappedFailureMessageExtraDiff = strings.TrimSpace(`
Expected
: "...aaaaaaaaa"
to equal |
: "...aaaaaaaaaa"
`)
var expectedTruncatedMultiByteFailureMessage = strings.TrimSpace(`
Expected
: "...tuvwxyz1"
to equal |
: "...tuvwxyz"
`)
var expectedFullFailureDiff = strings.TrimSpace(`
Expected
: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
to equal
: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaazaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
`)
var expectedSpecialCharacterFailureMessage = strings.TrimSpace(`
Expected
: \n
to equal
: something_else
`)
var expectedDiffSmallThreshold = strings.TrimSpace(`
Expected
: "aba"
to equal |
: "aza"
`)
var expectedDiffZeroMismatch = strings.TrimSpace(`
Expected
: aba
to equal
: aza
`)
var expectedDiffSmallThresholdZeroMismatch = strings.TrimSpace(`
Expected
: "...b..."
to equal |
: "...z..."
`)
var expectedDiffLongMessage = strings.TrimSpace(`
Expected
: "...aaaaabaaaaa..."
to equal very long message
: "...aaaaazaaaaa..."
`)
golang-gomega-1.27.10/gbytes/ 0000775 0000000 0000000 00000000000 14462163431 0015667 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gbytes/buffer.go 0000664 0000000 0000000 00000013272 14462163431 0017474 0 ustar 00root root 0000000 0000000 /*
Package gbytes provides a buffer that supports incrementally detecting input.
You use gbytes.Buffer with the gbytes.Say matcher. When Say finds a match, it fastforwards the buffer's read cursor to the end of that match.
Subsequent matches against the buffer will only operate against data that appears *after* the read cursor.
The read cursor is an opaque implementation detail that you cannot access. You should use the Say matcher to sift through the buffer. You can always
access the entire buffer's contents with Contents().
*/
package gbytes
import (
"errors"
"fmt"
"io"
"regexp"
"sync"
"time"
)
/*
gbytes.Buffer implements an io.Writer and can be used with the gbytes.Say matcher.
You should only use a gbytes.Buffer in test code. It stores all writes in an in-memory buffer - behavior that is inappropriate for production code!
*/
type Buffer struct {
contents []byte
readCursor uint64
lock *sync.Mutex
detectCloser chan interface{}
closed bool
}
/*
NewBuffer returns a new gbytes.Buffer
*/
func NewBuffer() *Buffer {
return &Buffer{
lock: &sync.Mutex{},
}
}
/*
BufferWithBytes returns a new gbytes.Buffer seeded with the passed in bytes
*/
func BufferWithBytes(bytes []byte) *Buffer {
return &Buffer{
lock: &sync.Mutex{},
contents: bytes,
}
}
/*
BufferReader returns a new gbytes.Buffer that wraps a reader. The reader's contents are read into
the Buffer via io.Copy
*/
func BufferReader(reader io.Reader) *Buffer {
b := &Buffer{
lock: &sync.Mutex{},
}
go func() {
io.Copy(b, reader)
b.Close()
}()
return b
}
/*
Write implements the io.Writer interface
*/
func (b *Buffer) Write(p []byte) (n int, err error) {
b.lock.Lock()
defer b.lock.Unlock()
if b.closed {
return 0, errors.New("attempt to write to closed buffer")
}
b.contents = append(b.contents, p...)
return len(p), nil
}
/*
Read implements the io.Reader interface. It advances the
cursor as it reads.
*/
func (b *Buffer) Read(d []byte) (int, error) {
b.lock.Lock()
defer b.lock.Unlock()
if uint64(len(b.contents)) <= b.readCursor {
return 0, io.EOF
}
n := copy(d, b.contents[b.readCursor:])
b.readCursor += uint64(n)
return n, nil
}
/*
Clear clears out the buffer's contents
*/
func (b *Buffer) Clear() error {
b.lock.Lock()
defer b.lock.Unlock()
if b.closed {
return errors.New("attempt to clear closed buffer")
}
b.contents = []byte{}
b.readCursor = 0
return nil
}
/*
Close signifies that the buffer will no longer be written to
*/
func (b *Buffer) Close() error {
b.lock.Lock()
defer b.lock.Unlock()
b.closed = true
return nil
}
/*
Closed returns true if the buffer has been closed
*/
func (b *Buffer) Closed() bool {
b.lock.Lock()
defer b.lock.Unlock()
return b.closed
}
/*
Contents returns all data ever written to the buffer.
*/
func (b *Buffer) Contents() []byte {
b.lock.Lock()
defer b.lock.Unlock()
contents := make([]byte, len(b.contents))
copy(contents, b.contents)
return contents
}
/*
Detect takes a regular expression and returns a channel.
The channel will receive true the first time data matching the regular expression is written to the buffer.
The channel is subsequently closed and the buffer's read-cursor is fast-forwarded to just after the matching region.
You typically don't need to use Detect and should use the ghttp.Say matcher instead. Detect is useful, however, in cases where your code must
be branch and handle different outputs written to the buffer.
For example, consider a buffer hooked up to the stdout of a client library. You may (or may not, depending on state outside of your control) need to authenticate the client library.
You could do something like:
select {
case <-buffer.Detect("You are not logged in"):
//log in
case <-buffer.Detect("Success"):
//carry on
case <-time.After(time.Second):
//welp
}
buffer.CancelDetects()
You should always call CancelDetects after using Detect. This will close any channels that have not detected and clean up the goroutines that were spawned to support them.
Finally, you can pass detect a format string followed by variadic arguments. This will construct the regexp using fmt.Sprintf.
*/
func (b *Buffer) Detect(desired string, args ...interface{}) chan bool {
formattedRegexp := desired
if len(args) > 0 {
formattedRegexp = fmt.Sprintf(desired, args...)
}
re := regexp.MustCompile(formattedRegexp)
b.lock.Lock()
defer b.lock.Unlock()
if b.detectCloser == nil {
b.detectCloser = make(chan interface{})
}
closer := b.detectCloser
response := make(chan bool)
go func() {
ticker := time.NewTicker(10 * time.Millisecond)
defer ticker.Stop()
defer close(response)
for {
select {
case <-ticker.C:
b.lock.Lock()
data, cursor := b.contents[b.readCursor:], b.readCursor
loc := re.FindIndex(data)
b.lock.Unlock()
if loc != nil {
response <- true
b.lock.Lock()
newCursorPosition := cursor + uint64(loc[1])
if newCursorPosition >= b.readCursor {
b.readCursor = newCursorPosition
}
b.lock.Unlock()
return
}
case <-closer:
return
}
}
}()
return response
}
/*
CancelDetects cancels any pending detects and cleans up their goroutines. You should always call this when you're done with a set of Detect channels.
*/
func (b *Buffer) CancelDetects() {
b.lock.Lock()
defer b.lock.Unlock()
close(b.detectCloser)
b.detectCloser = nil
}
func (b *Buffer) didSay(re *regexp.Regexp) (bool, []byte) {
b.lock.Lock()
defer b.lock.Unlock()
unreadBytes := b.contents[b.readCursor:]
copyOfUnreadBytes := make([]byte, len(unreadBytes))
copy(copyOfUnreadBytes, unreadBytes)
loc := re.FindIndex(unreadBytes)
if loc != nil {
b.readCursor += uint64(loc[1])
return true, copyOfUnreadBytes
}
return false, copyOfUnreadBytes
}
golang-gomega-1.27.10/gbytes/buffer_test.go 0000664 0000000 0000000 00000013376 14462163431 0020540 0 ustar 00root root 0000000 0000000 package gbytes_test
import (
"io"
"time"
. "github.com/onsi/gomega/gbytes"
"bytes"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
type SlowReader struct {
R io.Reader
D time.Duration
}
func (s SlowReader) Read(p []byte) (int, error) {
time.Sleep(s.D)
return s.R.Read(p)
}
var _ = Describe("Buffer", func() {
var buffer *Buffer
BeforeEach(func() {
buffer = NewBuffer()
})
Describe("dumping the entire contents of the buffer", func() {
It("should return everything that's been written", func() {
buffer.Write([]byte("abc"))
buffer.Write([]byte("def"))
Expect(buffer.Contents()).Should(Equal([]byte("abcdef")))
Expect(buffer).Should(Say("bcd"))
Expect(buffer.Contents()).Should(Equal([]byte("abcdef")))
})
})
Describe("creating a buffer with bytes", func() {
It("should create the buffer with the cursor set to the beginning", func() {
buffer := BufferWithBytes([]byte("abcdef"))
Expect(buffer.Contents()).Should(Equal([]byte("abcdef")))
Expect(buffer).Should(Say("abc"))
Expect(buffer).ShouldNot(Say("abc"))
Expect(buffer).Should(Say("def"))
})
})
Describe("creating a buffer that wraps a reader", func() {
Context("for a well-behaved reader", func() {
It("should buffer the contents of the reader", func() {
reader := bytes.NewBuffer([]byte("abcdef"))
buffer := BufferReader(reader)
Eventually(buffer).Should(Say("abc"))
Expect(buffer).ShouldNot(Say("abc"))
Eventually(buffer).Should(Say("def"))
Eventually(buffer.Closed).Should(BeTrue())
})
})
Context("for a slow reader", func() {
It("should allow Eventually to time out", func() {
slowReader := SlowReader{
R: bytes.NewBuffer([]byte("abcdef")),
D: time.Second,
}
buffer := BufferReader(slowReader)
failures := InterceptGomegaFailures(func() {
Eventually(buffer, 100*time.Millisecond).Should(Say("abc"))
})
Expect(failures).ShouldNot(BeEmpty())
fastReader := SlowReader{
R: bytes.NewBuffer([]byte("abcdef")),
D: time.Millisecond,
}
buffer = BufferReader(fastReader)
Eventually(buffer, 100*time.Millisecond).Should(Say("abc"))
Eventually(buffer.Closed).Should(BeTrue())
})
})
})
Describe("reading from a buffer", func() {
It("should read the current contents of the buffer", func() {
buffer := BufferWithBytes([]byte("abcde"))
dest := make([]byte, 3)
n, err := buffer.Read(dest)
Expect(err).ShouldNot(HaveOccurred())
Expect(n).Should(Equal(3))
Expect(string(dest)).Should(Equal("abc"))
dest = make([]byte, 3)
n, err = buffer.Read(dest)
Expect(err).ShouldNot(HaveOccurred())
Expect(n).Should(Equal(2))
Expect(string(dest[:n])).Should(Equal("de"))
n, err = buffer.Read(dest)
Expect(err).Should(Equal(io.EOF))
Expect(n).Should(Equal(0))
})
})
Describe("detecting regular expressions", func() {
It("should fire the appropriate channel when the passed in pattern matches, then close it", func() {
go func() {
time.Sleep(10 * time.Millisecond)
buffer.Write([]byte("abcde"))
}()
A := buffer.Detect("%s", "a.c")
B := buffer.Detect("def")
var gotIt bool
select {
case gotIt = <-A:
case <-B:
Fail("should not have gotten here")
case <-time.After(time.Second):
Fail("timed out waiting for detection")
}
Expect(gotIt).Should(BeTrue())
Eventually(A).Should(BeClosed())
buffer.Write([]byte("f"))
Eventually(B).Should(Receive())
Eventually(B).Should(BeClosed())
})
It("should fast-forward the buffer upon detection", func() {
buffer.Write([]byte("abcde"))
select {
case <-buffer.Detect("abc"):
case <-time.After(time.Second):
Fail("timed out waiting for detection")
}
Expect(buffer).ShouldNot(Say("abc"))
Expect(buffer).Should(Say("de"))
})
It("should only fast-forward the buffer when the channel is read, and only if doing so would not rewind it", func() {
buffer.Write([]byte("abcde"))
A := buffer.Detect("abc")
time.Sleep(20 * time.Millisecond) //give the goroutine a chance to detect and write to the channel
Expect(buffer).Should(Say("abcd"))
select {
case <-A:
case <-time.After(time.Second):
Fail("timed out waiting for detection")
}
Expect(buffer).ShouldNot(Say("d"))
Expect(buffer).Should(Say("e"))
Eventually(A).Should(BeClosed())
})
It("should be possible to cancel a detection", func() {
A := buffer.Detect("abc")
B := buffer.Detect("def")
buffer.CancelDetects()
buffer.Write([]byte("abcdef"))
Eventually(A).Should(BeClosed())
Eventually(B).Should(BeClosed())
Expect(buffer).Should(Say("bcde"))
select {
case <-buffer.Detect("f"):
case <-time.After(time.Second):
Fail("timed out waiting for detection")
}
})
})
Describe("clearing the buffer", func() {
It("should clear out the contents of the buffer", func() {
buffer.Write([]byte("abc"))
Expect(buffer).To(Say("ab"))
Expect(buffer.Clear()).To(Succeed())
Expect(buffer).NotTo(Say("c"))
Expect(buffer.Contents()).To(BeEmpty())
buffer.Write([]byte("123"))
Expect(buffer).To(Say("123"))
Expect(buffer.Contents()).To(Equal([]byte("123")))
})
It("should error when the buffer is closed", func() {
buffer.Write([]byte("abc"))
buffer.Close()
err := buffer.Clear()
Expect(err).To(HaveOccurred())
})
})
Describe("closing the buffer", func() {
It("should error when further write attempts are made", func() {
_, err := buffer.Write([]byte("abc"))
Expect(err).ShouldNot(HaveOccurred())
buffer.Close()
_, err = buffer.Write([]byte("def"))
Expect(err).Should(HaveOccurred())
Expect(buffer.Contents()).Should(Equal([]byte("abc")))
})
It("should be closed", func() {
Expect(buffer.Closed()).Should(BeFalse())
buffer.Close()
Expect(buffer.Closed()).Should(BeTrue())
})
})
})
golang-gomega-1.27.10/gbytes/gbuffer_suite_test.go 0000664 0000000 0000000 00000000302 14462163431 0022101 0 ustar 00root root 0000000 0000000 package gbytes_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"testing"
)
func TestGbytes(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Gbytes Suite")
}
golang-gomega-1.27.10/gbytes/io_wrappers.go 0000664 0000000 0000000 00000003731 14462163431 0020554 0 ustar 00root root 0000000 0000000 package gbytes
import (
"errors"
"io"
"time"
)
// ErrTimeout is returned by TimeoutCloser, TimeoutReader, and TimeoutWriter when the underlying Closer/Reader/Writer does not return within the specified timeout
var ErrTimeout = errors.New("timeout occurred")
// TimeoutCloser returns an io.Closer that wraps the passed-in io.Closer. If the underlying Closer fails to close within the allotted timeout ErrTimeout is returned.
func TimeoutCloser(c io.Closer, timeout time.Duration) io.Closer {
return timeoutReaderWriterCloser{c: c, d: timeout}
}
// TimeoutReader returns an io.Reader that wraps the passed-in io.Reader. If the underlying Reader fails to read within the allotted timeout ErrTimeout is returned.
func TimeoutReader(r io.Reader, timeout time.Duration) io.Reader {
return timeoutReaderWriterCloser{r: r, d: timeout}
}
// TimeoutWriter returns an io.Writer that wraps the passed-in io.Writer. If the underlying Writer fails to write within the allotted timeout ErrTimeout is returned.
func TimeoutWriter(w io.Writer, timeout time.Duration) io.Writer {
return timeoutReaderWriterCloser{w: w, d: timeout}
}
type timeoutReaderWriterCloser struct {
c io.Closer
w io.Writer
r io.Reader
d time.Duration
}
func (t timeoutReaderWriterCloser) Close() error {
done := make(chan struct{})
var err error
go func() {
err = t.c.Close()
close(done)
}()
select {
case <-done:
return err
case <-time.After(t.d):
return ErrTimeout
}
}
func (t timeoutReaderWriterCloser) Read(p []byte) (int, error) {
done := make(chan struct{})
var n int
var err error
go func() {
n, err = t.r.Read(p)
close(done)
}()
select {
case <-done:
return n, err
case <-time.After(t.d):
return 0, ErrTimeout
}
}
func (t timeoutReaderWriterCloser) Write(p []byte) (int, error) {
done := make(chan struct{})
var n int
var err error
go func() {
n, err = t.w.Write(p)
close(done)
}()
select {
case <-done:
return n, err
case <-time.After(t.d):
return 0, ErrTimeout
}
}
golang-gomega-1.27.10/gbytes/io_wrappers_test.go 0000664 0000000 0000000 00000007632 14462163431 0021617 0 ustar 00root root 0000000 0000000 package gbytes_test
import (
"fmt"
"io"
"time"
. "github.com/onsi/gomega/gbytes"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
type FakeCloser struct {
err error
duration time.Duration
}
func (f FakeCloser) Close() error {
time.Sleep(f.duration)
return f.err
}
type FakeReader struct {
err error
duration time.Duration
}
func (f FakeReader) Read(p []byte) (int, error) {
time.Sleep(f.duration)
if f.err != nil {
return 0, f.err
}
for i := 0; i < len(p); i++ {
p[i] = 'a'
}
return len(p), nil
}
type FakeWriter struct {
err error
duration time.Duration
}
func (f FakeWriter) Write(p []byte) (int, error) {
time.Sleep(f.duration)
if f.err != nil {
return 0, f.err
}
return len(p), nil
}
var _ = Describe("Io Wrappers", func() {
Describe("TimeoutCloser", func() {
var innerCloser io.Closer
var timeoutCloser io.Closer
JustBeforeEach(func() {
timeoutCloser = TimeoutCloser(innerCloser, 20*time.Millisecond)
})
When("the underlying Closer closes with no error", func() {
BeforeEach(func() {
innerCloser = FakeCloser{}
})
It("returns with no error", func() {
Expect(timeoutCloser.Close()).Should(Succeed())
})
})
When("the underlying Closer closes with an error", func() {
BeforeEach(func() {
innerCloser = FakeCloser{err: fmt.Errorf("boom")}
})
It("returns the error", func() {
Expect(timeoutCloser.Close()).Should(MatchError("boom"))
})
})
When("the underlying Closer hangs", func() {
BeforeEach(func() {
innerCloser = FakeCloser{
err: fmt.Errorf("boom"),
duration: time.Hour,
}
})
It("returns ErrTimeout", func() {
Expect(timeoutCloser.Close()).Should(MatchError(ErrTimeout))
})
})
})
Describe("TimeoutReader", func() {
var innerReader io.Reader
var timeoutReader io.Reader
JustBeforeEach(func() {
timeoutReader = TimeoutReader(innerReader, 20*time.Millisecond)
})
When("the underlying Reader returns no error", func() {
BeforeEach(func() {
innerReader = FakeReader{}
})
It("returns with no error", func() {
p := make([]byte, 5)
n, err := timeoutReader.Read(p)
Expect(n).Should(Equal(5))
Expect(err).ShouldNot(HaveOccurred())
Expect(p).Should(Equal([]byte("aaaaa")))
})
})
When("the underlying Reader returns an error", func() {
BeforeEach(func() {
innerReader = FakeReader{err: fmt.Errorf("boom")}
})
It("returns the error", func() {
p := make([]byte, 5)
_, err := timeoutReader.Read(p)
Expect(err).Should(MatchError("boom"))
})
})
When("the underlying Reader hangs", func() {
BeforeEach(func() {
innerReader = FakeReader{err: fmt.Errorf("boom"), duration: time.Hour}
})
It("returns ErrTimeout", func() {
p := make([]byte, 5)
_, err := timeoutReader.Read(p)
Expect(err).Should(MatchError(ErrTimeout))
})
})
})
Describe("TimeoutWriter", func() {
var innerWriter io.Writer
var timeoutWriter io.Writer
JustBeforeEach(func() {
timeoutWriter = TimeoutWriter(innerWriter, 20*time.Millisecond)
})
When("the underlying Writer returns no error", func() {
BeforeEach(func() {
innerWriter = FakeWriter{}
})
It("returns with no error", func() {
n, err := timeoutWriter.Write([]byte("aaaaa"))
Expect(n).Should(Equal(5))
Expect(err).ShouldNot(HaveOccurred())
})
})
When("the underlying Writer returns an error", func() {
BeforeEach(func() {
innerWriter = FakeWriter{err: fmt.Errorf("boom")}
})
It("returns the error", func() {
_, err := timeoutWriter.Write([]byte("aaaaa"))
Expect(err).Should(MatchError("boom"))
})
})
When("the underlying Writer hangs", func() {
BeforeEach(func() {
innerWriter = FakeWriter{err: fmt.Errorf("boom"), duration: time.Hour}
})
It("returns ErrTimeout", func() {
_, err := timeoutWriter.Write([]byte("aaaaa"))
Expect(err).Should(MatchError(ErrTimeout))
})
})
})
})
golang-gomega-1.27.10/gbytes/say_matcher.go 0000664 0000000 0000000 00000005376 14462163431 0020530 0 ustar 00root root 0000000 0000000 // untested sections: 1
package gbytes
import (
"fmt"
"regexp"
"github.com/onsi/gomega/format"
)
//Objects satisfying the BufferProvider can be used with the Say matcher.
type BufferProvider interface {
Buffer() *Buffer
}
/*
Say is a Gomega matcher that operates on gbytes.Buffers:
Expect(buffer).Should(Say("something"))
will succeed if the unread portion of the buffer matches the regular expression "something".
When Say succeeds, it fast forwards the gbytes.Buffer's read cursor to just after the successful match.
Thus, subsequent calls to Say will only match against the unread portion of the buffer
Say pairs very well with Eventually. To assert that a buffer eventually receives data matching "[123]-star" within 3 seconds you can:
Eventually(buffer, 3).Should(Say("[123]-star"))
Ditto with consistently. To assert that a buffer does not receive data matching "never-see-this" for 1 second you can:
Consistently(buffer, 1).ShouldNot(Say("never-see-this"))
In addition to bytes.Buffers, Say can operate on objects that implement the gbytes.BufferProvider interface.
In such cases, Say simply operates on the *gbytes.Buffer returned by Buffer()
If the buffer is closed, the Say matcher will tell Eventually to abort.
*/
func Say(expected string, args ...interface{}) *sayMatcher {
if len(args) > 0 {
expected = fmt.Sprintf(expected, args...)
}
return &sayMatcher{
re: regexp.MustCompile(expected),
}
}
type sayMatcher struct {
re *regexp.Regexp
receivedSayings []byte
}
func (m *sayMatcher) buffer(actual interface{}) (*Buffer, bool) {
var buffer *Buffer
switch x := actual.(type) {
case *Buffer:
buffer = x
case BufferProvider:
buffer = x.Buffer()
default:
return nil, false
}
return buffer, true
}
func (m *sayMatcher) Match(actual interface{}) (success bool, err error) {
buffer, ok := m.buffer(actual)
if !ok {
return false, fmt.Errorf("Say must be passed a *gbytes.Buffer or BufferProvider. Got:\n%s", format.Object(actual, 1))
}
didSay, sayings := buffer.didSay(m.re)
m.receivedSayings = sayings
return didSay, nil
}
func (m *sayMatcher) FailureMessage(actual interface{}) (message string) {
return fmt.Sprintf(
"Got stuck at:\n%s\nWaiting for:\n%s",
format.IndentString(string(m.receivedSayings), 1),
format.IndentString(m.re.String(), 1),
)
}
func (m *sayMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return fmt.Sprintf(
"Saw:\n%s\nWhich matches the unexpected:\n%s",
format.IndentString(string(m.receivedSayings), 1),
format.IndentString(m.re.String(), 1),
)
}
func (m *sayMatcher) MatchMayChangeInTheFuture(actual interface{}) bool {
switch x := actual.(type) {
case *Buffer:
return !x.Closed()
case BufferProvider:
return !x.Buffer().Closed()
default:
return true
}
}
golang-gomega-1.27.10/gbytes/say_matcher_test.go 0000664 0000000 0000000 00000010051 14462163431 0021551 0 ustar 00root root 0000000 0000000 package gbytes_test
import (
"time"
. "github.com/onsi/gomega/gbytes"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
type speaker struct {
buffer *Buffer
}
func (s *speaker) Buffer() *Buffer {
return s.buffer
}
var _ = Describe("SayMatcher", func() {
var buffer *Buffer
BeforeEach(func() {
buffer = NewBuffer()
buffer.Write([]byte("abc"))
})
When("actual is not a gexec Buffer, or a BufferProvider", func() {
It("should error", func() {
failures := InterceptGomegaFailures(func() {
Expect("foo").Should(Say("foo"))
})
Expect(failures[0]).Should(ContainSubstring("*gbytes.Buffer"))
})
})
When("a match is found", func() {
It("should succeed", func() {
Expect(buffer).Should(Say("abc"))
})
It("should support printf-like formatting", func() {
Expect(buffer).Should(Say("a%sc", "b"))
})
It("should match literal %", func() {
buffer.Write([]byte("%"))
Expect(buffer).Should(Say("abc%"))
})
It("should use a regular expression", func() {
Expect(buffer).Should(Say("a.c"))
})
It("should fastforward the buffer", func() {
buffer.Write([]byte("def"))
Expect(buffer).Should(Say("abcd"))
Expect(buffer).Should(Say("ef"))
Expect(buffer).ShouldNot(Say("[a-z]"))
})
})
When("no match is found", func() {
It("should not error", func() {
Expect(buffer).ShouldNot(Say("def"))
})
When("the buffer is closed", func() {
BeforeEach(func() {
buffer.Close()
})
It("should abort an eventually", func() {
t := time.Now()
failures := InterceptGomegaFailures(func() {
Eventually(buffer).Should(Say("def"))
})
Eventually(buffer).ShouldNot(Say("def"))
Expect(time.Since(t)).Should(BeNumerically("<", 500*time.Millisecond))
Expect(failures).Should(HaveLen(1))
t = time.Now()
Eventually(buffer).Should(Say("abc"))
Expect(time.Since(t)).Should(BeNumerically("<", 500*time.Millisecond))
})
It("should abort a consistently", func() {
t := time.Now()
Consistently(buffer, 2.0).ShouldNot(Say("def"))
Expect(time.Since(t)).Should(BeNumerically("<", 500*time.Millisecond))
})
It("should not error with a synchronous matcher", func() {
Expect(buffer).ShouldNot(Say("def"))
Expect(buffer).Should(Say("abc"))
})
})
})
When("a positive match fails", func() {
It("should report where it got stuck", func() {
Expect(buffer).Should(Say("abc"))
buffer.Write([]byte("def"))
failures := InterceptGomegaFailures(func() {
Expect(buffer).Should(Say("abc"))
})
Expect(failures[0]).Should(ContainSubstring("Got stuck at:"))
Expect(failures[0]).Should(ContainSubstring("def"))
})
})
When("a negative match fails", func() {
It("should report where it got stuck", func() {
failures := InterceptGomegaFailures(func() {
Expect(buffer).ShouldNot(Say("abc"))
})
Expect(failures[0]).Should(ContainSubstring("Saw:"))
Expect(failures[0]).Should(ContainSubstring("Which matches the unexpected:"))
Expect(failures[0]).Should(ContainSubstring("abc"))
})
})
When("a match is not found", func() {
It("should not fastforward the buffer", func() {
Expect(buffer).ShouldNot(Say("def"))
Expect(buffer).Should(Say("abc"))
})
})
Context("a nice real-life example", func() {
It("should behave well", func() {
Expect(buffer).Should(Say("abc"))
go func() {
time.Sleep(10 * time.Millisecond)
buffer.Write([]byte("def"))
}()
Expect(buffer).ShouldNot(Say("def"))
Eventually(buffer).Should(Say("def"))
})
})
When("actual is a BufferProvider", func() {
It("should use actual's buffer", func() {
s := &speaker{
buffer: NewBuffer(),
}
Expect(s).ShouldNot(Say("abc"))
s.Buffer().Write([]byte("abc"))
Expect(s).Should(Say("abc"))
})
It("should abort an eventually", func() {
s := &speaker{
buffer: NewBuffer(),
}
s.buffer.Close()
t := time.Now()
failures := InterceptGomegaFailures(func() {
Eventually(s).Should(Say("def"))
})
Expect(failures).Should(HaveLen(1))
Expect(time.Since(t)).Should(BeNumerically("<", 500*time.Millisecond))
})
})
})
golang-gomega-1.27.10/gcustom/ 0000775 0000000 0000000 00000000000 14462163431 0016053 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gcustom/gcustom_suite_test.go 0000664 0000000 0000000 00000000305 14462163431 0022331 0 ustar 00root root 0000000 0000000 package gcustom_test
import (
"testing"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
func TestGcustom(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Gcustom Suite")
}
golang-gomega-1.27.10/gcustom/make_matcher.go 0000664 0000000 0000000 00000024165 14462163431 0021032 0 ustar 00root root 0000000 0000000 /*
package gcustom provides a simple mechanism for creating custom Gomega matchers
*/
package gcustom
import (
"fmt"
"reflect"
"strings"
"text/template"
"github.com/onsi/gomega/format"
)
var interfaceType = reflect.TypeOf((*interface{})(nil)).Elem()
var errInterface = reflect.TypeOf((*error)(nil)).Elem()
var defaultTemplate = template.Must(ParseTemplate("{{if .Failure}}Custom matcher failed for:{{else}}Custom matcher succeeded (but was expected to fail) for:{{end}}\n{{.FormattedActual}}"))
func formatObject(object any, indent ...uint) string {
indentation := uint(0)
if len(indent) > 0 {
indentation = indent[0]
}
return format.Object(object, indentation)
}
/*
ParseTemplate allows you to precompile templates for MakeMatcher's custom matchers.
Use ParseTemplate if you are concerned about performance and would like to avoid repeatedly parsing failure message templates. The data made available to the template is documented in the WithTemplate() method of CustomGomegaMatcher.
Once parsed you can pass the template in either as an argument to MakeMatcher(matchFunc, ) or using MakeMatcher(matchFunc).WithPrecompiledTemplate(template)
*/
func ParseTemplate(templ string) (*template.Template, error) {
return template.New("template").Funcs(template.FuncMap{
"format": formatObject,
}).Parse(templ)
}
/*
MakeMatcher builds a Gomega-compatible matcher from a function (the matchFunc).
matchFunc must return (bool, error) and take a single argument. If you want to perform type-checking yourself pass in a matchFunc of type `func(actual any) (bool, error)`. If you want to only operate on a specific type, pass in `func(actual DesiredType) (bool, error)`; MakeMatcher will take care of checking types for you and notifying the user if they use the matcher with an invalid type.
MakeMatcher(matchFunc) builds a matcher with generic failure messages that look like:
Custom matcher failed for:
for the positive failure case (i.e. when Expect(actual).To(match) fails) and
Custom matcher succeeded (but was expected to fail) for:
for the negative case (i.e. when Expect(actual).NotTo(match) fails).
There are two ways to provide a different message. You can either provide a simple message string:
matcher := MakeMatcher(matchFunc, message)
matcher := MakeMatcher(matchFunc).WithMessage(message)
(where message is of type string) or a template:
matcher := MakeMatcher(matchFunc).WithTemplate(templateString)
where templateString is a string that is compiled by WithTemplate into a matcher. Alternatively you can provide a precompiled template like this:
template, err = gcustom.ParseTemplate(templateString) //use gcustom's ParseTemplate to get some additional functions mixed in
matcher := MakeMatcher(matchFunc, template)
matcher := MakeMatcher(matchFunc).WithPrecompiled(template)
When a simple message string is provided the positive failure message will look like:
Expected:
to
and the negative failure message will look like:
Expected:
not to
A template allows you to have greater control over the message. For more details see the docs for WithTemplate
*/
func MakeMatcher(matchFunc any, args ...any) CustomGomegaMatcher {
t := reflect.TypeOf(matchFunc)
if !(t.Kind() == reflect.Func && t.NumIn() == 1 && t.NumOut() == 2 && t.Out(0).Kind() == reflect.Bool && t.Out(1).Implements(errInterface)) {
panic("MakeMatcher must be passed a function that takes one argument and returns (bool, error)")
}
var finalMatchFunc func(actual any) (bool, error)
if t.In(0) == interfaceType {
finalMatchFunc = matchFunc.(func(actual any) (bool, error))
} else {
matchFuncValue := reflect.ValueOf(matchFunc)
finalMatchFunc = reflect.MakeFunc(reflect.TypeOf(finalMatchFunc),
func(args []reflect.Value) []reflect.Value {
actual := args[0].Interface()
if actual == nil && reflect.TypeOf(actual) == reflect.TypeOf(nil) {
return matchFuncValue.Call([]reflect.Value{reflect.New(t.In(0)).Elem()})
} else if reflect.TypeOf(actual).AssignableTo(t.In(0)) {
return matchFuncValue.Call([]reflect.Value{reflect.ValueOf(actual)})
} else {
return []reflect.Value{
reflect.ValueOf(false),
reflect.ValueOf(fmt.Errorf("Matcher expected actual of type <%s>. Got:\n%s", t.In(0), format.Object(actual, 1))),
}
}
}).Interface().(func(actual any) (bool, error))
}
matcher := CustomGomegaMatcher{
matchFunc: finalMatchFunc,
templateMessage: defaultTemplate,
}
for _, arg := range args {
switch v := arg.(type) {
case string:
matcher = matcher.WithMessage(v)
case *template.Template:
matcher = matcher.WithPrecompiledTemplate(v)
}
}
return matcher
}
// CustomGomegaMatcher is generated by MakeMatcher - you should always use MakeMatcher to construct custom matchers
type CustomGomegaMatcher struct {
matchFunc func(actual any) (bool, error)
templateMessage *template.Template
templateData any
customFailureMessage func(actual any) string
customNegatedFailureMessage func(actual any) string
}
/*
WithMessage returns a CustomGomegaMatcher configured with a message to display when failure occurs. Matchers configured this way produce a positive failure message that looks like:
Expected:
to
and a negative failure message that looks like:
Expected:
not to
*/
func (c CustomGomegaMatcher) WithMessage(message string) CustomGomegaMatcher {
return c.WithTemplate("Expected:\n{{.FormattedActual}}\n{{.To}} " + message)
}
/*
WithTemplate compiles the passed-in template and returns a CustomGomegaMatcher configured to use that template to generate failure messages.
Templates are provided the following variables and functions:
{{.Failure}} - a bool that, if true, indicates this should be a positive failure message, otherwise this should be a negated failure message
{{.NegatedFailure}} - a bool that, if true, indicates this should be a negated failure message, otherwise this should be a positive failure message
{{.To}} - is set to "to" if this is a positive failure message and "not to" if this is a negated failure message
{{.Actual}} - the actual passed in to the matcher
{{.FormattedActual}} - a string representing the formatted actual. This can be multiple lines and is always generated with an indentation of 1
{{format is formatted and can be set to an integer to control indentation.
In addition, you can provide custom data to the template by calling WithTemplate(templateString, data) (where data can be anything). This is provided to the template as {{.Data}}.
Here's a simple example of all these pieces working together:
func HaveWidget(widget Widget) OmegaMatcher {
return MakeMatcher(func(machine Machine) (bool, error) {
return machine.HasWidget(widget), nil
}).WithTemplate("Expected:\n{{.FormattedActual}}\n{{.To}} have widget named {{.Data.Name}}:\n{{format .Data 1}}", widget)
}
Expect(machine).To(HaveWidget(Widget{Name: "sprocket", Version: 2}))
Would generate a failure message that looks like:
Expected:
to have widget named sprocket:
*/
func (c CustomGomegaMatcher) WithTemplate(templ string, data ...any) CustomGomegaMatcher {
return c.WithPrecompiledTemplate(template.Must(ParseTemplate(templ)), data...)
}
/*
WithPrecompiledTemplate returns a CustomGomegaMatcher configured to use the passed-in template. The template should be precompiled with gcustom.ParseTemplate().
As with WithTemplate() you can provide a single pice of additional data as an optional argument. This is accessed in the template via {{.Data}}
*/
func (c CustomGomegaMatcher) WithPrecompiledTemplate(templ *template.Template, data ...any) CustomGomegaMatcher {
c.templateMessage = templ
c.templateData = nil
if len(data) > 0 {
c.templateData = data[0]
}
return c
}
/*
WithTemplateData() returns a CustomGomegaMatcher configured to provide it's template with the passed-in data. The following are equivalent:
MakeMatcher(matchFunc).WithTemplate(templateString, data)
MakeMatcher(matchFunc).WithTemplate(templateString).WithTemplateData(data)
*/
func (c CustomGomegaMatcher) WithTemplateData(data any) CustomGomegaMatcher {
c.templateData = data
return c
}
// Match runs the passed-in match func and satisfies the GomegaMatcher interface
func (c CustomGomegaMatcher) Match(actual any) (bool, error) {
return c.matchFunc(actual)
}
// FailureMessage generates the positive failure message configured via WithMessage or WithTemplate/WithPrecompiledTemplate
// i.e. this is the failure message when Expect(actual).To(match) fails
func (c CustomGomegaMatcher) FailureMessage(actual any) string {
return c.renderTemplateMessage(actual, true)
}
// NegatedFailureMessage generates the negative failure message configured via WithMessage or WithTemplate/WithPrecompiledTemplate
// i.e. this is the failure message when Expect(actual).NotTo(match) fails
func (c CustomGomegaMatcher) NegatedFailureMessage(actual any) string {
return c.renderTemplateMessage(actual, false)
}
type templateData struct {
Failure bool
NegatedFailure bool
To string
FormattedActual string
Actual any
Data any
}
func (c CustomGomegaMatcher) renderTemplateMessage(actual any, isFailure bool) string {
var data templateData
formattedActual := format.Object(actual, 1)
if isFailure {
data = templateData{
Failure: true,
NegatedFailure: false,
To: "to",
FormattedActual: formattedActual,
Actual: actual,
Data: c.templateData,
}
} else {
data = templateData{
Failure: false,
NegatedFailure: true,
To: "not to",
FormattedActual: formattedActual,
Actual: actual,
Data: c.templateData,
}
}
b := &strings.Builder{}
err := c.templateMessage.Execute(b, data)
if err != nil {
return fmt.Sprintf("Failed to render failure message template: %s", err.Error())
}
return b.String()
}
golang-gomega-1.27.10/gcustom/make_matcher_test.go 0000664 0000000 0000000 00000021600 14462163431 0022060 0 ustar 00root root 0000000 0000000 package gcustom_test
import (
"errors"
"runtime"
"strings"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gcustom"
"github.com/onsi/gomega/internal"
)
// InstrumentedGomega
type InstrumentedGomega struct {
G *internal.Gomega
FailureMessage string
FailureSkip []int
RegisteredHelpers []string
}
func NewInstrumentedGomega() *InstrumentedGomega {
out := &InstrumentedGomega{}
out.G = internal.NewGomega(internal.FetchDefaultDurationBundle())
out.G.Fail = func(message string, skip ...int) {
out.FailureMessage = message
out.FailureSkip = skip
}
out.G.THelper = func() {
pc, _, _, _ := runtime.Caller(1)
f := runtime.FuncForPC(pc)
funcName := strings.TrimPrefix(f.Name(), "github.com/onsi/gomega/internal.")
out.RegisteredHelpers = append(out.RegisteredHelpers, funcName)
}
return out
}
type someType struct {
Name string
}
var _ = Describe("MakeMatcher", func() {
It("generatees a custom matcher that satisfies the GomegaMatcher interface and renders correct failure messages", func() {
m := gcustom.MakeMatcher(func(a int) (bool, error) {
if a == 0 {
return true, nil
}
if a == 1 {
return false, nil
}
return false, errors.New("bam")
}).WithMessage("match")
Ω(0).Should(m)
Ω(1).ShouldNot(m)
ig := NewInstrumentedGomega()
ig.G.Ω(1).Should(m)
Ω(ig.FailureMessage).Should(Equal("Expected:\n : 1\nto match"))
ig.G.Ω(0).ShouldNot(m)
Ω(ig.FailureMessage).Should(Equal("Expected:\n : 0\nnot to match"))
ig.G.Ω(2).Should(m)
Ω(ig.FailureMessage).Should(Equal("bam"))
ig.G.Ω(2).ShouldNot(m)
Ω(ig.FailureMessage).Should(Equal("bam"))
})
Describe("validating and wrapping the MatchFunc", func() {
DescribeTable("it panics when passed an invalid function", func(f any) {
Expect(func() {
gcustom.MakeMatcher(f)
}).To(PanicWith("MakeMatcher must be passed a function that takes one argument and returns (bool, error)"))
},
Entry("a non-function", "foo"),
Entry("a non-function", 1),
Entry("a function with no input", func() (bool, error) { return false, nil }),
Entry("a function with too many inputs", func(a int, b string) (bool, error) { return false, nil }),
Entry("a function with no outputs", func(a any) {}),
Entry("a function with insufficient outputs", func(a any) bool { return false }),
Entry("a function with insufficient outputs", func(a any) error { return nil }),
Entry("a function with too many outputs", func(a any) (bool, error, string) { return false, nil, "" }),
Entry("a function with the wrong types of outputs", func(a any) (int, error) { return 1, nil }),
Entry("a function with the wrong types of outputs", func(a any) (bool, int) { return false, 1 }),
)
Context("when the match func accepts any actual", func() {
It("always passes in the actual, regardless of type", func() {
var passedIn any
m := gcustom.MakeMatcher(func(a any) (bool, error) {
passedIn = a
return true, nil
})
m.Match(1)
Ω(passedIn).Should(Equal(1))
m.Match("foo")
Ω(passedIn).Should(Equal("foo"))
m.Match(someType{"foo"})
Ω(passedIn).Should(Equal(someType{"foo"}))
c := make(chan bool)
m.Match(c)
Ω(passedIn).Should(Equal(c))
})
})
Context("when the match func accepts a specific type", func() {
It("ensure the type matches before calling func", func() {
var passedIn any
m := gcustom.MakeMatcher(func(a int) (bool, error) {
passedIn = a
return true, nil
})
success, err := m.Match(1)
Ω(success).Should(BeTrue())
Ω(err).ShouldNot(HaveOccurred())
Ω(passedIn).Should(Equal(1))
passedIn = nil
success, err = m.Match(1.2)
Ω(success).Should(BeFalse())
Ω(err).Should(MatchError(ContainSubstring("Matcher expected actual of type . Got:\n : 1.2")))
Ω(passedIn).Should(BeNil())
m = gcustom.MakeMatcher(func(a someType) (bool, error) {
passedIn = a
return true, nil
})
success, err = m.Match(someType{"foo"})
Ω(success).Should(BeTrue())
Ω(err).ShouldNot(HaveOccurred())
Ω(passedIn).Should(Equal(someType{"foo"}))
passedIn = nil
success, err = m.Match("foo")
Ω(success).Should(BeFalse())
Ω(err).Should(MatchError(ContainSubstring("Matcher expected actual of type . Got:\n : foo")))
Ω(passedIn).Should(BeNil())
})
})
Context("when the match func accepts a nil-able type", func() {
It("ensure nil matches the type", func() {
var passedIn any
m := gcustom.MakeMatcher(func(a *someType) (bool, error) {
passedIn = a
return true, nil
})
success, err := m.Match(nil)
Ω(success).Should(BeTrue())
Ω(err).ShouldNot(HaveOccurred())
Ω(passedIn).Should(BeNil())
})
})
})
It("calls the matchFunc and returns whatever it returns when Match is called", func() {
m := gcustom.MakeMatcher(func(a int) (bool, error) {
if a == 0 {
return true, nil
}
if a == 1 {
return false, nil
}
return false, errors.New("bam")
})
Ω(m.Match(0)).Should(BeTrue())
Ω(m.Match(1)).Should(BeFalse())
success, err := m.Match(2)
Ω(success).Should(BeFalse())
Ω(err).Should(MatchError("bam"))
})
Describe("rendering messages", func() {
var m gcustom.CustomGomegaMatcher
BeforeEach(func() {
m = gcustom.MakeMatcher(func(a any) (bool, error) { return false, nil })
})
Context("when no message is configured", func() {
It("renders a simple canned message", func() {
Ω(m.FailureMessage(3)).Should(Equal("Custom matcher failed for:\n : 3"))
Ω(m.NegatedFailureMessage(3)).Should(Equal("Custom matcher succeeded (but was expected to fail) for:\n : 3"))
})
})
Context("when a simple message is configured", func() {
It("tacks that message onto the end of a formatted string", func() {
m = m.WithMessage("have been confabulated")
Ω(m.FailureMessage(3)).Should(Equal("Expected:\n : 3\nto have been confabulated"))
Ω(m.NegatedFailureMessage(3)).Should(Equal("Expected:\n : 3\nnot to have been confabulated"))
m = gcustom.MakeMatcher(func(a any) (bool, error) { return false, nil }, "have been confabulated")
Ω(m.FailureMessage(3)).Should(Equal("Expected:\n : 3\nto have been confabulated"))
Ω(m.NegatedFailureMessage(3)).Should(Equal("Expected:\n : 3\nnot to have been confabulated"))
})
})
Context("when a template is registered", func() {
It("uses that template", func() {
m = m.WithTemplate("{{.Failure}} {{.NegatedFailure}} {{.To}} {{.FormattedActual}} {{.Actual.Name}}")
Ω(m.FailureMessage(someType{"foo"})).Should(Equal("true false to : {Name: \"foo\"} foo"))
Ω(m.NegatedFailureMessage(someType{"foo"})).Should(Equal("false true not to : {Name: \"foo\"} foo"))
})
})
Context("when a template with custom data is registered", func() {
It("provides that custom data", func() {
m = m.WithTemplate("{{.Failure}} {{.NegatedFailure}} {{.To}} {{.FormattedActual}} {{.Actual.Name}} {{.Data}}", 17)
Ω(m.FailureMessage(someType{"foo"})).Should(Equal("true false to : {Name: \"foo\"} foo 17"))
Ω(m.NegatedFailureMessage(someType{"foo"})).Should(Equal("false true not to : {Name: \"foo\"} foo 17"))
})
It("provides a mechanism for formatting custom data", func() {
m = m.WithTemplate("{{format .Data}}", 17)
Ω(m.FailureMessage(0)).Should(Equal(": 17"))
Ω(m.NegatedFailureMessage(0)).Should(Equal(": 17"))
m = m.WithTemplate("{{format .Data 1}}", 17)
Ω(m.FailureMessage(0)).Should(Equal(" : 17"))
Ω(m.NegatedFailureMessage(0)).Should(Equal(" : 17"))
})
})
Context("when a precompiled template is registered", func() {
It("uses that template", func() {
templ, err := gcustom.ParseTemplate("{{.Failure}} {{.NegatedFailure}} {{.To}} {{.FormattedActual}} {{.Actual.Name}} {{format .Data}}")
Ω(err).ShouldNot(HaveOccurred())
m = m.WithPrecompiledTemplate(templ, 17)
Ω(m.FailureMessage(someType{"foo"})).Should(Equal("true false to : {Name: \"foo\"} foo : 17"))
Ω(m.NegatedFailureMessage(someType{"foo"})).Should(Equal("false true not to : {Name: \"foo\"} foo : 17"))
})
It("can also take a template as an argument upon construction", func() {
templ, err := gcustom.ParseTemplate("{{.To}} {{format .Data}}")
Ω(err).ShouldNot(HaveOccurred())
m = gcustom.MakeMatcher(func(a any) (bool, error) { return false, nil }, templ)
Ω(m.FailureMessage(0)).Should(Equal("to : nil"))
Ω(m.NegatedFailureMessage(0)).Should(Equal("not to : nil"))
m = m.WithTemplateData(17)
Ω(m.FailureMessage(0)).Should(Equal("to : 17"))
Ω(m.NegatedFailureMessage(0)).Should(Equal("not to : 17"))
})
})
})
})
golang-gomega-1.27.10/gexec/ 0000775 0000000 0000000 00000000000 14462163431 0015465 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gexec/_fixture/ 0000775 0000000 0000000 00000000000 14462163431 0017312 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gexec/_fixture/firefly/ 0000775 0000000 0000000 00000000000 14462163431 0020752 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gexec/_fixture/firefly/main.go 0000664 0000000 0000000 00000001426 14462163431 0022230 0 ustar 00root root 0000000 0000000 package main
import (
"fmt"
"math/rand"
"os"
"strconv"
"time"
)
var outQuote = "We've done the impossible, and that makes us mighty."
var errQuote = "Ah, curse your sudden but inevitable betrayal!"
var randomQuotes = []string{
"Can we maybe vote on the whole murdering people issue?",
"I swear by my pretty floral bonnet, I will end you.",
"My work's illegal, but at least it's honest.",
}
func main() {
fmt.Fprintln(os.Stdout, outQuote)
fmt.Fprintln(os.Stderr, errQuote)
randomIndex := rand.New(rand.NewSource(time.Now().UnixNano())).Intn(len(randomQuotes))
time.Sleep(100 * time.Millisecond)
fmt.Fprintln(os.Stdout, randomQuotes[randomIndex])
if len(os.Args) == 2 {
exitCode, _ := strconv.Atoi(os.Args[1])
os.Exit(exitCode)
} else {
os.Exit(randomIndex)
}
}
golang-gomega-1.27.10/gexec/_fixture/firefly/main_test.go 0000664 0000000 0000000 00000000137 14462163431 0023265 0 ustar 00root root 0000000 0000000 package main_test
import "testing"
func Test(t *testing.T) {
t.Log("Hum, it seems okay.")
}
golang-gomega-1.27.10/gexec/build.go 0000664 0000000 0000000 00000015510 14462163431 0017115 0 ustar 00root root 0000000 0000000 // untested sections: 5
package gexec
import (
"errors"
"fmt"
"go/build"
"os"
"os/exec"
"path"
"path/filepath"
"runtime"
"strings"
"sync"
"github.com/onsi/gomega/internal/gutil"
)
var (
mu sync.Mutex
tmpDir string
)
/*
Build uses go build to compile the package at packagePath. The resulting binary is saved off in a temporary directory.
A path pointing to this binary is returned.
Build uses the $GOPATH set in your environment. If $GOPATH is not set and you are using Go 1.8+,
it will use the default GOPATH instead. It passes the variadic args on to `go build`.
*/
func Build(packagePath string, args ...string) (compiledPath string, err error) {
return doBuild(build.Default.GOPATH, packagePath, nil, args...)
}
/*
BuildWithEnvironment is identical to Build but allows you to specify env vars to be set at build time.
*/
func BuildWithEnvironment(packagePath string, env []string, args ...string) (compiledPath string, err error) {
return doBuild(build.Default.GOPATH, packagePath, env, args...)
}
/*
BuildIn is identical to Build but allows you to specify a custom $GOPATH (the first argument).
*/
func BuildIn(gopath string, packagePath string, args ...string) (compiledPath string, err error) {
return doBuild(gopath, packagePath, nil, args...)
}
func doBuild(gopath, packagePath string, env []string, args ...string) (compiledPath string, err error) {
executable, err := newExecutablePath(gopath, packagePath)
if err != nil {
return "", err
}
cmdArgs := append([]string{"build"}, args...)
cmdArgs = append(cmdArgs, "-o", executable, packagePath)
build := exec.Command("go", cmdArgs...)
build.Env = replaceGoPath(os.Environ(), gopath)
build.Env = append(build.Env, env...)
output, err := build.CombinedOutput()
if err != nil {
return "", fmt.Errorf("Failed to build %s:\n\nError:\n%s\n\nOutput:\n%s", packagePath, err, string(output))
}
return executable, nil
}
/*
CompileTest uses go test to compile the test package at packagePath. The resulting binary is saved off in a temporary directory.
A path pointing to this binary is returned.
CompileTest uses the $GOPATH set in your environment. If $GOPATH is not set and you are using Go 1.8+,
it will use the default GOPATH instead. It passes the variadic args on to `go test`.
*/
func CompileTest(packagePath string, args ...string) (compiledPath string, err error) {
return doCompileTest(build.Default.GOPATH, packagePath, nil, args...)
}
/*
GetAndCompileTest is identical to CompileTest but `go get` the package before compiling tests.
*/
func GetAndCompileTest(packagePath string, args ...string) (compiledPath string, err error) {
if err := getForTest(build.Default.GOPATH, packagePath, []string{"GO111MODULE=off"}); err != nil {
return "", err
}
return doCompileTest(build.Default.GOPATH, packagePath, []string{"GO111MODULE=off"}, args...)
}
/*
CompileTestWithEnvironment is identical to CompileTest but allows you to specify env vars to be set at build time.
*/
func CompileTestWithEnvironment(packagePath string, env []string, args ...string) (compiledPath string, err error) {
return doCompileTest(build.Default.GOPATH, packagePath, env, args...)
}
/*
GetAndCompileTestWithEnvironment is identical to GetAndCompileTest but allows you to specify env vars to be set at build time.
*/
func GetAndCompileTestWithEnvironment(packagePath string, env []string, args ...string) (compiledPath string, err error) {
if err := getForTest(build.Default.GOPATH, packagePath, append(env, "GO111MODULE=off")); err != nil {
return "", err
}
return doCompileTest(build.Default.GOPATH, packagePath, append(env, "GO111MODULE=off"), args...)
}
/*
CompileTestIn is identical to CompileTest but allows you to specify a custom $GOPATH (the first argument).
*/
func CompileTestIn(gopath string, packagePath string, args ...string) (compiledPath string, err error) {
return doCompileTest(gopath, packagePath, nil, args...)
}
/*
GetAndCompileTestIn is identical to GetAndCompileTest but allows you to specify a custom $GOPATH (the first argument).
*/
func GetAndCompileTestIn(gopath string, packagePath string, args ...string) (compiledPath string, err error) {
if err := getForTest(gopath, packagePath, []string{"GO111MODULE=off"}); err != nil {
return "", err
}
return doCompileTest(gopath, packagePath, []string{"GO111MODULE=off"}, args...)
}
func isLocalPackage(packagePath string) bool {
return strings.HasPrefix(packagePath, ".")
}
func getForTest(gopath, packagePath string, env []string) error {
if isLocalPackage(packagePath) {
return nil
}
return doGet(gopath, packagePath, env, "-t")
}
func doGet(gopath, packagePath string, env []string, args ...string) error {
args = append(args, packagePath)
args = append([]string{"get"}, args...)
goGet := exec.Command("go", args...)
goGet.Dir = gopath
goGet.Env = replaceGoPath(os.Environ(), gopath)
goGet.Env = append(goGet.Env, env...)
output, err := goGet.CombinedOutput()
if err != nil {
return fmt.Errorf("Failed to get %s:\n\nError:\n%s\n\nOutput:\n%s", packagePath, err, string(output))
}
return nil
}
func doCompileTest(gopath, packagePath string, env []string, args ...string) (compiledPath string, err error) {
executable, err := newExecutablePath(gopath, packagePath, ".test")
if err != nil {
return "", err
}
cmdArgs := append([]string{"test", "-c"}, args...)
cmdArgs = append(cmdArgs, "-o", executable, packagePath)
build := exec.Command("go", cmdArgs...)
build.Env = replaceGoPath(os.Environ(), gopath)
build.Env = append(build.Env, env...)
output, err := build.CombinedOutput()
if err != nil {
return "", fmt.Errorf("Failed to build %s:\n\nError:\n%s\n\nOutput:\n%s", packagePath, err, string(output))
}
return executable, nil
}
func replaceGoPath(environ []string, newGoPath string) []string {
newEnviron := []string{}
for _, v := range environ {
if !strings.HasPrefix(v, "GOPATH=") {
newEnviron = append(newEnviron, v)
}
}
return append(newEnviron, "GOPATH="+newGoPath)
}
func newExecutablePath(gopath, packagePath string, suffixes ...string) (string, error) {
tmpDir, err := temporaryDirectory()
if err != nil {
return "", err
}
if len(gopath) == 0 {
return "", errors.New("$GOPATH not provided when building " + packagePath)
}
executable := filepath.Join(tmpDir, path.Base(packagePath))
if runtime.GOOS == "windows" {
executable += ".exe"
}
return executable, nil
}
/*
You should call CleanupBuildArtifacts before your test ends to clean up any temporary artifacts generated by
gexec. In Ginkgo this is typically done in an AfterSuite callback.
*/
func CleanupBuildArtifacts() {
mu.Lock()
defer mu.Unlock()
if tmpDir != "" {
os.RemoveAll(tmpDir)
tmpDir = ""
}
}
func temporaryDirectory() (string, error) {
var err error
mu.Lock()
defer mu.Unlock()
if tmpDir == "" {
tmpDir, err = gutil.MkdirTemp("", "gexec_artifacts")
if err != nil {
return "", err
}
}
return gutil.MkdirTemp(tmpDir, "g")
}
golang-gomega-1.27.10/gexec/build_test.go 0000664 0000000 0000000 00000017747 14462163431 0020172 0 ustar 00root root 0000000 0000000 package gexec_test
import (
"fmt"
"os"
"path/filepath"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gexec"
"github.com/onsi/gomega/internal/gutil"
)
var packagePath = "./_fixture/firefly"
var _ = Describe(".Build", func() {
When("there have been previous calls to CompileTest", func() {
BeforeEach(func() {
_, err := gexec.CompileTest(packagePath)
Expect(err).ShouldNot(HaveOccurred())
})
It("compiles the specified package", func() {
compiledPath, err := gexec.Build(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
Expect(filepath.Base(compiledPath)).Should(MatchRegexp(`firefly(|.exe)$`))
})
Context("and CleanupBuildArtifacts has been called", func() {
BeforeEach(func() {
gexec.CleanupBuildArtifacts()
})
It("compiles the specified package", func() {
fireflyPath, err := gexec.Build(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(fireflyPath).Should(BeAnExistingFile())
})
})
})
When("there have been previous calls to Build", func() {
BeforeEach(func() {
_, err := gexec.Build(packagePath)
Expect(err).ShouldNot(HaveOccurred())
})
It("compiles the specified package", func() {
compiledPath, err := gexec.Build(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
Context("and CleanupBuildArtifacts has been called", func() {
BeforeEach(func() {
gexec.CleanupBuildArtifacts()
})
It("compiles the specified package", func() {
fireflyPath, err := gexec.Build(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(fireflyPath).Should(BeAnExistingFile())
})
})
})
})
var _ = Describe(".BuildWithEnvironment", func() {
var err error
env := []string{
"GOOS=linux",
"GOARCH=amd64",
}
It("compiles the specified package with the specified env vars", func() {
compiledPath, err := gexec.BuildWithEnvironment(packagePath, env)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
It("returns the environment to a good state", func() {
_, err = gexec.BuildWithEnvironment(packagePath, env)
Expect(err).ShouldNot(HaveOccurred())
Expect(os.Environ()).ShouldNot(ContainElement("GOOS=linux"))
})
})
var _ = Describe(".BuildIn", func() {
const (
target = "github.com/onsi/gomega/gexec/_fixture/firefly/"
)
var (
original string
gopath string
)
BeforeEach(func() {
var err error
original = os.Getenv("GOPATH")
gopath, err = gutil.MkdirTemp("", "")
Expect(err).NotTo(HaveOccurred())
copyFile(filepath.Join("_fixture", "firefly", "main.go"), filepath.Join(gopath, "src", target), "main.go")
Expect(os.Setenv("GOPATH", filepath.Join(os.TempDir(), "emptyFakeGopath"))).To(Succeed())
Expect(os.Environ()).To(ContainElement(fmt.Sprintf("GOPATH=%s", filepath.Join(os.TempDir(), "emptyFakeGopath"))))
})
AfterEach(func() {
if original == "" {
Expect(os.Unsetenv("GOPATH")).To(Succeed())
} else {
Expect(os.Setenv("GOPATH", original)).To(Succeed())
}
if gopath != "" {
os.RemoveAll(gopath)
}
})
It("appends the gopath env var", func() {
compiledPath, err := gexec.BuildIn(gopath, target)
Expect(err).NotTo(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
It("resets GOPATH to its original value", func() {
_, err := gexec.BuildIn(gopath, target)
Expect(err).NotTo(HaveOccurred())
Expect(os.Getenv("GOPATH")).To(Equal(filepath.Join(os.TempDir(), "emptyFakeGopath")))
})
})
var _ = Describe(".CompileTest", func() {
Context("a remote package", Label("network"), func() {
const remotePackage = "github.com/onsi/ginkgo/types"
It("compiles the specified test package", func() {
compiledPath, err := gexec.GetAndCompileTest(remotePackage)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
})
When("there have been previous calls to CompileTest", func() {
BeforeEach(func() {
_, err := gexec.CompileTest(packagePath)
Expect(err).ShouldNot(HaveOccurred())
})
It("compiles the specified test package", func() {
compiledPath, err := gexec.CompileTest(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
Context("and CleanupBuildArtifacts has been called", func() {
BeforeEach(func() {
gexec.CleanupBuildArtifacts()
})
It("compiles the specified test package", func() {
fireflyTestPath, err := gexec.CompileTest(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(fireflyTestPath).Should(BeAnExistingFile())
})
})
})
When("there have been previous calls to Build", func() {
BeforeEach(func() {
_, err := gexec.Build(packagePath)
Expect(err).ShouldNot(HaveOccurred())
})
It("compiles the specified test package", func() {
compiledPath, err := gexec.CompileTest(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
Context("and CleanupBuildArtifacts has been called", func() {
BeforeEach(func() {
gexec.CleanupBuildArtifacts()
})
It("compiles the specified test package", func() {
fireflyTestPath, err := gexec.CompileTest(packagePath)
Expect(err).ShouldNot(HaveOccurred())
Expect(fireflyTestPath).Should(BeAnExistingFile())
})
})
})
})
var _ = Describe(".CompileTestWithEnvironment", func() {
var err error
env := []string{
"GOOS=linux",
"GOARCH=amd64",
}
Context("a remote package", Label("network"), func() {
const remotePackage = "github.com/onsi/ginkgo/types"
It("compiles the specified test package with the specified env vars", func() {
compiledPath, err := gexec.GetAndCompileTestWithEnvironment(remotePackage, env)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
})
It("compiles the specified test package with the specified env vars", func() {
compiledPath, err := gexec.CompileTestWithEnvironment(packagePath, env)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
It("returns the environment to a good state", func() {
_, err = gexec.CompileTestWithEnvironment(packagePath, env)
Expect(err).ShouldNot(HaveOccurred())
Expect(os.Environ()).ShouldNot(ContainElement("GOOS=linux"))
})
})
var _ = Describe(".CompiledTestIn", func() {
const target = "github.com/onsi/gomega/gexec/_fixture/firefly"
var (
original string
gopath string
)
BeforeEach(func() {
var err error
original = os.Getenv("GOPATH")
gopath, err = gutil.MkdirTemp("", "")
Expect(err).NotTo(HaveOccurred())
Expect(os.Setenv("GOPATH", filepath.Join(os.TempDir(), "emptyFakeGopath"))).To(Succeed())
Expect(os.Environ()).To(ContainElement(fmt.Sprintf("GOPATH=%s", filepath.Join(os.TempDir(), "emptyFakeGopath"))))
})
AfterEach(func() {
if original == "" {
Expect(os.Unsetenv("GOPATH")).To(Succeed())
} else {
Expect(os.Setenv("GOPATH", original)).To(Succeed())
}
if gopath != "" {
os.RemoveAll(gopath)
}
})
Context("a remote package", Label("network"), func() {
const remotePackage = "github.com/onsi/ginkgo/types"
It("compiles the specified test package", func() {
compiledPath, err := gexec.GetAndCompileTestIn(gopath, remotePackage)
Expect(err).ShouldNot(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
})
It("appends the gopath env var", func() {
compiledPath, err := gexec.CompileTestIn(gopath, target)
Expect(err).NotTo(HaveOccurred())
Expect(compiledPath).Should(BeAnExistingFile())
})
It("resets GOPATH to its original value", func() {
_, err := gexec.CompileTestIn(gopath, target)
Expect(err).NotTo(HaveOccurred())
Expect(os.Getenv("GOPATH")).To(Equal(filepath.Join(os.TempDir(), "emptyFakeGopath")))
})
})
func copyFile(source, directory, basename string) {
Expect(os.MkdirAll(directory, 0755)).To(Succeed())
content, err := gutil.ReadFile(source)
Expect(err).NotTo(HaveOccurred())
Expect(gutil.WriteFile(filepath.Join(directory, basename), content)).To(Succeed())
}
golang-gomega-1.27.10/gexec/exit_matcher.go 0000664 0000000 0000000 00000004040 14462163431 0020466 0 ustar 00root root 0000000 0000000 // untested sections: 2
package gexec
import (
"fmt"
"github.com/onsi/gomega/format"
)
/*
The Exit matcher operates on a session:
Expect(session).Should(Exit())
Exit passes if the session has already exited.
If no status code is provided, then Exit will succeed if the session has exited regardless of exit code.
Otherwise, Exit will only succeed if the process has exited with the provided status code.
Note that the process must have already exited. To wait for a process to exit, use Eventually:
Eventually(session, 3).Should(Exit(0))
*/
func Exit(optionalExitCode ...int) *exitMatcher {
exitCode := -1
if len(optionalExitCode) > 0 {
exitCode = optionalExitCode[0]
}
return &exitMatcher{
exitCode: exitCode,
}
}
type exitMatcher struct {
exitCode int
didExit bool
actualExitCode int
}
type Exiter interface {
ExitCode() int
}
func (m *exitMatcher) Match(actual interface{}) (success bool, err error) {
exiter, ok := actual.(Exiter)
if !ok {
return false, fmt.Errorf("Exit must be passed a gexec.Exiter (Missing method ExitCode() int) Got:\n%s", format.Object(actual, 1))
}
m.actualExitCode = exiter.ExitCode()
if m.actualExitCode == -1 {
return false, nil
}
if m.exitCode == -1 {
return true, nil
}
return m.exitCode == m.actualExitCode, nil
}
func (m *exitMatcher) FailureMessage(actual interface{}) (message string) {
if m.actualExitCode == -1 {
return "Expected process to exit. It did not."
}
return format.Message(m.actualExitCode, "to match exit code:", m.exitCode)
}
func (m *exitMatcher) NegatedFailureMessage(actual interface{}) (message string) {
if m.actualExitCode == -1 {
return "you really shouldn't be able to see this!"
} else {
if m.exitCode == -1 {
return "Expected process not to exit. It did."
}
return format.Message(m.actualExitCode, "not to match exit code:", m.exitCode)
}
}
func (m *exitMatcher) MatchMayChangeInTheFuture(actual interface{}) bool {
session, ok := actual.(*Session)
if ok {
return session.ExitCode() == -1
}
return true
}
golang-gomega-1.27.10/gexec/exit_matcher_test.go 0000664 0000000 0000000 00000005464 14462163431 0021540 0 ustar 00root root 0000000 0000000 package gexec_test
import (
"os/exec"
"time"
. "github.com/onsi/gomega/gexec"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
type NeverExits struct{}
func (e NeverExits) ExitCode() int {
return -1
}
var _ = Describe("ExitMatcher", func() {
var command *exec.Cmd
var session *Session
BeforeEach(func() {
fireflyPath, err := Build("./_fixture/firefly")
Expect(err).ShouldNot(HaveOccurred())
command = exec.Command(fireflyPath, "0")
session, err = Start(command, nil, nil)
Expect(err).ShouldNot(HaveOccurred())
})
Describe("when passed something that is an Exiter", func() {
It("should act normally", func() {
failures := InterceptGomegaFailures(func() {
Expect(NeverExits{}).Should(Exit())
})
Expect(failures[0]).Should(ContainSubstring("Expected process to exit. It did not."))
})
})
Describe("when passed something that is not an Exiter", func() {
It("should error", func() {
failures := InterceptGomegaFailures(func() {
Expect("aardvark").Should(Exit())
})
Expect(failures[0]).Should(ContainSubstring("Exit must be passed a gexec.Exiter"))
})
})
Context("with no exit code", func() {
It("should say the right things when it fails", func() {
Expect(session).ShouldNot(Exit())
failures := InterceptGomegaFailures(func() {
Expect(session).Should(Exit())
})
Expect(failures[0]).Should(ContainSubstring("Expected process to exit. It did not."))
Eventually(session).Should(Exit())
Expect(session).Should(Exit())
failures = InterceptGomegaFailures(func() {
Expect(session).ShouldNot(Exit())
})
Expect(failures[0]).Should(ContainSubstring("Expected process not to exit. It did."))
})
})
Context("with an exit code", func() {
It("should say the right things when it fails", func() {
Expect(session).ShouldNot(Exit(0))
Expect(session).ShouldNot(Exit(1))
failures := InterceptGomegaFailures(func() {
Expect(session).Should(Exit(0))
})
Expect(failures[0]).Should(ContainSubstring("Expected process to exit. It did not."))
Eventually(session).Should(Exit(0))
Expect(session).Should(Exit(0))
failures = InterceptGomegaFailures(func() {
Expect(session).Should(Exit(1))
})
Expect(failures[0]).Should(ContainSubstring("to match exit code:"))
Expect(session).ShouldNot(Exit(1))
failures = InterceptGomegaFailures(func() {
Expect(session).ShouldNot(Exit(0))
})
Expect(failures[0]).Should(ContainSubstring("not to match exit code:"))
})
})
Describe("bailing out early", func() {
It("should bail out early once the process exits", func() {
t := time.Now()
failures := InterceptGomegaFailures(func() {
Eventually(session).Should(Exit(1))
})
Expect(time.Since(t)).Should(BeNumerically("<=", 500*time.Millisecond))
Expect(failures).Should(HaveLen(1))
})
})
})
golang-gomega-1.27.10/gexec/gexec_suite_test.go 0000664 0000000 0000000 00000000431 14462163431 0021355 0 ustar 00root root 0000000 0000000 package gexec_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gexec"
"testing"
)
func TestGexec(t *testing.T) {
AfterSuite(func() {
gexec.CleanupBuildArtifacts()
})
RegisterFailHandler(Fail)
RunSpecs(t, "Gexec Suite")
}
golang-gomega-1.27.10/gexec/prefixed_writer.go 0000664 0000000 0000000 00000002171 14462163431 0021217 0 ustar 00root root 0000000 0000000 // untested sections: 1
package gexec
import (
"io"
"sync"
)
/*
PrefixedWriter wraps an io.Writer, emitting the passed in prefix at the beginning of each new line.
This can be useful when running multiple gexec.Sessions concurrently - you can prefix the log output of each
session by passing in a PrefixedWriter:
gexec.Start(cmd, NewPrefixedWriter("[my-cmd] ", GinkgoWriter), NewPrefixedWriter("[my-cmd] ", GinkgoWriter))
*/
type PrefixedWriter struct {
prefix []byte
writer io.Writer
lock *sync.Mutex
atStartOfLine bool
}
func NewPrefixedWriter(prefix string, writer io.Writer) *PrefixedWriter {
return &PrefixedWriter{
prefix: []byte(prefix),
writer: writer,
lock: &sync.Mutex{},
atStartOfLine: true,
}
}
func (w *PrefixedWriter) Write(b []byte) (int, error) {
w.lock.Lock()
defer w.lock.Unlock()
toWrite := []byte{}
for _, c := range b {
if w.atStartOfLine {
toWrite = append(toWrite, w.prefix...)
}
toWrite = append(toWrite, c)
w.atStartOfLine = c == '\n'
}
_, err := w.writer.Write(toWrite)
if err != nil {
return 0, err
}
return len(b), nil
}
golang-gomega-1.27.10/gexec/prefixed_writer_test.go 0000664 0000000 0000000 00000001423 14462163431 0022255 0 ustar 00root root 0000000 0000000 package gexec_test
import (
"bytes"
. "github.com/onsi/gomega/gexec"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("PrefixedWriter", func() {
var buffer *bytes.Buffer
var writer *PrefixedWriter
BeforeEach(func() {
buffer = &bytes.Buffer{}
writer = NewPrefixedWriter("[p]", buffer)
})
It("should emit the prefix on newlines", func() {
writer.Write([]byte("abc"))
writer.Write([]byte("def\n"))
writer.Write([]byte("hij\n"))
writer.Write([]byte("\n\n"))
writer.Write([]byte("klm\n\nnop"))
writer.Write([]byte(""))
writer.Write([]byte("qrs"))
writer.Write([]byte("\ntuv\nwx"))
writer.Write([]byte("yz\n\n"))
Expect(buffer.String()).Should(Equal(`[p]abcdef
[p]hij
[p]
[p]
[p]klm
[p]
[p]nopqrs
[p]tuv
[p]wxyz
[p]
`))
})
})
golang-gomega-1.27.10/gexec/session.go 0000664 0000000 0000000 00000020416 14462163431 0017502 0 ustar 00root root 0000000 0000000 /*
Package gexec provides support for testing external processes.
*/
// untested sections: 1
package gexec
import (
"io"
"os"
"os/exec"
"sync"
"syscall"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gbytes"
)
const INVALID_EXIT_CODE = 254
type Session struct {
//The wrapped command
Command *exec.Cmd
//A *gbytes.Buffer connected to the command's stdout
Out *gbytes.Buffer
//A *gbytes.Buffer connected to the command's stderr
Err *gbytes.Buffer
//A channel that will close when the command exits
Exited <-chan struct{}
lock *sync.Mutex
exitCode int
}
/*
Start starts the passed-in *exec.Cmd command. It wraps the command in a *gexec.Session.
The session pipes the command's stdout and stderr to two *gbytes.Buffers available as properties on the session: session.Out and session.Err.
These buffers can be used with the gbytes.Say matcher to match against unread output:
Expect(session.Out).Should(gbytes.Say("foo-out"))
Expect(session.Err).Should(gbytes.Say("foo-err"))
In addition, Session satisfies the gbytes.BufferProvider interface and provides the stdout *gbytes.Buffer. This allows you to replace the first line, above, with:
Expect(session).Should(gbytes.Say("foo-out"))
When outWriter and/or errWriter are non-nil, the session will pipe stdout and/or stderr output both into the session *gybtes.Buffers and to the passed-in outWriter/errWriter.
This is useful for capturing the process's output or logging it to screen. In particular, when using Ginkgo it can be convenient to direct output to the GinkgoWriter:
session, err := Start(command, GinkgoWriter, GinkgoWriter)
This will log output when running tests in verbose mode, but - otherwise - will only log output when a test fails.
The session wrapper is responsible for waiting on the *exec.Cmd command. You *should not* call command.Wait() yourself.
Instead, to assert that the command has exited you can use the gexec.Exit matcher:
Expect(session).Should(gexec.Exit())
When the session exits it closes the stdout and stderr gbytes buffers. This will short circuit any
Eventuallys waiting for the buffers to Say something.
*/
func Start(command *exec.Cmd, outWriter io.Writer, errWriter io.Writer) (*Session, error) {
exited := make(chan struct{})
session := &Session{
Command: command,
Out: gbytes.NewBuffer(),
Err: gbytes.NewBuffer(),
Exited: exited,
lock: &sync.Mutex{},
exitCode: -1,
}
var commandOut, commandErr io.Writer
commandOut, commandErr = session.Out, session.Err
if outWriter != nil {
commandOut = io.MultiWriter(commandOut, outWriter)
}
if errWriter != nil {
commandErr = io.MultiWriter(commandErr, errWriter)
}
command.Stdout = commandOut
command.Stderr = commandErr
err := command.Start()
if err == nil {
go session.monitorForExit(exited)
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
trackedSessions = append(trackedSessions, session)
}
return session, err
}
/*
Buffer implements the gbytes.BufferProvider interface and returns s.Out
This allows you to make gbytes.Say matcher assertions against stdout without having to reference .Out:
Eventually(session).Should(gbytes.Say("foo"))
*/
func (s *Session) Buffer() *gbytes.Buffer {
return s.Out
}
/*
ExitCode returns the wrapped command's exit code. If the command hasn't exited yet, ExitCode returns -1.
To assert that the command has exited it is more convenient to use the Exit matcher:
Eventually(s).Should(gexec.Exit())
When the process exits because it has received a particular signal, the exit code will be 128+signal-value
(See http://www.tldp.org/LDP/abs/html/exitcodes.html and http://man7.org/linux/man-pages/man7/signal.7.html)
*/
func (s *Session) ExitCode() int {
s.lock.Lock()
defer s.lock.Unlock()
return s.exitCode
}
/*
Wait waits until the wrapped command exits. It can be passed an optional timeout.
If the command does not exit within the timeout, Wait will trigger a test failure.
Wait returns the session, making it possible to chain:
session.Wait().Out.Contents()
will wait for the command to exit then return the entirety of Out's contents.
Wait uses eventually under the hood and accepts the same timeout/polling intervals that eventually does.
*/
func (s *Session) Wait(timeout ...interface{}) *Session {
EventuallyWithOffset(1, s, timeout...).Should(Exit())
return s
}
/*
Kill sends the running command a SIGKILL signal. It does not wait for the process to exit.
If the command has already exited, Kill returns silently.
The session is returned to enable chaining.
*/
func (s *Session) Kill() *Session {
return s.Signal(syscall.SIGKILL)
}
/*
Interrupt sends the running command a SIGINT signal. It does not wait for the process to exit.
If the command has already exited, Interrupt returns silently.
The session is returned to enable chaining.
*/
func (s *Session) Interrupt() *Session {
return s.Signal(syscall.SIGINT)
}
/*
Terminate sends the running command a SIGTERM signal. It does not wait for the process to exit.
If the command has already exited, Terminate returns silently.
The session is returned to enable chaining.
*/
func (s *Session) Terminate() *Session {
return s.Signal(syscall.SIGTERM)
}
/*
Signal sends the running command the passed in signal. It does not wait for the process to exit.
If the command has already exited, Signal returns silently.
The session is returned to enable chaining.
*/
func (s *Session) Signal(signal os.Signal) *Session {
if s.processIsAlive() {
s.Command.Process.Signal(signal)
}
return s
}
func (s *Session) monitorForExit(exited chan<- struct{}) {
err := s.Command.Wait()
s.lock.Lock()
s.Out.Close()
s.Err.Close()
status := s.Command.ProcessState.Sys().(syscall.WaitStatus)
if status.Signaled() {
s.exitCode = 128 + int(status.Signal())
} else {
exitStatus := status.ExitStatus()
if exitStatus == -1 && err != nil {
s.exitCode = INVALID_EXIT_CODE
}
s.exitCode = exitStatus
}
s.lock.Unlock()
close(exited)
}
func (s *Session) processIsAlive() bool {
return s.ExitCode() == -1 && s.Command.Process != nil
}
var trackedSessions = []*Session{}
var trackedSessionsMutex = &sync.Mutex{}
/*
Kill sends a SIGKILL signal to all the processes started by Run, and waits for them to exit.
The timeout specified is applied to each process killed.
If any of the processes already exited, KillAndWait returns silently.
*/
func KillAndWait(timeout ...interface{}) {
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
for _, session := range trackedSessions {
session.Kill().Wait(timeout...)
}
trackedSessions = []*Session{}
}
/*
Kill sends a SIGTERM signal to all the processes started by Run, and waits for them to exit.
The timeout specified is applied to each process killed.
If any of the processes already exited, TerminateAndWait returns silently.
*/
func TerminateAndWait(timeout ...interface{}) {
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
for _, session := range trackedSessions {
session.Terminate().Wait(timeout...)
}
}
/*
Kill sends a SIGKILL signal to all the processes started by Run.
It does not wait for the processes to exit.
If any of the processes already exited, Kill returns silently.
*/
func Kill() {
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
for _, session := range trackedSessions {
session.Kill()
}
}
/*
Terminate sends a SIGTERM signal to all the processes started by Run.
It does not wait for the processes to exit.
If any of the processes already exited, Terminate returns silently.
*/
func Terminate() {
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
for _, session := range trackedSessions {
session.Terminate()
}
}
/*
Signal sends the passed in signal to all the processes started by Run.
It does not wait for the processes to exit.
If any of the processes already exited, Signal returns silently.
*/
func Signal(signal os.Signal) {
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
for _, session := range trackedSessions {
session.Signal(signal)
}
}
/*
Interrupt sends the SIGINT signal to all the processes started by Run.
It does not wait for the processes to exit.
If any of the processes already exited, Interrupt returns silently.
*/
func Interrupt() {
trackedSessionsMutex.Lock()
defer trackedSessionsMutex.Unlock()
for _, session := range trackedSessions {
session.Interrupt()
}
}
golang-gomega-1.27.10/gexec/session_test.go 0000664 0000000 0000000 00000031027 14462163431 0020541 0 ustar 00root root 0000000 0000000 //go:build !windows
// +build !windows
package gexec_test
import (
"io"
"os/exec"
"syscall"
"time"
. "github.com/onsi/gomega/gbytes"
. "github.com/onsi/gomega/gexec"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("Session", func() {
Context("firefly binary", func() {
var fireflyPath string
var command *exec.Cmd
var session *Session
var outWriter, errWriter io.Writer
BeforeEach(func() {
outWriter = nil
errWriter = nil
var err error
fireflyPath, err = Build("./_fixture/firefly")
Expect(err).ShouldNot(HaveOccurred())
})
JustBeforeEach(func() {
command = exec.Command(fireflyPath)
var err error
session, err = Start(command, outWriter, errWriter)
Expect(err).ShouldNot(HaveOccurred())
})
Context("running a command", func() {
It("should start the process", func() {
Expect(command.Process).ShouldNot(BeNil())
})
It("should wrap the process's stdout and stderr with gbytes buffers", func() {
Eventually(session.Out).Should(Say("We've done the impossible, and that makes us mighty"))
Eventually(session.Err).Should(Say("Ah, curse your sudden but inevitable betrayal!"))
defer session.Out.CancelDetects()
select {
case <-session.Out.Detect("Can we maybe vote on the whole murdering people issue"):
Eventually(session).Should(Exit(0))
case <-session.Out.Detect("I swear by my pretty floral bonnet, I will end you."):
Eventually(session).Should(Exit(1))
case <-session.Out.Detect("My work's illegal, but at least it's honest."):
Eventually(session).Should(Exit(2))
case <-time.After(5 * time.Second):
Fail("timed out waiting for detection")
}
})
It("should satisfy the gbytes.BufferProvider interface, passing Stdout", func() {
Eventually(session).Should(Say("We've done the impossible, and that makes us mighty"))
Eventually(session).Should(Exit())
})
})
Describe("providing the exit code", func() {
It("should provide the app's exit code", func() {
Expect(session.ExitCode()).Should(Equal(-1))
Eventually(session).Should(Exit())
Expect(session.ExitCode()).Should(BeNumerically(">=", 0))
Expect(session.ExitCode()).Should(BeNumerically("<", 3))
})
})
Describe("wait", func() {
It("should wait till the command exits", func() {
Expect(session.ExitCode()).Should(Equal(-1))
Expect(session.Wait().ExitCode()).Should(BeNumerically(">=", 0))
Expect(session.Wait().ExitCode()).Should(BeNumerically("<", 3))
})
})
Describe("exited", func() {
It("should close when the command exits", func() {
Eventually(session.Exited).Should(BeClosed())
Expect(session.ExitCode()).ShouldNot(Equal(-1))
})
})
Describe("kill", func() {
It("should kill the command", func() {
session, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session.Kill()
Eventually(session).Should(Exit(128 + 9))
})
})
Describe("interrupt", func() {
It("should interrupt the command", func() {
session, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session.Interrupt()
Eventually(session).Should(Exit(128 + 2))
})
})
Describe("terminate", func() {
It("should terminate the command", func() {
session, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session.Terminate()
Eventually(session).Should(Exit(128 + 15))
})
})
Describe("signal", func() {
It("should send the signal to the command", func() {
session, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session.Signal(syscall.SIGABRT)
Eventually(session).WithTimeout(5 * time.Second).Should(Exit(128 + 6))
})
It("should ignore sending a signal if the command did not start", func() {
session, err := Start(exec.Command("notexisting"), GinkgoWriter, GinkgoWriter)
Expect(err).To(HaveOccurred())
Expect(func() { session.Signal(syscall.SIGUSR1) }).NotTo(Panic())
})
})
Context("tracking sessions", func() {
BeforeEach(func() {
KillAndWait()
})
Describe("kill", func() {
It("should kill all the started sessions", func() {
session1, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
Kill()
Eventually(session1).Should(Exit(128 + 9))
Eventually(session2).Should(Exit(128 + 9))
Eventually(session3).Should(Exit(128 + 9))
})
It("should not track unstarted sessions", func() {
_, err := Start(exec.Command("does not exist", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).Should(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
Kill()
Eventually(session2).Should(Exit(128 + 9))
Eventually(session3).Should(Exit(128 + 9))
})
})
Describe("killAndWait", func() {
It("should kill all the started sessions and wait for them to finish", func() {
session1, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
KillAndWait()
Expect(session1).Should(Exit(128+9), "Should have exited")
Expect(session2).Should(Exit(128+9), "Should have exited")
Expect(session3).Should(Exit(128+9), "Should have exited")
})
})
Describe("terminate", func() {
It("should terminate all the started sessions", func() {
session1, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
Terminate()
Eventually(session1).Should(Exit(128 + 15))
Eventually(session2).Should(Exit(128 + 15))
Eventually(session3).Should(Exit(128 + 15))
})
})
Describe("terminateAndWait", func() {
It("should terminate all the started sessions, and wait for them to exit", func() {
session1, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
TerminateAndWait()
Expect(session1).Should(Exit(128+15), "Should have exited")
Expect(session2).Should(Exit(128+15), "Should have exited")
Expect(session3).Should(Exit(128+15), "Should have exited")
})
})
Describe("signal", func() {
It("should signal all the started sessions", func() {
session1, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
Signal(syscall.SIGABRT)
Eventually(session1).WithTimeout(5 * time.Second).Should(Exit(128 + 6))
Eventually(session2).WithTimeout(5 * time.Second).Should(Exit(128 + 6))
Eventually(session3).WithTimeout(5 * time.Second).Should(Exit(128 + 6))
})
})
Describe("interrupt", func() {
It("should interrupt all the started sessions, and not wait", func() {
session1, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session2, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
session3, err := Start(exec.Command("sleep", "10000000"), GinkgoWriter, GinkgoWriter)
Expect(err).ShouldNot(HaveOccurred())
Interrupt()
Eventually(session1).Should(Exit(128 + 2))
Eventually(session2).Should(Exit(128 + 2))
Eventually(session3).Should(Exit(128 + 2))
})
})
})
When("the command exits", func() {
It("should close the buffers", func() {
Eventually(session).Should(Exit())
Expect(session.Out.Closed()).Should(BeTrue())
Expect(session.Err.Closed()).Should(BeTrue())
Expect(session.Out).Should(Say("We've done the impossible, and that makes us mighty"))
})
var So = It
So("this means that eventually should short circuit", func() {
t := time.Now()
failures := InterceptGomegaFailures(func() {
Eventually(session).Should(Say("blah blah blah blah blah"))
})
Expect(time.Since(t)).Should(BeNumerically("<", time.Second))
Expect(failures).Should(HaveLen(1))
})
})
When("wrapping out and err", func() {
var (
outWriterBuffer, errWriterBuffer *Buffer
)
BeforeEach(func() {
outWriterBuffer = NewBuffer()
outWriter = outWriterBuffer
errWriterBuffer = NewBuffer()
errWriter = errWriterBuffer
})
It("should route to both the provided writers and the gbytes buffers", func() {
Eventually(session.Out).Should(Say("We've done the impossible, and that makes us mighty"))
Eventually(session.Err).Should(Say("Ah, curse your sudden but inevitable betrayal!"))
Expect(outWriterBuffer.Contents()).Should(ContainSubstring("We've done the impossible, and that makes us mighty"))
Expect(errWriterBuffer.Contents()).Should(ContainSubstring("Ah, curse your sudden but inevitable betrayal!"))
Eventually(session).Should(Exit())
Expect(outWriterBuffer.Contents()).Should(Equal(session.Out.Contents()))
Expect(errWriterBuffer.Contents()).Should(Equal(session.Err.Contents()))
})
When("discarding the output of the command", func() {
BeforeEach(func() {
outWriter = io.Discard
errWriter = io.Discard
})
It("executes succesfuly", func() {
Eventually(session).Should(Exit())
})
})
})
})
Context("firefly tests", func() {
var fireflyTestPath string
var command *exec.Cmd
var session *Session
var outWriter, errWriter io.Writer
BeforeEach(func() {
outWriter = nil
errWriter = nil
var err error
fireflyTestPath, err = CompileTest("./_fixture/firefly")
Expect(err).ShouldNot(HaveOccurred())
})
JustBeforeEach(func() {
command = exec.Command(fireflyTestPath)
var err error
session, err = Start(command, outWriter, errWriter)
Expect(err).ShouldNot(HaveOccurred())
})
When("wrapping out and err", func() {
var (
outWriterBuffer, errWriterBuffer *Buffer
)
BeforeEach(func() {
outWriterBuffer = NewBuffer()
outWriter = outWriterBuffer
errWriterBuffer = NewBuffer()
errWriter = errWriterBuffer
})
It("should route to both the provided writers and the gbytes buffers", func() {
Eventually(session.Out).Should(Say("PASS"))
Eventually(session.Err).Should(Say(""))
Expect(outWriterBuffer.Contents()).Should(ContainSubstring("PASS"))
Expect(errWriterBuffer.Contents()).Should(BeEmpty())
Eventually(session).Should(Exit())
Expect(outWriterBuffer.Contents()).Should(Equal(session.Out.Contents()))
Expect(errWriterBuffer.Contents()).Should(Equal(session.Err.Contents()))
})
When("discarding the output of the command", func() {
BeforeEach(func() {
outWriter = io.Discard
errWriter = io.Discard
})
It("executes succesfuly", func() {
Eventually(session).Should(Exit())
})
})
})
})
Describe("when the command fails to start", func() {
It("should return an error", func() {
_, err := Start(exec.Command("agklsjdfas"), nil, nil)
Expect(err).Should(HaveOccurred())
})
})
})
golang-gomega-1.27.10/ghttp/ 0000775 0000000 0000000 00000000000 14462163431 0015520 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/ghttp/handlers.go 0000664 0000000 0000000 00000035775 14462163431 0017670 0 ustar 00root root 0000000 0000000 // untested sections: 3
package ghttp
import (
"encoding/base64"
"encoding/json"
"fmt"
"net/http"
"net/url"
"reflect"
"strings"
"github.com/golang/protobuf/proto"
"github.com/onsi/gomega"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/internal/gutil"
"github.com/onsi/gomega/types"
)
type GHTTPWithGomega struct {
gomega Gomega
}
func NewGHTTPWithGomega(gomega Gomega) *GHTTPWithGomega {
return &GHTTPWithGomega{
gomega: gomega,
}
}
//CombineHandler takes variadic list of handlers and produces one handler
//that calls each handler in order.
func CombineHandlers(handlers ...http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
for _, handler := range handlers {
handler(w, req)
}
}
}
//VerifyRequest returns a handler that verifies that a request uses the specified method to connect to the specified path
//You may also pass in an optional rawQuery string which is tested against the request's `req.URL.RawQuery`
//
//For path, you may pass in a string, in which case strict equality will be applied
//Alternatively you can pass in a matcher (ContainSubstring("/foo") and MatchRegexp("/foo/[a-f0-9]+") for example)
func (g GHTTPWithGomega) VerifyRequest(method string, path interface{}, rawQuery ...string) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
g.gomega.Expect(req.Method).Should(Equal(method), "Method mismatch")
switch p := path.(type) {
case types.GomegaMatcher:
g.gomega.Expect(req.URL.Path).Should(p, "Path mismatch")
default:
g.gomega.Expect(req.URL.Path).Should(Equal(path), "Path mismatch")
}
if len(rawQuery) > 0 {
values, err := url.ParseQuery(rawQuery[0])
g.gomega.Expect(err).ShouldNot(HaveOccurred(), "Expected RawQuery is malformed")
g.gomega.Expect(req.URL.Query()).Should(Equal(values), "RawQuery mismatch")
}
}
}
//VerifyContentType returns a handler that verifies that a request has a Content-Type header set to the
//specified value
func (g GHTTPWithGomega) VerifyContentType(contentType string) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
g.gomega.Expect(req.Header.Get("Content-Type")).Should(Equal(contentType))
}
}
//VerifyMimeType returns a handler that verifies that a request has a specified mime type set
//in Content-Type header
func (g GHTTPWithGomega) VerifyMimeType(mimeType string) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
g.gomega.Expect(strings.Split(req.Header.Get("Content-Type"), ";")[0]).Should(Equal(mimeType))
}
}
//VerifyBasicAuth returns a handler that verifies the request contains a BasicAuth Authorization header
//matching the passed in username and password
func (g GHTTPWithGomega) VerifyBasicAuth(username string, password string) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
auth := req.Header.Get("Authorization")
g.gomega.Expect(auth).ShouldNot(Equal(""), "Authorization header must be specified")
decoded, err := base64.StdEncoding.DecodeString(auth[6:])
g.gomega.Expect(err).ShouldNot(HaveOccurred())
g.gomega.Expect(string(decoded)).Should(Equal(fmt.Sprintf("%s:%s", username, password)), "Authorization mismatch")
}
}
//VerifyHeader returns a handler that verifies the request contains the passed in headers.
//The passed in header keys are first canonicalized via http.CanonicalHeaderKey.
//
//The request must contain *all* the passed in headers, but it is allowed to have additional headers
//beyond the passed in set.
func (g GHTTPWithGomega) VerifyHeader(header http.Header) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
for key, values := range header {
key = http.CanonicalHeaderKey(key)
g.gomega.Expect(req.Header[key]).Should(Equal(values), "Header mismatch for key: %s", key)
}
}
}
//VerifyHeaderKV returns a handler that verifies the request contains a header matching the passed in key and values
//(recall that a `http.Header` is a mapping from string (key) to []string (values))
//It is a convenience wrapper around `VerifyHeader` that allows you to avoid having to create an `http.Header` object.
func (g GHTTPWithGomega) VerifyHeaderKV(key string, values ...string) http.HandlerFunc {
return g.VerifyHeader(http.Header{key: values})
}
//VerifyBody returns a handler that verifies that the body of the request matches the passed in byte array.
//It does this using Equal().
func (g GHTTPWithGomega) VerifyBody(expectedBody []byte) http.HandlerFunc {
return CombineHandlers(
func(w http.ResponseWriter, req *http.Request) {
body, err := gutil.ReadAll(req.Body)
req.Body.Close()
g.gomega.Expect(err).ShouldNot(HaveOccurred())
g.gomega.Expect(body).Should(Equal(expectedBody), "Body Mismatch")
},
)
}
//VerifyJSON returns a handler that verifies that the body of the request is a valid JSON representation
//matching the passed in JSON string. It does this using Gomega's MatchJSON method
//
//VerifyJSON also verifies that the request's content type is application/json
func (g GHTTPWithGomega) VerifyJSON(expectedJSON string) http.HandlerFunc {
return CombineHandlers(
g.VerifyMimeType("application/json"),
func(w http.ResponseWriter, req *http.Request) {
body, err := gutil.ReadAll(req.Body)
req.Body.Close()
g.gomega.Expect(err).ShouldNot(HaveOccurred())
g.gomega.Expect(body).Should(MatchJSON(expectedJSON), "JSON Mismatch")
},
)
}
//VerifyJSONRepresenting is similar to VerifyJSON. Instead of taking a JSON string, however, it
//takes an arbitrary JSON-encodable object and verifies that the requests's body is a JSON representation
//that matches the object
func (g GHTTPWithGomega) VerifyJSONRepresenting(object interface{}) http.HandlerFunc {
data, err := json.Marshal(object)
g.gomega.Expect(err).ShouldNot(HaveOccurred())
return CombineHandlers(
g.VerifyMimeType("application/json"),
g.VerifyJSON(string(data)),
)
}
//VerifyForm returns a handler that verifies a request contains the specified form values.
//
//The request must contain *all* of the specified values, but it is allowed to have additional
//form values beyond the passed in set.
func (g GHTTPWithGomega) VerifyForm(values url.Values) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
err := r.ParseForm()
g.gomega.Expect(err).ShouldNot(HaveOccurred())
for key, vals := range values {
g.gomega.Expect(r.Form[key]).Should(Equal(vals), "Form mismatch for key: %s", key)
}
}
}
//VerifyFormKV returns a handler that verifies a request contains a form key with the specified values.
//
//It is a convenience wrapper around `VerifyForm` that lets you avoid having to create a `url.Values` object.
func (g GHTTPWithGomega) VerifyFormKV(key string, values ...string) http.HandlerFunc {
return g.VerifyForm(url.Values{key: values})
}
//VerifyProtoRepresenting returns a handler that verifies that the body of the request is a valid protobuf
//representation of the passed message.
//
//VerifyProtoRepresenting also verifies that the request's content type is application/x-protobuf
func (g GHTTPWithGomega) VerifyProtoRepresenting(expected proto.Message) http.HandlerFunc {
return CombineHandlers(
g.VerifyContentType("application/x-protobuf"),
func(w http.ResponseWriter, req *http.Request) {
body, err := gutil.ReadAll(req.Body)
g.gomega.Expect(err).ShouldNot(HaveOccurred())
req.Body.Close()
expectedType := reflect.TypeOf(expected)
actualValuePtr := reflect.New(expectedType.Elem())
actual, ok := actualValuePtr.Interface().(proto.Message)
g.gomega.Expect(ok).Should(BeTrue(), "Message value is not a proto.Message")
err = proto.Unmarshal(body, actual)
g.gomega.Expect(err).ShouldNot(HaveOccurred(), "Failed to unmarshal protobuf")
g.gomega.Expect(actual).Should(Equal(expected), "ProtoBuf Mismatch")
},
)
}
func copyHeader(src http.Header, dst http.Header) {
for key, value := range src {
dst[key] = value
}
}
/*
RespondWith returns a handler that responds to a request with the specified status code and body
Body may be a string or []byte
Also, RespondWith can be given an optional http.Header. The headers defined therein will be added to the response headers.
*/
func (g GHTTPWithGomega) RespondWith(statusCode int, body interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
if len(optionalHeader) == 1 {
copyHeader(optionalHeader[0], w.Header())
}
w.WriteHeader(statusCode)
switch x := body.(type) {
case string:
w.Write([]byte(x))
case []byte:
w.Write(x)
default:
g.gomega.Expect(body).Should(BeNil(), "Invalid type for body. Should be string or []byte.")
}
}
}
/*
RespondWithPtr returns a handler that responds to a request with the specified status code and body
Unlike RespondWith, you pass RepondWithPtr a pointer to the status code and body allowing different tests
to share the same setup but specify different status codes and bodies.
Also, RespondWithPtr can be given an optional http.Header. The headers defined therein will be added to the response headers.
Since the http.Header can be mutated after the fact you don't need to pass in a pointer.
*/
func (g GHTTPWithGomega) RespondWithPtr(statusCode *int, body interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
if len(optionalHeader) == 1 {
copyHeader(optionalHeader[0], w.Header())
}
w.WriteHeader(*statusCode)
if body != nil {
switch x := (body).(type) {
case *string:
w.Write([]byte(*x))
case *[]byte:
w.Write(*x)
default:
g.gomega.Expect(body).Should(BeNil(), "Invalid type for body. Should be string or []byte.")
}
}
}
}
/*
RespondWithJSONEncoded returns a handler that responds to a request with the specified status code and a body
containing the JSON-encoding of the passed in object
Also, RespondWithJSONEncoded can be given an optional http.Header. The headers defined therein will be added to the response headers.
*/
func (g GHTTPWithGomega) RespondWithJSONEncoded(statusCode int, object interface{}, optionalHeader ...http.Header) http.HandlerFunc {
data, err := json.Marshal(object)
g.gomega.Expect(err).ShouldNot(HaveOccurred())
var headers http.Header
if len(optionalHeader) == 1 {
headers = optionalHeader[0]
} else {
headers = make(http.Header)
}
if _, found := headers["Content-Type"]; !found {
headers["Content-Type"] = []string{"application/json"}
}
return RespondWith(statusCode, string(data), headers)
}
/*
RespondWithJSONEncodedPtr behaves like RespondWithJSONEncoded but takes a pointer
to a status code and object.
This allows different tests to share the same setup but specify different status codes and JSON-encoded
objects.
Also, RespondWithJSONEncodedPtr can be given an optional http.Header. The headers defined therein will be added to the response headers.
Since the http.Header can be mutated after the fact you don't need to pass in a pointer.
*/
func (g GHTTPWithGomega) RespondWithJSONEncodedPtr(statusCode *int, object interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
data, err := json.Marshal(object)
g.gomega.Expect(err).ShouldNot(HaveOccurred())
var headers http.Header
if len(optionalHeader) == 1 {
headers = optionalHeader[0]
} else {
headers = make(http.Header)
}
if _, found := headers["Content-Type"]; !found {
headers["Content-Type"] = []string{"application/json"}
}
copyHeader(headers, w.Header())
w.WriteHeader(*statusCode)
w.Write(data)
}
}
//RespondWithProto returns a handler that responds to a request with the specified status code and a body
//containing the protobuf serialization of the provided message.
//
//Also, RespondWithProto can be given an optional http.Header. The headers defined therein will be added to the response headers.
func (g GHTTPWithGomega) RespondWithProto(statusCode int, message proto.Message, optionalHeader ...http.Header) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
data, err := proto.Marshal(message)
g.gomega.Expect(err).ShouldNot(HaveOccurred())
var headers http.Header
if len(optionalHeader) == 1 {
headers = optionalHeader[0]
} else {
headers = make(http.Header)
}
if _, found := headers["Content-Type"]; !found {
headers["Content-Type"] = []string{"application/x-protobuf"}
}
copyHeader(headers, w.Header())
w.WriteHeader(statusCode)
w.Write(data)
}
}
func VerifyRequest(method string, path interface{}, rawQuery ...string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyRequest(method, path, rawQuery...)
}
func VerifyContentType(contentType string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyContentType(contentType)
}
func VerifyMimeType(mimeType string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyMimeType(mimeType)
}
func VerifyBasicAuth(username string, password string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyBasicAuth(username, password)
}
func VerifyHeader(header http.Header) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyHeader(header)
}
func VerifyHeaderKV(key string, values ...string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyHeaderKV(key, values...)
}
func VerifyBody(expectedBody []byte) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyBody(expectedBody)
}
func VerifyJSON(expectedJSON string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyJSON(expectedJSON)
}
func VerifyJSONRepresenting(object interface{}) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyJSONRepresenting(object)
}
func VerifyForm(values url.Values) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyForm(values)
}
func VerifyFormKV(key string, values ...string) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyFormKV(key, values...)
}
func VerifyProtoRepresenting(expected proto.Message) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).VerifyProtoRepresenting(expected)
}
func RespondWith(statusCode int, body interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).RespondWith(statusCode, body, optionalHeader...)
}
func RespondWithPtr(statusCode *int, body interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).RespondWithPtr(statusCode, body, optionalHeader...)
}
func RespondWithJSONEncoded(statusCode int, object interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).RespondWithJSONEncoded(statusCode, object, optionalHeader...)
}
func RespondWithJSONEncodedPtr(statusCode *int, object interface{}, optionalHeader ...http.Header) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).RespondWithJSONEncodedPtr(statusCode, object, optionalHeader...)
}
func RespondWithProto(statusCode int, message proto.Message, optionalHeader ...http.Header) http.HandlerFunc {
return NewGHTTPWithGomega(gomega.Default).RespondWithProto(statusCode, message, optionalHeader...)
}
golang-gomega-1.27.10/ghttp/protobuf/ 0000775 0000000 0000000 00000000000 14462163431 0017360 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/ghttp/protobuf/protobuf.go 0000664 0000000 0000000 00000000107 14462163431 0021545 0 ustar 00root root 0000000 0000000 package protobuf
//go:generate protoc --go_out=. simple_message.proto
golang-gomega-1.27.10/ghttp/protobuf/simple_message.pb.go 0000664 0000000 0000000 00000002522 14462163431 0023305 0 ustar 00root root 0000000 0000000 // Code generated by protoc-gen-go.
// source: simple_message.proto
// DO NOT EDIT!
/*
Package protobuf is a generated protocol buffer package.
It is generated from these files:
simple_message.proto
It has these top-level messages:
SimpleMessage
*/
package protobuf
import proto "github.com/golang/protobuf/proto"
import fmt "fmt"
import math "math"
// Reference imports to suppress errors if they are not otherwise used.
var _ = proto.Marshal
var _ = fmt.Errorf
var _ = math.Inf
type SimpleMessage struct {
Description *string `protobuf:"bytes,1,req,name=description" json:"description,omitempty"`
Id *int32 `protobuf:"varint,2,req,name=id" json:"id,omitempty"`
Metadata *string `protobuf:"bytes,3,opt,name=metadata" json:"metadata,omitempty"`
XXX_unrecognized []byte `json:"-"`
}
func (m *SimpleMessage) Reset() { *m = SimpleMessage{} }
func (m *SimpleMessage) String() string { return proto.CompactTextString(m) }
func (*SimpleMessage) ProtoMessage() {}
func (m *SimpleMessage) GetDescription() string {
if m != nil && m.Description != nil {
return *m.Description
}
return ""
}
func (m *SimpleMessage) GetId() int32 {
if m != nil && m.Id != nil {
return *m.Id
}
return 0
}
func (m *SimpleMessage) GetMetadata() string {
if m != nil && m.Metadata != nil {
return *m.Metadata
}
return ""
}
golang-gomega-1.27.10/ghttp/protobuf/simple_message.proto 0000664 0000000 0000000 00000000243 14462163431 0023441 0 ustar 00root root 0000000 0000000 syntax = "proto2";
package protobuf;
message SimpleMessage {
required string description = 1;
required int32 id = 2;
optional string metadata = 3;
}
golang-gomega-1.27.10/ghttp/test_server.go 0000664 0000000 0000000 00000032062 14462163431 0020417 0 ustar 00root root 0000000 0000000 /*
Package ghttp supports testing HTTP clients by providing a test server (simply a thin wrapper around httptest's server) that supports
registering multiple handlers. Incoming requests are not routed between the different handlers
- rather it is merely the order of the handlers that matters. The first request is handled by the first
registered handler, the second request by the second handler, etc.
The intent here is to have each handler *verify* that the incoming request is valid. To accomplish, ghttp
also provides a collection of bite-size handlers that each perform one aspect of request verification. These can
be composed together and registered with a ghttp server. The result is an expressive language for describing
the requests generated by the client under test.
Here's a simple example, note that the server handler is only defined in one BeforeEach and then modified, as required, by the nested BeforeEaches.
A more comprehensive example is available at https://onsi.github.io/gomega/#_testing_http_clients
var _ = Describe("A Sprockets Client", func() {
var server *ghttp.Server
var client *SprocketClient
BeforeEach(func() {
server = ghttp.NewServer()
client = NewSprocketClient(server.URL(), "skywalker", "tk427")
})
AfterEach(func() {
server.Close()
})
Describe("fetching sprockets", func() {
var statusCode int
var sprockets []Sprocket
BeforeEach(func() {
statusCode = http.StatusOK
sprockets = []Sprocket{}
server.AppendHandlers(ghttp.CombineHandlers(
ghttp.VerifyRequest("GET", "/sprockets"),
ghttp.VerifyBasicAuth("skywalker", "tk427"),
ghttp.RespondWithJSONEncodedPtr(&statusCode, &sprockets),
))
})
When("requesting all sprockets", func() {
When("the response is successful", func() {
BeforeEach(func() {
sprockets = []Sprocket{
NewSprocket("Alfalfa"),
NewSprocket("Banana"),
}
})
It("should return the returned sprockets", func() {
Expect(client.Sprockets()).Should(Equal(sprockets))
})
})
When("the response is missing", func() {
BeforeEach(func() {
statusCode = http.StatusNotFound
})
It("should return an empty list of sprockets", func() {
Expect(client.Sprockets()).Should(BeEmpty())
})
})
When("the response fails to authenticate", func() {
BeforeEach(func() {
statusCode = http.StatusUnauthorized
})
It("should return an AuthenticationError error", func() {
sprockets, err := client.Sprockets()
Expect(sprockets).Should(BeEmpty())
Expect(err).Should(MatchError(AuthenticationError))
})
})
When("the response is a server failure", func() {
BeforeEach(func() {
statusCode = http.StatusInternalServerError
})
It("should return an InternalError error", func() {
sprockets, err := client.Sprockets()
Expect(sprockets).Should(BeEmpty())
Expect(err).Should(MatchError(InternalError))
})
})
})
When("requesting some sprockets", func() {
BeforeEach(func() {
sprockets = []Sprocket{
NewSprocket("Alfalfa"),
NewSprocket("Banana"),
}
server.WrapHandler(0, ghttp.VerifyRequest("GET", "/sprockets", "filter=FOOD"))
})
It("should make the request with a filter", func() {
Expect(client.Sprockets("food")).Should(Equal(sprockets))
})
})
})
})
*/
// untested sections: 5
package ghttp
import (
"fmt"
"io"
"net/http"
"net/http/httptest"
"net/http/httputil"
"reflect"
"regexp"
"strings"
"sync"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/internal/gutil"
)
func new() *Server {
return &Server{
AllowUnhandledRequests: false,
UnhandledRequestStatusCode: http.StatusInternalServerError,
rwMutex: &sync.RWMutex{},
}
}
type routedHandler struct {
method string
pathRegexp *regexp.Regexp
path string
handler http.HandlerFunc
}
// NewServer returns a new `*ghttp.Server` that wraps an `httptest` server. The server is started automatically.
func NewServer() *Server {
s := new()
s.HTTPTestServer = httptest.NewServer(s)
return s
}
// NewUnstartedServer return a new, unstarted, `*ghttp.Server`. Useful for specifying a custom listener on `server.HTTPTestServer`.
func NewUnstartedServer() *Server {
s := new()
s.HTTPTestServer = httptest.NewUnstartedServer(s)
return s
}
// NewTLSServer returns a new `*ghttp.Server` that wraps an `httptest` TLS server. The server is started automatically.
func NewTLSServer() *Server {
s := new()
s.HTTPTestServer = httptest.NewTLSServer(s)
return s
}
type Server struct {
//The underlying httptest server
HTTPTestServer *httptest.Server
//Defaults to false. If set to true, the Server will allow more requests than there are registered handlers.
//Direct use of this property is deprecated and is likely to be removed, use GetAllowUnhandledRequests and SetAllowUnhandledRequests instead.
AllowUnhandledRequests bool
//The status code returned when receiving an unhandled request.
//Defaults to http.StatusInternalServerError.
//Only applies if AllowUnhandledRequests is true
//Direct use of this property is deprecated and is likely to be removed, use GetUnhandledRequestStatusCode and SetUnhandledRequestStatusCode instead.
UnhandledRequestStatusCode int
//If provided, ghttp will log about each request received to the provided io.Writer
//Defaults to nil
//If you're using Ginkgo, set this to GinkgoWriter to get improved output during failures
Writer io.Writer
receivedRequests []*http.Request
requestHandlers []http.HandlerFunc
routedHandlers []routedHandler
rwMutex *sync.RWMutex
calls int
}
//Start() starts an unstarted ghttp server. It is a catastrophic error to call Start more than once (thanks, httptest).
func (s *Server) Start() {
s.HTTPTestServer.Start()
}
//URL() returns a url that will hit the server
func (s *Server) URL() string {
s.rwMutex.RLock()
defer s.rwMutex.RUnlock()
return s.HTTPTestServer.URL
}
//Addr() returns the address on which the server is listening.
func (s *Server) Addr() string {
s.rwMutex.RLock()
defer s.rwMutex.RUnlock()
return s.HTTPTestServer.Listener.Addr().String()
}
//Close() should be called at the end of each test. It spins down and cleans up the test server.
func (s *Server) Close() {
s.rwMutex.Lock()
server := s.HTTPTestServer
s.HTTPTestServer = nil
s.rwMutex.Unlock()
if server != nil {
server.Close()
}
}
//ServeHTTP() makes Server an http.Handler
//When the server receives a request it handles the request in the following order:
//
//1. If the request matches a handler registered with RouteToHandler, that handler is called.
//2. Otherwise, if there are handlers registered via AppendHandlers, those handlers are called in order.
//3. If all registered handlers have been called then:
// a) If AllowUnhandledRequests is set to true, the request will be handled with response code of UnhandledRequestStatusCode
// b) If AllowUnhandledRequests is false, the request will not be handled and the current test will be marked as failed.
func (s *Server) ServeHTTP(w http.ResponseWriter, req *http.Request) {
s.rwMutex.Lock()
defer func() {
e := recover()
if e != nil {
w.WriteHeader(http.StatusInternalServerError)
}
//If the handler panics GHTTP will silently succeed. This is bad™.
//To catch this case we need to fail the test if the handler has panicked.
//However, if the handler is panicking because Ginkgo's causing it to panic (i.e. an assertion failed)
//then we shouldn't double-report the error as this will confuse people.
//So: step 1, if this is a Ginkgo panic - do nothing, Ginkgo's aware of the failure
eAsString, ok := e.(string)
if ok && strings.Contains(eAsString, "defer GinkgoRecover()") {
return
}
//If we're here, we have to do step 2: assert that the error is nil. This assertion will
//allow us to fail the test suite (note: we can't call Fail since Gomega is not allowed to import Ginkgo).
//Since a failed assertion throws a panic, and we are likely in a goroutine, we need to defer within our defer!
defer func() {
recover()
}()
Expect(e).Should(BeNil(), "Handler Panicked")
}()
if s.Writer != nil {
s.Writer.Write([]byte(fmt.Sprintf("GHTTP Received Request: %s - %s\n", req.Method, req.URL)))
}
s.receivedRequests = append(s.receivedRequests, req)
if routedHandler, ok := s.handlerForRoute(req.Method, req.URL.Path); ok {
s.rwMutex.Unlock()
routedHandler(w, req)
} else if s.calls < len(s.requestHandlers) {
h := s.requestHandlers[s.calls]
s.calls++
s.rwMutex.Unlock()
h(w, req)
} else {
s.rwMutex.Unlock()
if s.GetAllowUnhandledRequests() {
gutil.ReadAll(req.Body)
req.Body.Close()
w.WriteHeader(s.GetUnhandledRequestStatusCode())
} else {
formatted, err := httputil.DumpRequest(req, true)
Expect(err).NotTo(HaveOccurred(), "Encountered error while dumping HTTP request")
Expect(string(formatted)).Should(BeNil(), "Received Unhandled Request")
}
}
}
//ReceivedRequests is an array containing all requests received by the server (both handled and unhandled requests)
func (s *Server) ReceivedRequests() []*http.Request {
s.rwMutex.RLock()
defer s.rwMutex.RUnlock()
return s.receivedRequests
}
//RouteToHandler can be used to register handlers that will always handle requests that match
//the passed in method and path.
//
//The path may be either a string object or a *regexp.Regexp.
func (s *Server) RouteToHandler(method string, path interface{}, handler http.HandlerFunc) {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
rh := routedHandler{
method: method,
handler: handler,
}
switch p := path.(type) {
case *regexp.Regexp:
rh.pathRegexp = p
case string:
rh.path = p
default:
panic("path must be a string or a regular expression")
}
for i, existingRH := range s.routedHandlers {
if existingRH.method == method &&
reflect.DeepEqual(existingRH.pathRegexp, rh.pathRegexp) &&
existingRH.path == rh.path {
s.routedHandlers[i] = rh
return
}
}
s.routedHandlers = append(s.routedHandlers, rh)
}
func (s *Server) handlerForRoute(method string, path string) (http.HandlerFunc, bool) {
for _, rh := range s.routedHandlers {
if rh.method == method {
if rh.pathRegexp != nil {
if rh.pathRegexp.Match([]byte(path)) {
return rh.handler, true
}
} else if rh.path == path {
return rh.handler, true
}
}
}
return nil, false
}
//AppendHandlers will appends http.HandlerFuncs to the server's list of registered handlers. The first incoming request is handled by the first handler, the second by the second, etc...
func (s *Server) AppendHandlers(handlers ...http.HandlerFunc) {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
s.requestHandlers = append(s.requestHandlers, handlers...)
}
//SetHandler overrides the registered handler at the passed in index with the passed in handler
//This is useful, for example, when a server has been set up in a shared context, but must be tweaked
//for a particular test.
func (s *Server) SetHandler(index int, handler http.HandlerFunc) {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
s.requestHandlers[index] = handler
}
//GetHandler returns the handler registered at the passed in index.
func (s *Server) GetHandler(index int) http.HandlerFunc {
s.rwMutex.RLock()
defer s.rwMutex.RUnlock()
return s.requestHandlers[index]
}
func (s *Server) Reset() {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
s.HTTPTestServer.CloseClientConnections()
s.calls = 0
s.receivedRequests = nil
s.requestHandlers = nil
s.routedHandlers = nil
}
//WrapHandler combines the passed in handler with the handler registered at the passed in index.
//This is useful, for example, when a server has been set up in a shared context but must be tweaked
//for a particular test.
//
//If the currently registered handler is A, and the new passed in handler is B then
//WrapHandler will generate a new handler that first calls A, then calls B, and assign it to index
func (s *Server) WrapHandler(index int, handler http.HandlerFunc) {
existingHandler := s.GetHandler(index)
s.SetHandler(index, CombineHandlers(existingHandler, handler))
}
func (s *Server) CloseClientConnections() {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
s.HTTPTestServer.CloseClientConnections()
}
//SetAllowUnhandledRequests enables the server to accept unhandled requests.
func (s *Server) SetAllowUnhandledRequests(allowUnhandledRequests bool) {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
s.AllowUnhandledRequests = allowUnhandledRequests
}
//GetAllowUnhandledRequests returns true if the server accepts unhandled requests.
func (s *Server) GetAllowUnhandledRequests() bool {
s.rwMutex.RLock()
defer s.rwMutex.RUnlock()
return s.AllowUnhandledRequests
}
//SetUnhandledRequestStatusCode status code to be returned when the server receives unhandled requests
func (s *Server) SetUnhandledRequestStatusCode(statusCode int) {
s.rwMutex.Lock()
defer s.rwMutex.Unlock()
s.UnhandledRequestStatusCode = statusCode
}
//GetUnhandledRequestStatusCode returns the current status code being returned for unhandled requests
func (s *Server) GetUnhandledRequestStatusCode() int {
s.rwMutex.RLock()
defer s.rwMutex.RUnlock()
return s.UnhandledRequestStatusCode
}
golang-gomega-1.27.10/ghttp/test_server_suite_test.go 0000664 0000000 0000000 00000000277 14462163431 0022672 0 ustar 00root root 0000000 0000000 package ghttp_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"testing"
)
func TestGHTTP(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "GHTTP Suite")
}
golang-gomega-1.27.10/ghttp/test_server_test.go 0000664 0000000 0000000 00000102325 14462163431 0021456 0 ustar 00root root 0000000 0000000 package ghttp_test
import (
"bytes"
"io"
"net/http"
"net/url"
"regexp"
"github.com/golang/protobuf/proto"
"github.com/onsi/gomega/gbytes"
"github.com/onsi/gomega/ghttp/protobuf"
"github.com/onsi/gomega/internal/gutil"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/ghttp"
)
var _ = Describe("TestServer", func() {
var (
resp *http.Response
err error
s *Server
)
BeforeEach(func() {
s = NewServer()
})
AfterEach(func() {
s.Close()
})
Describe("Resetting the server", func() {
BeforeEach(func() {
s.RouteToHandler("GET", "/", func(w http.ResponseWriter, req *http.Request) {})
s.AppendHandlers(func(w http.ResponseWriter, req *http.Request) {})
http.Get(s.URL() + "/")
Expect(s.ReceivedRequests()).Should(HaveLen(1))
})
It("clears all handlers and call counts", func() {
s.Reset()
Expect(s.ReceivedRequests()).Should(HaveLen(0))
Expect(func() { s.GetHandler(0) }).Should(Panic())
})
})
Describe("closing client connections", func() {
It("closes", func() {
s.RouteToHandler("GET", "/",
func(w http.ResponseWriter, req *http.Request) {
io.WriteString(w, req.RemoteAddr)
},
)
client := http.Client{Transport: &http.Transport{DisableKeepAlives: true}}
resp, err := client.Get(s.URL())
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(200))
body, err := gutil.ReadAll(resp.Body)
resp.Body.Close()
Expect(err).ShouldNot(HaveOccurred())
s.CloseClientConnections()
resp, err = client.Get(s.URL())
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(200))
body2, err := gutil.ReadAll(resp.Body)
resp.Body.Close()
Expect(err).ShouldNot(HaveOccurred())
Expect(body2).ShouldNot(Equal(body))
})
})
Describe("closing server mulitple times", func() {
It("should not fail", func() {
s.Close()
Expect(s.Close).ShouldNot(Panic())
})
})
Describe("allowing unhandled requests", func() {
It("is not permitted by default", func() {
Expect(s.GetAllowUnhandledRequests()).To(BeFalse())
})
When("true", func() {
BeforeEach(func() {
s.SetAllowUnhandledRequests(true)
s.SetUnhandledRequestStatusCode(http.StatusForbidden)
resp, err = http.Get(s.URL() + "/foo")
Expect(err).ShouldNot(HaveOccurred())
})
It("should allow unhandled requests and respond with the passed in status code", func() {
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusForbidden))
data, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(data).Should(BeEmpty())
})
It("should record the requests", func() {
Expect(s.ReceivedRequests()).Should(HaveLen(1))
Expect(s.ReceivedRequests()[0].URL.Path).Should(Equal("/foo"))
})
})
When("false", func() {
It("should fail when attempting a request", func() {
failures := InterceptGomegaFailures(func() {
http.Get(s.URL() + "/foo")
})
Expect(failures[0]).Should(ContainSubstring("Received Unhandled Request"))
})
})
})
Describe("Managing Handlers", func() {
var called []string
BeforeEach(func() {
called = []string{}
s.RouteToHandler("GET", "/routed", func(w http.ResponseWriter, req *http.Request) {
called = append(called, "r1")
})
s.RouteToHandler("POST", regexp.MustCompile(`/routed\d`), func(w http.ResponseWriter, req *http.Request) {
called = append(called, "r2")
})
s.AppendHandlers(func(w http.ResponseWriter, req *http.Request) {
called = append(called, "A")
}, func(w http.ResponseWriter, req *http.Request) {
called = append(called, "B")
})
})
It("should prefer routed handlers if there is a match", func() {
http.Get(s.URL() + "/routed")
http.Post(s.URL()+"/routed7", "application/json", nil)
http.Get(s.URL() + "/foo")
http.Get(s.URL() + "/routed")
http.Post(s.URL()+"/routed9", "application/json", nil)
http.Get(s.URL() + "/bar")
failures := InterceptGomegaFailures(func() {
http.Get(s.URL() + "/foo")
http.Get(s.URL() + "/routed/not/a/match")
http.Get(s.URL() + "/routed7")
http.Post(s.URL()+"/routed", "application/json", nil)
})
Expect(failures[0]).Should(ContainSubstring("Received Unhandled Request"))
Expect(failures).Should(HaveLen(4))
http.Post(s.URL()+"/routed3", "application/json", nil)
Expect(called).Should(Equal([]string{"r1", "r2", "A", "r1", "r2", "B", "r2"}))
})
It("should override routed handlers when reregistered", func() {
s.RouteToHandler("GET", "/routed", func(w http.ResponseWriter, req *http.Request) {
called = append(called, "r3")
})
s.RouteToHandler("POST", regexp.MustCompile(`/routed\d`), func(w http.ResponseWriter, req *http.Request) {
called = append(called, "r4")
})
http.Get(s.URL() + "/routed")
http.Post(s.URL()+"/routed7", "application/json", nil)
Expect(called).Should(Equal([]string{"r3", "r4"}))
})
It("should call the appended handlers, in order, as requests come in", func() {
http.Get(s.URL() + "/foo")
Expect(called).Should(Equal([]string{"A"}))
http.Get(s.URL() + "/foo")
Expect(called).Should(Equal([]string{"A", "B"}))
failures := InterceptGomegaFailures(func() {
http.Get(s.URL() + "/foo")
})
Expect(failures[0]).Should(ContainSubstring("Received Unhandled Request"))
})
Describe("Overwriting an existing handler", func() {
BeforeEach(func() {
s.SetHandler(0, func(w http.ResponseWriter, req *http.Request) {
called = append(called, "C")
})
})
It("should override the specified handler", func() {
http.Get(s.URL() + "/foo")
http.Get(s.URL() + "/foo")
Expect(called).Should(Equal([]string{"C", "B"}))
})
})
Describe("Getting an existing handler", func() {
It("should return the handler func", func() {
s.GetHandler(1)(nil, nil)
Expect(called).Should(Equal([]string{"B"}))
})
})
Describe("Wrapping an existing handler", func() {
BeforeEach(func() {
s.WrapHandler(0, func(w http.ResponseWriter, req *http.Request) {
called = append(called, "C")
})
})
It("should wrap the existing handler in a new handler", func() {
http.Get(s.URL() + "/foo")
http.Get(s.URL() + "/foo")
Expect(called).Should(Equal([]string{"A", "C", "B"}))
})
})
})
Describe("When a handler fails", func() {
BeforeEach(func() {
s.SetUnhandledRequestStatusCode(http.StatusForbidden) //just to be clear that 500s aren't coming from unhandled requests
})
Context("because the handler has panicked", func() {
BeforeEach(func() {
s.AppendHandlers(func(w http.ResponseWriter, req *http.Request) {
panic("bam")
})
})
It("should respond with a 500 and make a failing assertion", func() {
var resp *http.Response
var err error
failures := InterceptGomegaFailures(func() {
resp, err = http.Get(s.URL())
})
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusInternalServerError))
Expect(failures).Should(ConsistOf(ContainSubstring("Handler Panicked")))
})
})
Context("because an assertion has failed", func() {
BeforeEach(func() {
s.AppendHandlers(func(w http.ResponseWriter, req *http.Request) {
// Expect(true).Should(BeFalse()) <-- would be nice to do it this way, but the test just can't be written this way
By("We're cheating a bit here -- we're pretending to throw a Ginkgo panic which simulates a failed assertion")
panic("defer GinkgoRecover()")
})
})
It("should respond with a 500 and *not* make a failing assertion, instead relying on Ginkgo to have already been notified of the error", func() {
resp, err := http.Get(s.URL())
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusInternalServerError))
})
})
})
Describe("Logging to the Writer", func() {
var buf *gbytes.Buffer
BeforeEach(func() {
buf = gbytes.NewBuffer()
s.Writer = buf
s.AppendHandlers(func(w http.ResponseWriter, req *http.Request) {})
s.AppendHandlers(func(w http.ResponseWriter, req *http.Request) {})
})
It("should write to the buffer when a request comes in", func() {
http.Get(s.URL() + "/foo")
Expect(buf).Should(gbytes.Say("GHTTP Received Request: GET - /foo\n"))
http.Post(s.URL()+"/bar", "", nil)
Expect(buf).Should(gbytes.Say("GHTTP Received Request: POST - /bar\n"))
})
})
Describe("Request Handlers", func() {
Describe("VerifyRequest", func() {
BeforeEach(func() {
s.AppendHandlers(VerifyRequest("GET", "/foo"))
})
It("should verify the method, path", func() {
resp, err = http.Get(s.URL() + "/foo?baz=bar")
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the method, path", func() {
failures := InterceptGomegaFailures(func() {
http.Get(s.URL() + "/foo2")
})
Expect(failures).Should(HaveLen(1))
})
It("should verify the method, path", func() {
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/foo", "application/json", nil)
})
Expect(failures).Should(HaveLen(1))
})
When("passed a rawQuery", func() {
It("should also be possible to verify the rawQuery", func() {
s.SetHandler(0, VerifyRequest("GET", "/foo", "baz=bar"))
resp, err = http.Get(s.URL() + "/foo?baz=bar")
Expect(err).ShouldNot(HaveOccurred())
})
It("should match irregardless of query parameter ordering", func() {
s.SetHandler(0, VerifyRequest("GET", "/foo", "type=get&name=money"))
u, _ := url.Parse(s.URL() + "/foo")
u.RawQuery = url.Values{
"type": []string{"get"},
"name": []string{"money"},
}.Encode()
resp, err = http.Get(u.String())
Expect(err).ShouldNot(HaveOccurred())
})
})
When("passed a matcher for path", func() {
It("should apply the matcher", func() {
s.SetHandler(0, VerifyRequest("GET", MatchRegexp(`/foo/[a-f]*/3`)))
resp, err = http.Get(s.URL() + "/foo/abcdefa/3")
Expect(err).ShouldNot(HaveOccurred())
})
})
})
Describe("VerifyContentType", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("GET", "/foo"),
VerifyContentType("application/octet-stream"),
))
})
It("should verify the content type", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Set("Content-Type", "application/octet-stream")
resp, err = http.DefaultClient.Do(req)
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the content type", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Set("Content-Type", "application/json")
failures := InterceptGomegaFailures(func() {
http.DefaultClient.Do(req)
})
Expect(failures).Should(HaveLen(1))
})
It("should verify the content type", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Set("Content-Type", "application/octet-stream; charset=utf-8")
failures := InterceptGomegaFailures(func() {
http.DefaultClient.Do(req)
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("Verify BasicAuth", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("GET", "/foo"),
VerifyBasicAuth("bob", "password"),
))
})
It("should verify basic auth", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.SetBasicAuth("bob", "password")
resp, err = http.DefaultClient.Do(req)
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify basic auth", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.SetBasicAuth("bob", "bassword")
failures := InterceptGomegaFailures(func() {
http.DefaultClient.Do(req)
})
Expect(failures).Should(HaveLen(1))
})
It("should require basic auth header", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
failures := InterceptGomegaFailures(func() {
http.DefaultClient.Do(req)
})
Expect(failures).Should(ContainElement(ContainSubstring("Authorization header must be specified")))
})
})
Describe("VerifyHeader", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("GET", "/foo"),
VerifyHeader(http.Header{
"accept": []string{"jpeg", "png"},
"cache-control": []string{"omicron"},
"Return-Path": []string{"hobbiton"},
}),
))
})
It("should verify the headers", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Add("Accept", "jpeg")
req.Header.Add("Accept", "png")
req.Header.Add("Cache-Control", "omicron")
req.Header.Add("return-path", "hobbiton")
resp, err = http.DefaultClient.Do(req)
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the headers", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Add("Schmaccept", "jpeg")
req.Header.Add("Schmaccept", "png")
req.Header.Add("Cache-Control", "omicron")
req.Header.Add("return-path", "hobbiton")
failures := InterceptGomegaFailures(func() {
http.DefaultClient.Do(req)
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("VerifyHeaderKV", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("GET", "/foo"),
VerifyHeaderKV("accept", "jpeg", "png"),
VerifyHeaderKV("cache-control", "omicron"),
VerifyHeaderKV("Return-Path", "hobbiton"),
))
})
It("should verify the headers", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Add("Accept", "jpeg")
req.Header.Add("Accept", "png")
req.Header.Add("Cache-Control", "omicron")
req.Header.Add("return-path", "hobbiton")
resp, err = http.DefaultClient.Do(req)
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the headers", func() {
req, err := http.NewRequest("GET", s.URL()+"/foo", nil)
Expect(err).ShouldNot(HaveOccurred())
req.Header.Add("Accept", "jpeg")
req.Header.Add("Cache-Control", "omicron")
req.Header.Add("return-path", "hobbiton")
failures := InterceptGomegaFailures(func() {
http.DefaultClient.Do(req)
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("VerifyBody", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
VerifyBody([]byte("some body")),
))
})
It("should verify the body", func() {
resp, err = http.Post(s.URL()+"/foo", "", bytes.NewReader([]byte("some body")))
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the body", func() {
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/foo", "", bytes.NewReader([]byte("wrong body")))
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("VerifyMimeType", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyMimeType("application/json"),
))
})
It("should verify the mime type in content-type header", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json; charset=utf-8", bytes.NewReader([]byte(`{}`)))
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the mime type in content-type header", func() {
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/foo", "text/plain", bytes.NewReader([]byte(`{}`)))
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("VerifyJSON", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
VerifyJSON(`{"a":3, "b":2}`),
))
})
It("should verify the json body and the content type", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", bytes.NewReader([]byte(`{"b":2, "a":3}`)))
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the json body and the content type", func() {
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/foo", "application/json", bytes.NewReader([]byte(`{"b":2, "a":4}`)))
})
Expect(failures).Should(HaveLen(1))
})
It("should verify the json body and the content type", func() {
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/foo", "application/not-json", bytes.NewReader([]byte(`{"b":2, "a":3}`)))
})
Expect(failures).Should(HaveLen(1))
})
It("should verify the json body and the content type", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json; charset=utf-8", bytes.NewReader([]byte(`{"b":2, "a":3}`)))
Expect(err).ShouldNot(HaveOccurred())
})
})
Describe("VerifyJSONRepresenting", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
VerifyJSONRepresenting([]int{1, 3, 5}),
))
})
It("should verify the json body and the content type", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", bytes.NewReader([]byte(`[1,3,5]`)))
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the json body and the content type", func() {
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/foo", "application/json; charset=utf-8", bytes.NewReader([]byte(`[1,3]`)))
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("VerifyForm", func() {
var formValues url.Values
BeforeEach(func() {
formValues = make(url.Values)
formValues.Add("users", "user1")
formValues.Add("users", "user2")
formValues.Add("group", "users")
})
When("encoded in the URL", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("GET", "/foo"),
VerifyForm(url.Values{
"users": []string{"user1", "user2"},
"group": []string{"users"},
}),
))
})
It("should verify form values", func() {
resp, err = http.Get(s.URL() + "/foo?" + formValues.Encode())
Expect(err).ShouldNot(HaveOccurred())
})
It("should ignore extra values", func() {
formValues.Add("extra", "value")
resp, err = http.Get(s.URL() + "/foo?" + formValues.Encode())
Expect(err).ShouldNot(HaveOccurred())
})
It("fail on missing values", func() {
formValues.Del("group")
failures := InterceptGomegaFailures(func() {
resp, err = http.Get(s.URL() + "/foo?" + formValues.Encode())
})
Expect(failures).Should(HaveLen(1))
})
It("fail on incorrect values", func() {
formValues.Set("group", "wheel")
failures := InterceptGomegaFailures(func() {
resp, err = http.Get(s.URL() + "/foo?" + formValues.Encode())
})
Expect(failures).Should(HaveLen(1))
})
})
When("present in the body", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
VerifyForm(url.Values{
"users": []string{"user1", "user2"},
"group": []string{"users"},
}),
))
})
It("should verify form values", func() {
resp, err = http.PostForm(s.URL()+"/foo", formValues)
Expect(err).ShouldNot(HaveOccurred())
})
It("should ignore extra values", func() {
formValues.Add("extra", "value")
resp, err = http.PostForm(s.URL()+"/foo", formValues)
Expect(err).ShouldNot(HaveOccurred())
})
It("fail on missing values", func() {
formValues.Del("group")
failures := InterceptGomegaFailures(func() {
resp, err = http.PostForm(s.URL()+"/foo", formValues)
})
Expect(failures).Should(HaveLen(1))
})
It("fail on incorrect values", func() {
formValues.Set("group", "wheel")
failures := InterceptGomegaFailures(func() {
resp, err = http.PostForm(s.URL()+"/foo", formValues)
})
Expect(failures).Should(HaveLen(1))
})
})
})
Describe("VerifyFormKV", func() {
When("encoded in the URL", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("GET", "/foo"),
VerifyFormKV("users", "user1", "user2"),
))
})
It("verifies the form value", func() {
resp, err = http.Get(s.URL() + "/foo?users=user1&users=user2")
Expect(err).ShouldNot(HaveOccurred())
})
It("verifies the form value", func() {
failures := InterceptGomegaFailures(func() {
resp, err = http.Get(s.URL() + "/foo?users=user1")
})
Expect(failures).Should(HaveLen(1))
})
})
When("present in the body", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
VerifyFormKV("users", "user1", "user2"),
))
})
It("verifies the form value", func() {
resp, err = http.PostForm(s.URL()+"/foo", url.Values{"users": []string{"user1", "user2"}})
Expect(err).ShouldNot(HaveOccurred())
})
It("verifies the form value", func() {
failures := InterceptGomegaFailures(func() {
resp, err = http.PostForm(s.URL()+"/foo", url.Values{"users": []string{"user1"}})
})
Expect(failures).Should(HaveLen(1))
})
})
})
Describe("VerifyProtoRepresenting", func() {
var message *protobuf.SimpleMessage
BeforeEach(func() {
message = new(protobuf.SimpleMessage)
message.Description = proto.String("A description")
message.Id = proto.Int32(0)
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/proto"),
VerifyProtoRepresenting(message),
))
})
It("verifies the proto body and the content type", func() {
serialized, err := proto.Marshal(message)
Expect(err).ShouldNot(HaveOccurred())
resp, err = http.Post(s.URL()+"/proto", "application/x-protobuf", bytes.NewReader(serialized))
Expect(err).ShouldNot(HaveOccurred())
})
It("should verify the proto body and the content type", func() {
serialized, err := proto.Marshal(&protobuf.SimpleMessage{
Description: proto.String("A description"),
Id: proto.Int32(0),
Metadata: proto.String("some metadata"),
})
Expect(err).ShouldNot(HaveOccurred())
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/proto", "application/x-protobuf", bytes.NewReader(serialized))
})
Expect(failures).Should(HaveLen(1))
})
It("should verify the proto body and the content type", func() {
serialized, err := proto.Marshal(message)
Expect(err).ShouldNot(HaveOccurred())
failures := InterceptGomegaFailures(func() {
http.Post(s.URL()+"/proto", "application/not-x-protobuf", bytes.NewReader(serialized))
})
Expect(failures).Should(HaveLen(1))
})
})
Describe("RespondWith", func() {
Context("without headers", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWith(http.StatusCreated, "sweet"),
), CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWith(http.StatusOK, []byte("sour")),
))
})
It("should return the response", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
body, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(Equal([]byte("sweet")))
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusOK))
body, err = gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(Equal([]byte("sour")))
})
})
Context("with headers", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWith(http.StatusCreated, "sweet", http.Header{"X-Custom-Header": []string{"my header"}}),
))
})
It("should return the headers too", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
Expect(gutil.ReadAll(resp.Body)).Should(Equal([]byte("sweet")))
Expect(resp.Header.Get("X-Custom-Header")).Should(Equal("my header"))
})
})
})
Describe("RespondWithPtr", func() {
var code int
var byteBody []byte
var stringBody string
BeforeEach(func() {
code = http.StatusOK
byteBody = []byte("sweet")
stringBody = "sour"
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithPtr(&code, &byteBody),
), CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithPtr(&code, &stringBody),
))
})
It("should return the response", func() {
code = http.StatusCreated
byteBody = []byte("tasty")
stringBody = "treat"
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
body, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(Equal([]byte("tasty")))
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
body, err = gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(Equal([]byte("treat")))
})
When("passed a nil body", func() {
BeforeEach(func() {
s.SetHandler(0, CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithPtr(&code, nil),
))
})
It("should return an empty body and not explode", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusOK))
body, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(BeEmpty())
Expect(s.ReceivedRequests()).Should(HaveLen(1))
})
})
})
Describe("RespondWithJSON", func() {
When("no optional headers are set", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithJSONEncoded(http.StatusCreated, []int{1, 2, 3}),
))
})
It("should return the response", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
body, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(MatchJSON("[1,2,3]"))
})
It("should set the Content-Type header to application/json", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"application/json"}))
})
})
When("optional headers are set", func() {
var headers http.Header
BeforeEach(func() {
headers = http.Header{"Stuff": []string{"things"}}
})
JustBeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithJSONEncoded(http.StatusCreated, []int{1, 2, 3}, headers),
))
})
It("should preserve those headers", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Stuff"]).Should(Equal([]string{"things"}))
})
It("should set the Content-Type header to application/json", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"application/json"}))
})
When("setting the Content-Type explicitly", func() {
BeforeEach(func() {
headers["Content-Type"] = []string{"not-json"}
})
It("should use the Content-Type header that was explicitly set", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"not-json"}))
})
})
})
})
Describe("RespondWithJSONPtr", func() {
type testObject struct {
Key string
Value string
}
var code int
var object testObject
When("no optional headers are set", func() {
BeforeEach(func() {
code = http.StatusOK
object = testObject{}
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithJSONEncodedPtr(&code, &object),
))
})
It("should return the response", func() {
code = http.StatusCreated
object = testObject{
Key: "Jim",
Value: "Codes",
}
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
body, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
Expect(body).Should(MatchJSON(`{"Key": "Jim", "Value": "Codes"}`))
})
It("should set the Content-Type header to application/json", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"application/json"}))
})
})
When("optional headers are set", func() {
var headers http.Header
BeforeEach(func() {
headers = http.Header{"Stuff": []string{"things"}}
})
JustBeforeEach(func() {
code = http.StatusOK
object = testObject{}
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/foo"),
RespondWithJSONEncodedPtr(&code, &object, headers),
))
})
It("should preserve those headers", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Stuff"]).Should(Equal([]string{"things"}))
})
It("should set the Content-Type header to application/json", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"application/json"}))
})
When("setting the Content-Type explicitly", func() {
BeforeEach(func() {
headers["Content-Type"] = []string{"not-json"}
})
It("should use the Content-Type header that was explicitly set", func() {
resp, err = http.Post(s.URL()+"/foo", "application/json", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"not-json"}))
})
})
})
})
Describe("RespondWithProto", func() {
var message *protobuf.SimpleMessage
BeforeEach(func() {
message = new(protobuf.SimpleMessage)
message.Description = proto.String("A description")
message.Id = proto.Int32(99)
})
When("no optional headers are set", func() {
BeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/proto"),
RespondWithProto(http.StatusCreated, message),
))
})
It("should return the response", func() {
resp, err = http.Post(s.URL()+"/proto", "application/x-protobuf", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.StatusCode).Should(Equal(http.StatusCreated))
var received protobuf.SimpleMessage
body, err := gutil.ReadAll(resp.Body)
Expect(err).ShouldNot(HaveOccurred())
err = proto.Unmarshal(body, &received)
Expect(err).ShouldNot(HaveOccurred())
})
It("should set the Content-Type header to application/x-protobuf", func() {
resp, err = http.Post(s.URL()+"/proto", "application/x-protobuf", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"application/x-protobuf"}))
})
})
When("optional headers are set", func() {
var headers http.Header
BeforeEach(func() {
headers = http.Header{"Stuff": []string{"things"}}
})
JustBeforeEach(func() {
s.AppendHandlers(CombineHandlers(
VerifyRequest("POST", "/proto"),
RespondWithProto(http.StatusCreated, message, headers),
))
})
It("should preserve those headers", func() {
resp, err = http.Post(s.URL()+"/proto", "application/x-protobuf", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Stuff"]).Should(Equal([]string{"things"}))
})
It("should set the Content-Type header to application/x-protobuf", func() {
resp, err = http.Post(s.URL()+"/proto", "application/x-protobuf", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"application/x-protobuf"}))
})
When("setting the Content-Type explicitly", func() {
BeforeEach(func() {
headers["Content-Type"] = []string{"not-x-protobuf"}
})
It("should use the Content-Type header that was explicitly set", func() {
resp, err = http.Post(s.URL()+"/proto", "application/x-protobuf", nil)
Expect(err).ShouldNot(HaveOccurred())
Expect(resp.Header["Content-Type"]).Should(Equal([]string{"not-x-protobuf"}))
})
})
})
})
})
})
golang-gomega-1.27.10/gleak/ 0000775 0000000 0000000 00000000000 14462163431 0015455 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gleak/doc.go 0000664 0000000 0000000 00000011571 14462163431 0016556 0 ustar 00root root 0000000 0000000 /*
package gleak complements the Gingko/Gomega testing and matchers framework with
matchers for Goroutine leakage detection.
Basics of nleak
To start with,
Goroutines()
returns information about all (non-dead) goroutines at a particular moment. This
is useful to capture a known correct snapshot and then later taking a new
snapshot and comparing these two snapshots for leaked goroutines.
Next, the matcher
HaveLeaked(...)
filters out well-known and expected "non-leaky" goroutines from an actual list
of goroutines (passed from Eventually or Expect), hopefully ending up with an
empty list of leaked goroutines. If there are still goroutines left after
filtering, then HaveLeaked() will succeed ... which usually is actually
considered to be failure. So, this can be rather declared to be "suckcess"
because no one wants leaked goroutines.
A typical pattern to detect goroutines leaked in individual tests is as follows:
var ignoreGood []Goroutine
BeforeEach(func() {
ignoreGood = Goroutines()
})
AfterEach(func() {
// Note: it's "Goroutines", but not "Goroutines()", when using with Eventually!
Eventually(Goroutines).ShouldNot(HaveLeaked(ignoreGood))
})
Using Eventually instead of Expect ensures that there is some time given for
temporary goroutines to finally wind down. Gomega's default values apply: the 1s
timeout and 10ms polling interval.
Please note that the form
HaveLeaked(ignoreGood)
is the same as the slightly longer, but also more expressive variant:
HaveLeaked(IgnoringGoroutines(ignoreGood))
Leak-Related Matchers
Depending on your tests and the dependencies used, you might need to identify
additional goroutines as not being leaks. The gleak packages comes with the
following predefined goroutine "filter" matchers that can be specified as
arguments to HaveLeaked(...):
IgnoringTopFunction("foo.bar") // exactly "foo.bar"
IgnoringTopFunction("foo.bar...") // top function name with prefix "foo.bar." (note the trailing dot!)
IgnoringTopFunction("foo.bar [chan receive]") // exactly "foo.bar" with state starting with "chan receive"
IgnoringGoroutines(expectedGoroutines) // ignore specified goroutines with these IDs
IgnoringInBacktrace("foo.bar.baz") // "foo.bar.baz" within the backtrace
IgnoringCreator("foo.bar") // exact creator function name "foo.bar"
IgnoringCreator("foo.bar...") // creator function name with prefix "foo.bar."
In addition, you can use any other GomegaMatcher, as long as it can work on a
(single) Goroutine. For instance, Gomega's HaveField and WithTransform
matchers are good foundations for writing project-specific gleak matchers.
Leaked Goroutine Dump
By default, when gleak's HaveLeaked matcher finds one or more leaked
goroutines, it dumps the goroutine backtraces in a condensed format that uses
only a single line per call instead of two lines. Moreover, the backtraces
abbreviate the source file location in the form of package/source.go:lineno:
goroutine 42 [flabbergasted]
main.foo.func1() at foo/test.go:6
created by main.foo at foo/test.go:5
By setting gleak.ReportFilenameWithPath=true the leaky goroutine backtraces
will show full path names for each source file:
goroutine 42 [flabbergasted]
main.foo.func1() at /home/go/foo/test.go:6
created by main.foo at home/go/foo/test.go:5
Acknowledgement
gleak has been heavily inspired by the Goroutine leak detector
github.com/uber-go/goleak. That's definitely a fine piece of work!
But then why another goroutine leak package? After a deep analysis of Uber's
goleak we decided against crunching goleak somehow half-assed into the Gomega
TDD matcher ecosystem. In particular, reusing and wrapping of the existing Uber
implementation would have become very awkward: goleak.Find combines all the
different elements of getting actual goroutines information, filtering them,
arriving at a leak conclusion, and even retrying multiple times all in just one
single exported function. Unfortunately, goleak makes gathering information
about all goroutines an internal matter, so we cannot reuse such functionality
elsewhere.
Users of the Gomega ecosystem are already experienced in arriving at conclusions
and retrying temporarily failing expectations: Gomega does it in form of
Eventually().ShouldNot(), and (without the trying aspect) with Expect().NotTo().
So what is missing is only a goroutine leak detector in form of the HaveLeaked
matcher, as well as the ability to specify goroutine filters in order to sort
out the non-leaking (and therefore expected) goroutines, using a few filter
criteria. That is, a few new goroutine-related matchers. In this architecture,
even existing Gomega matchers can optionally be (re)used as the need arises.
References
https://github.com/onsi/gomega and https://github.com/onsi/ginkgo.
*/
package gleak
golang-gomega-1.27.10/gleak/ginkgo_parallel_client.go 0000664 0000000 0000000 00000001476 14462163431 0022504 0 ustar 00root root 0000000 0000000 package gleak
import "os"
// IgnoreGinkgoParallelClient must be called in a BeforeSuite whenever a test
// suite is run in parallel with other test suites using "ginkgo -p". Calling
// IgnoreGinkgoParallelClient checks for a Ginkgo-related background go routine
// and then updates gleak's internal ignore list to specifically ignore this
// background go routine by its ("random") ID.
func IgnoreGinkgoParallelClient() {
ignoreCreator := "net/rpc.NewClientWithCodec"
if os.Getenv("GINKGO_PARALLEL_PROTOCOL") == "HTTP" {
ignoreCreator = "net/http.(*Transport).dialConn"
}
ignores := []Goroutine{}
for _, g := range Goroutines() {
if g.CreatorFunction == ignoreCreator {
ignores = append(ignores, g)
}
}
if len(ignores) == 0 {
return
}
standardFilters = append(standardFilters, IgnoringGoroutines(ignores))
}
golang-gomega-1.27.10/gleak/gleak_suite_test.go 0000664 0000000 0000000 00000000735 14462163431 0021344 0 ustar 00root root 0000000 0000000 package gleak
import (
"testing"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
// In case this suite is run in parallel with other test suites using "ginkgo
// -p", then there is a Ginkgo-related background go routine that we need to
// ignore in all tests and that can be identified only by its random ID.
var _ = BeforeSuite(func() {
IgnoreGinkgoParallelClient()
})
func TestGleak(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Gleak Suite")
}
golang-gomega-1.27.10/gleak/goroutine/ 0000775 0000000 0000000 00000000000 14462163431 0017470 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gleak/goroutine/doc.go 0000664 0000000 0000000 00000000724 14462163431 0020567 0 ustar 00root root 0000000 0000000 /*
Package goroutine discovers and returns information about either all goroutines
or only the caller's goroutine. Information provided by the Goroutine type
consists of a unique ID, the state, the name of the topmost (most recent)
function in the call stack and the full backtrace. For goroutines other than the
main goroutine (the one with ID 1) the creating function as well as location
(file name and line number) are additionally provided.
*/
package goroutine
golang-gomega-1.27.10/gleak/goroutine/goroutine.go 0000664 0000000 0000000 00000021035 14462163431 0022033 0 ustar 00root root 0000000 0000000 package goroutine
import (
"bufio"
"bytes"
"fmt"
"io"
"strconv"
"strings"
)
// Goroutine represents information about a single goroutine, such as its unique
// ID, state, backtrace, creator, and more.
//
// Go's runtime assigns unique IDs to goroutines, also called "goid" in Go
// runtime parlance. These IDs start with 1 for the main goroutine and only
// increase (unless you manage to create 2**64-2 goroutines during the lifetime
// of your tests so that the goids wrap around). Due to runtime-internal
// optimizations, not all IDs might be used, so that there might be gaps. But
// IDs are never reused, so they're fine as unique goroutine identities.
//
// The size of a goidsis always 64bits, even on 32bit architectures (if you
// like, you might want to double-check for yourself in runtime/runtime2.go and
// runtime/proc.go).
//
// A Goroutine's State field starts with one of the following strings:
// - "idle"
// - "runnable"
// - "running"
// - "syscall"
// - ("waiting" ... see below)
// - ("dead" ... these goroutines should never appear in dumps)
// - "copystack"
// - "preempted"
// - ("???" ... something IS severely broken.)
//
// In case a goroutine is in waiting state, the State field instead starts with
// one of the following strings, never showing a lonely "waiting" string, but
// rather one of the reasons for waiting:
// - "chan receive"
// - "chan send"
// - "select"
// - "sleep"
// - "finalizer wait"
// - ...quite some more waiting states.
//
// The State description may next contain "(scan)", separated by a single blank
// from the preceding goroutine state text.
//
// If a goroutine is blocked from more than at least a minute, then the state
// description next contains the string "X minutes", where X is the number of
// minutes blocked. This text is separated by a "," and a blank from the
// preceding information.
//
// Finally, OS thread-locked goroutines finally contain "locked to thread" in
// their State description, again separated by a "," and a blank from the
// preceding information.
//
// Please note that the State field never contains the opening and closing
// square brackets as used in plain stack dumps.
type Goroutine struct {
ID uint64 // unique goroutine ID ("goid" in Go's runtime parlance)
State string // goroutine state, such as "running"
TopFunction string // topmost function on goroutine's stack
CreatorFunction string // name of function creating this goroutine, if any
BornAt string // location where the goroutine was started from, if any; format "file-path:line-number"
Backtrace string // goroutine's backtrace (of the stack)
}
// String returns a short textual description of this goroutine, but without the
// potentially lengthy and ugly backtrace details.
func (g Goroutine) String() string {
s := fmt.Sprintf("Goroutine ID: %d, state: %s, top function: %s",
g.ID, g.State, g.TopFunction)
if g.CreatorFunction == "" {
return s
}
s += fmt.Sprintf(", created by: %s, at: %s",
g.CreatorFunction, g.BornAt)
return s
}
// GomegaString returns the Gomega struct representation of a Goroutine, but
// without a potentially rather lengthy backtrace. This Gomega object value
// dumps getting happily truncated as to become more or less useless.
func (g Goroutine) GomegaString() string {
return fmt.Sprintf(
"{ID: %d, State: %q, TopFunction: %q, CreatorFunction: %q, BornAt: %q}",
g.ID, g.State, g.TopFunction, g.CreatorFunction, g.BornAt)
}
// Goroutines returns information about all goroutines.
func Goroutines() []Goroutine {
return goroutines(true)
}
// Current returns information about the current goroutine in which it is
// called. Please note that the topmost function name will always be
// runtime.Stack.
func Current() Goroutine {
return goroutines(false)[0]
}
// goroutines is an internal wrapper around dumping either only the stack of the
// current goroutine of the caller or dumping the stacks of all goroutines, and
// then parsing the dump into separate Goroutine descriptions.
func goroutines(all bool) []Goroutine {
return parseStack(stacks(all))
}
// parseStack parses the stack dump of one or multiple goroutines, as returned
// by runtime.Stack() and then returns a list of Goroutine descriptions based on
// the dump.
func parseStack(stacks []byte) []Goroutine {
gs := []Goroutine{}
r := bufio.NewReader(bytes.NewReader(stacks))
for {
// We expect a line describing a new "goroutine", everything else is a
// failure. And yes, if we get an EOF already with this line, bail out.
line, err := r.ReadString('\n')
if err == io.EOF {
break
}
g := new(line)
// Read the rest ... that is, the backtrace for this goroutine.
g.TopFunction, g.Backtrace = parseGoroutineBacktrace(r)
if strings.HasSuffix(g.Backtrace, "\n\n") {
g.Backtrace = g.Backtrace[:len(g.Backtrace)-1]
}
g.CreatorFunction, g.BornAt = findCreator(g.Backtrace)
gs = append(gs, g)
}
return gs
}
// new takes a goroutine line from a stack dump and returns a Goroutine object
// based on the information contained in the dump.
func new(s string) Goroutine {
s = strings.TrimSuffix(s, ":\n")
fields := strings.SplitN(s, " ", 3)
if len(fields) != 3 {
panic(fmt.Sprintf("invalid stack header: %q", s))
}
id, err := strconv.ParseUint(fields[1], 10, 64)
if err != nil {
panic(fmt.Sprintf("invalid stack header ID: %q, header: %q", fields[1], s))
}
state := strings.TrimSuffix(strings.TrimPrefix(fields[2], "["), "]")
return Goroutine{ID: id, State: state}
}
// Beginning of line indicating the creator of a Goroutine, if any. This
// indication is missing for the main goroutine as it appeared in a big bang or
// something similar.
const backtraceGoroutineCreator = "created by "
// findCreator solves the great mystery of Gokind, answering the question of who
// created this goroutine? Given a backtrace, that is.
func findCreator(backtrace string) (creator, location string) {
pos := strings.LastIndex(backtrace, backtraceGoroutineCreator)
if pos < 0 {
return
}
// Split the "created by ..." line from the following line giving us the
// (indented) file name:line number and the hex offset of the call location
// within the function.
details := strings.SplitN(backtrace[pos+len(backtraceGoroutineCreator):], "\n", 3)
if len(details) < 2 {
return
}
// Split off the call location hex offset which is of no use to us, and only
// keep the file path and line number information. This will be useful for
// diagnosis, when dumping leaked goroutines.
offsetpos := strings.LastIndex(details[1], " +0x")
if offsetpos < 0 {
return
}
location = strings.TrimSpace(details[1][:offsetpos])
creator = details[0]
if offsetpos := strings.LastIndex(creator, " in goroutine "); offsetpos >= 0 {
creator = creator[:offsetpos]
}
return
}
// Beginning of header line introducing a (new) goroutine in a backtrace.
const backtraceGoroutineHeader = "goroutine "
// Length of the header line prefix introducing a (new) goroutine in a
// backtrace.
const backtraceGoroutineHeaderLen = len(backtraceGoroutineHeader)
// parseGoroutineBacktrace reads from reader r the backtrace information until
// the end or until the next goroutine header is seen. This next goroutine
// header is NOT consumed so that callers can still read the next header from
// the reader.
func parseGoroutineBacktrace(r *bufio.Reader) (topFn string, backtrace string) {
bt := bytes.Buffer{}
// Read backtrace information belonging to this goroutine until we meet
// another goroutine header.
for {
header, err := r.Peek(backtraceGoroutineHeaderLen)
if string(header) == backtraceGoroutineHeader {
// next goroutine header is up for read, so we're done with parsing
// the backtrace of this goroutine.
break
}
if err != nil && err != io.EOF {
// There is some serious problem with the stack dump, so we
// decidedly panic now.
panic("parsing backtrace failed: " + err.Error())
}
line, err := r.ReadString('\n')
if err != nil && err != io.EOF {
// There is some serious problem with the stack dump, so we
// decidedly panic now.
panic("parsing backtrace failed: " + err.Error())
}
// The first line after a goroutine header lists the "topmost" function.
if topFn == "" {
line := /*sic!*/ strings.TrimSpace(line)
idx := strings.LastIndex(line, "(")
if idx <= 0 {
panic(fmt.Sprintf("invalid function call stack entry: %q", line))
}
topFn = line[:idx]
}
// Always append the line read to the goroutine's backtrace.
bt.WriteString(line)
if err == io.EOF {
// we're reached the end of the stack dump, so that's it.
break
}
}
return topFn, bt.String()
}
golang-gomega-1.27.10/gleak/goroutine/goroutine_suite_test.go 0000664 0000000 0000000 00000000306 14462163431 0024301 0 ustar 00root root 0000000 0000000 package goroutine
import (
"testing"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
func TestGoroutine(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Goroutine Suite")
}
golang-gomega-1.27.10/gleak/goroutine/goroutine_test.go 0000664 0000000 0000000 00000015151 14462163431 0023074 0 ustar 00root root 0000000 0000000 package goroutine
import (
"bufio"
"errors"
"io"
"reflect"
"strings"
"sync"
"testing/iotest"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("goroutine", func() {
const stack = `runtime/debug.Stack()
/usr/local/go-faketime/src/runtime/debug/stack.go:24 +0x65
runtime/debug.PrintStack()
/usr/local/go-faketime/src/runtime/debug/stack.go:16 +0x19
main.main()
/tmp/sandbox3386995578/prog.go:10 +0x17
`
const header = `goroutine 666 [running]:
`
const nextStack = header + `main.hades()
/tmp/sandbox3386995578/prog.go:10 +0x17
`
It("prints", func() {
Expect(Goroutine{
ID: 1234,
State: "gone",
TopFunction: "gopher.hole",
}.String()).To(Equal(
"Goroutine ID: 1234, state: gone, top function: gopher.hole"))
Expect(Goroutine{
ID: 1234,
State: "gone",
TopFunction: "gopher.hole",
CreatorFunction: "google",
BornAt: "/plan/10:2009",
}.String()).To(Equal(
"Goroutine ID: 1234, state: gone, top function: gopher.hole, created by: google, at: /plan/10:2009"))
Expect(Goroutine{
ID: 1234,
State: "gone",
TopFunction: "gopher.hole",
CreatorFunction: "google",
BornAt: "/plan/10:2009",
}.GomegaString()).To(Equal(
"{ID: 1234, State: \"gone\", TopFunction: \"gopher.hole\", CreatorFunction: \"google\", BornAt: \"/plan/10:2009\"}"))
})
Context("goroutine header", func() {
It("parses goroutine header", func() {
g := new(header)
Expect(g.ID).To(Equal(uint64(666)))
Expect(g.State).To(Equal("running"))
})
It("panics on malformed goroutine header", func() {
Expect(func() { _ = new("a") }).To(PanicWith(MatchRegexp(`invalid stack header: .*`)))
Expect(func() { _ = new("a b") }).To(PanicWith(MatchRegexp(`invalid stack header: .*`)))
})
It("panics on malformed goroutine ID", func() {
Expect(func() { _ = new("a b c:\n") }).To(PanicWith(MatchRegexp(`invalid stack header ID: "b", header: ".*"`)))
})
})
Context("goroutine backtrace", func() {
It("parses goroutine's backtrace", func() {
r := bufio.NewReader(strings.NewReader(stack))
topF, backtrace := parseGoroutineBacktrace(r)
Expect(topF).To(Equal("runtime/debug.Stack"))
Expect(backtrace).To(Equal(stack))
r.Reset(strings.NewReader(stack[:len(stack)-1]))
topF, backtrace = parseGoroutineBacktrace(r)
Expect(topF).To(Equal("runtime/debug.Stack"))
Expect(backtrace).To(Equal(stack[:len(stack)-1]))
})
It("parses goroutine's backtrace until next goroutine header", func() {
r := bufio.NewReader(strings.NewReader(stack + nextStack))
topF, backtrace := parseGoroutineBacktrace(r)
Expect(topF).To(Equal("runtime/debug.Stack"))
Expect(backtrace).To(Equal(stack))
})
It("panics on invalid function call stack entry", func() {
r := bufio.NewReader(strings.NewReader(`main.main
/somewhere/prog.go:123 +0x666
`))
Expect(func() { parseGoroutineBacktrace(r) }).To(PanicWith(MatchRegexp(`invalid function call stack entry: "main.main"`)))
})
It("panics on failing reader", func() {
Expect(func() {
parseGoroutineBacktrace(bufio.NewReader(
iotest.ErrReader(errors.New("foo failure"))))
}).To(PanicWith("parsing backtrace failed: foo failure"))
Expect(func() {
parseGoroutineBacktrace(
bufio.NewReaderSize(
iotest.TimeoutReader(strings.NewReader(strings.Repeat("x", 32))),
16))
}).To(PanicWith("parsing backtrace failed: timeout"))
Expect(func() {
parseGoroutineBacktrace(bufio.NewReader(
iotest.ErrReader(io.ErrClosedPipe)))
}).To(PanicWith(MatchRegexp(`parsing backtrace failed: .*`)))
})
It("parses goroutine information and stack", func() {
gs := parseStack([]byte(header + stack))
Expect(gs).To(HaveLen(1))
Expect(gs[0]).To(And(
HaveField("ID", uint64(666)),
HaveField("State", "running"),
HaveField("TopFunction", "runtime/debug.Stack"),
HaveField("Backtrace", stack)))
})
It("finds its Creator", func() {
creator, location := findCreator(`
goroutine 42 [chan receive]:
main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo
/home/foo/test.go:5 +0x64
`)
Expect(creator).To(Equal("main.foo"))
Expect(location).To(Equal("/home/foo/test.go:5"))
})
It("handles missing or invalid creator information", func() {
creator, location := findCreator("")
Expect(creator).To(BeEmpty())
Expect(location).To(BeEmpty())
creator, location = findCreator(`
goroutine 42 [chan receive]:
main.foo.func1()
/home/foo/test.go:6 +0x28
created by`)
Expect(creator).To(BeEmpty())
Expect(location).To(BeEmpty())
creator, location = findCreator(`
goroutine 42 [chan receive]:
main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo`)
Expect(creator).To(BeEmpty())
Expect(location).To(BeEmpty())
creator, location = findCreator(`
goroutine 42 [chan receive]:
main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo
/home/foo/test.go:5
`)
Expect(creator).To(BeEmpty())
Expect(location).To(BeEmpty())
})
})
Context("live", func() {
It("discovers current goroutine information", func() {
type T struct{}
pkg := reflect.TypeOf(T{}).PkgPath()
gs := goroutines(false)
Expect(gs).To(HaveLen(1))
Expect(gs[0]).To(And(
HaveField("ID", Not(BeZero())),
HaveField("State", "running"),
HaveField("TopFunction", pkg+".stacks"),
HaveField("Backtrace", MatchRegexp(pkg+`.stacks.*
`))))
})
It("discovers a goroutine's creator", func() {
ch := make(chan Goroutine)
go func() {
ch <- Current()
}()
g := <-ch
Expect(g.CreatorFunction).NotTo(BeEmpty(), "no creator: %s", g.Backtrace)
Expect(g.BornAt).NotTo(BeEmpty())
})
It("discovers all goroutine information", func() {
By("creating a chan receive canary goroutine")
done := make(chan struct{})
go testWait(done)
once := sync.Once{}
cloze := func() { once.Do(func() { close(done) }) }
defer cloze()
By("getting all goroutines including canary")
type T struct{}
pkg := reflect.TypeOf(T{}).PkgPath()
Eventually(Goroutines).
WithTimeout(1 * time.Second).WithPolling(250 * time.Millisecond).
Should(ContainElements(
And(
HaveField("TopFunction", pkg+".stacks"),
HaveField("State", "running")),
And(
HaveField("TopFunction", pkg+".testWait"),
HaveField("State", "chan receive")),
))
By("getting all goroutines after being done with the canary")
cloze()
Eventually(Goroutines).
WithTimeout(1 * time.Second).WithPolling(250 * time.Millisecond).
ShouldNot(ContainElement(HaveField("TopFunction", pkg+".testWait")))
})
})
})
func testWait(done <-chan struct{}) {
<-done
}
golang-gomega-1.27.10/gleak/goroutine/stack.go 0000664 0000000 0000000 00000000714 14462163431 0021126 0 ustar 00root root 0000000 0000000 package goroutine
import "runtime"
const startStackBufferSize = 64 * 1024 // 64kB
// stacks returns stack trace information for either all goroutines or only the
// current goroutine. It is a convenience wrapper around runtime.Stack, hiding
// the result allocation.
func stacks(all bool) []byte {
for size := startStackBufferSize; ; size *= 2 {
buffer := make([]byte, size)
if n := runtime.Stack(buffer, all); n < size {
return buffer[:n]
}
}
}
golang-gomega-1.27.10/gleak/goroutines.go 0000664 0000000 0000000 00000000667 14462163431 0020213 0 ustar 00root root 0000000 0000000 package gleak
import "github.com/onsi/gomega/gleak/goroutine"
// Goroutine represents information about a single goroutine and is a
// convenience type alias.
type Goroutine = goroutine.Goroutine
// Goroutines returns information about all goroutines: their goroutine IDs, the
// names of the topmost functions in the backtraces, and finally the goroutine
// backtraces.
func Goroutines() []Goroutine {
return goroutine.Goroutines()
}
golang-gomega-1.27.10/gleak/goroutines_test.go 0000664 0000000 0000000 00000000501 14462163431 0021235 0 ustar 00root root 0000000 0000000 package gleak
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("goroutines", func() {
It("returns all goroutines", func() {
Expect(Goroutines()).To(ContainElement(
HaveField("TopFunction", SatisfyAny(
Equal("testing.(*T).Run"),
Equal("testing.RunTests")))))
})
})
golang-gomega-1.27.10/gleak/have_leaked_matcher.go 0000664 0000000 0000000 00000027550 14462163431 0021750 0 ustar 00root root 0000000 0000000 package gleak
import (
"fmt"
"path"
"path/filepath"
"reflect"
"strconv"
"strings"
"github.com/onsi/gomega"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/gleak/goroutine"
"github.com/onsi/gomega/types"
)
// ReportFilenameWithPath controls whether to show call locations in leak
// reports by default in abbreviated form with only source code filename with
// package name and line number, or alternatively with source code filename with
// path and line number.
//
// That is, with ReportFilenameWithPath==false:
//
// foo/bar.go:123
//
// Or with ReportFilenameWithPath==true:
//
// /home/goworld/coolprojects/mymodule/foo/bar.go:123
var ReportFilenameWithPath = false
// standardFilters specifies the always automatically included no-leak goroutine
// filter matchers.
//
// Note: it's okay to instantiate the Gomega Matchers here, as all goroutine
// filtering-related gleak matchers are stateless with respect to any actual
// value they try to match. This allows us to simply prepend them to any
// user-supplied optional matchers when HaveLeaked returns a new goroutine
// leakage detecting matcher.
//
// Note: cgo's goroutines with status "[syscall, locked to thread]" do not
// appear any longer (since mid-2017), as these cgo goroutines are put into the
// "dead" state when not in use. See: https://github.com/golang/go/issues/16714
// and https://go-review.googlesource.com/c/go/+/45030/.
var standardFilters = []types.GomegaMatcher{
// Ginkgo testing framework
IgnoringTopFunction("github.com/onsi/ginkgo/v2/internal.(*Suite).runNode"),
IgnoringTopFunction("github.com/onsi/ginkgo/v2/internal.(*Suite).runNode..."),
gomega.And(IgnoringTopFunction("runtime.goexit1"), IgnoringCreator("github.com/onsi/ginkgo/v2/internal.(*Suite).runNode")),
IgnoringTopFunction("github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts..."),
IgnoringTopFunction("github.com/onsi/ginkgo/internal/specrunner.(*SpecRunner).registerForInterrupts"),
IgnoringCreator("github.com/onsi/ginkgo/v2/internal.(*genericOutputInterceptor).ResumeIntercepting"),
IgnoringCreator("github.com/onsi/ginkgo/v2/internal.(*genericOutputInterceptor).ResumeIntercepting..."),
IgnoringCreator("github.com/onsi/ginkgo/v2/internal.RegisterForProgressSignal"),
// goroutines of Go's own testing package for its own workings...
IgnoringTopFunction("testing.RunTests [chan receive]"),
IgnoringTopFunction("testing.(*T).Run [chan receive]"),
IgnoringTopFunction("testing.(*T).Parallel [chan receive]"),
// os/signal starts its own runtime goroutine, where loop calls signal_recv
// in a loop, so we need to expect them both...
IgnoringTopFunction("os/signal.signal_recv"),
IgnoringTopFunction("os/signal.loop"),
// signal.Notify starts a runtime goroutine...
IgnoringInBacktrace("runtime.ensureSigM"),
// reading a trace...
IgnoringInBacktrace("runtime.ReadTrace"),
}
// HaveLeaked succeeds (or rather, "suckceeds" considering it appears in failing
// tests) if after filtering out ("ignoring") the expected goroutines from the
// list of actual goroutines the remaining list of goroutines is non-empty.
// These goroutines not filtered out are considered to have been leaked.
//
// For convenience, HaveLeaked automatically filters out well-known runtime and
// testing goroutines using a built-in standard filter matchers list. In
// addition to the built-in filters, HaveLeaked accepts an optional list of
// non-leaky goroutine filter matchers. These filtering matchers can be
// specified in different formats, as described below.
//
// Since there might be "pending" goroutines at the end of tests that eventually
// will properly wind down so they aren't leaking, HaveLeaked is best paired
// with Eventually instead of Expect. In its shortest form this will use
// Eventually's default timeout and polling interval settings, but these can be
// overridden as usual:
//
// // Remember to use "Goroutines" and not "Goroutines()" with Eventually()!
// Eventually(Goroutines).ShouldNot(HaveLeaked())
// Eventually(Goroutines).WithTimeout(5 * time.Second).ShouldNot(HaveLeaked())
//
// In its simplest form, an expected non-leaky goroutine can be identified by
// passing the (fully qualified) name (in form of a string) of the topmost
// function in the backtrace. For instance:
//
// Eventually(Goroutines).ShouldNot(HaveLeaked("foo.bar"))
//
// This is the shorthand equivalent to this explicit form:
//
// Eventually(Goroutines).ShouldNot(HaveLeaked(IgnoringTopFunction("foo.bar")))
//
// HaveLeak also accepts passing a slice of Goroutine objects to be considered
// non-leaky goroutines.
//
// snapshot := Goroutines()
// DoSomething()
// Eventually(Goroutines).ShouldNot(HaveLeaked(snapshot))
//
// Again, this is shorthand for the following explicit form:
//
// snapshot := Goroutines()
// DoSomething()
// Eventually(Goroutines).ShouldNot(HaveLeaked(IgnoringGoroutines(snapshot)))
//
// Finally, HaveLeaked accepts any GomegaMatcher and will repeatedly pass it a
// Goroutine object: if the matcher succeeds, the Goroutine object in question
// is considered to be non-leaked and thus filtered out. While the following
// built-in Goroutine filter matchers should hopefully cover most situations,
// any suitable GomegaMatcher can be used for tricky leaky Goroutine filtering.
//
// IgnoringTopFunction("foo.bar")
// IgnoringTopFunction("foo.bar...")
// IgnoringTopFunction("foo.bar [chan receive]")
// IgnoringGoroutines(expectedGoroutines)
// IgnoringInBacktrace("foo.bar.baz")
func HaveLeaked(ignoring ...interface{}) types.GomegaMatcher {
m := &HaveLeakedMatcher{filters: standardFilters}
for _, ign := range ignoring {
switch ign := ign.(type) {
case string:
m.filters = append(m.filters, IgnoringTopFunction(ign))
case []Goroutine:
m.filters = append(m.filters, IgnoringGoroutines(ign))
case types.GomegaMatcher:
m.filters = append(m.filters, ign)
default:
panic(fmt.Sprintf("HaveLeaked expected a string, []Goroutine, or GomegaMatcher, but got:\n%s", format.Object(ign, 1)))
}
}
return m
}
// HaveLeakedMatcher implements the HaveLeaked Gomega Matcher that succeeds if
// the actual list of goroutines is non-empty after filtering out the expected
// goroutines.
type HaveLeakedMatcher struct {
filters []types.GomegaMatcher // expected goroutines that aren't leaks.
leaked []Goroutine // surplus goroutines which we consider to be leaks.
}
var gsT = reflect.TypeOf([]Goroutine{})
// Match succeeds if actual is an array or slice of Goroutine
// information and still contains goroutines after filtering out all expected
// goroutines that were specified when creating the matcher.
func (matcher *HaveLeakedMatcher) Match(actual interface{}) (success bool, err error) {
val := reflect.ValueOf(actual)
switch val.Kind() {
case reflect.Array, reflect.Slice:
if !val.Type().AssignableTo(gsT) {
return false, fmt.Errorf(
"HaveLeaked matcher expects an array or slice of goroutines. Got:\n%s",
format.Object(actual, 1))
}
default:
return false, fmt.Errorf(
"HaveLeaked matcher expects an array or slice of goroutines. Got:\n%s",
format.Object(actual, 1))
}
goroutines := val.Convert(gsT).Interface().([]Goroutine)
matcher.leaked, err = matcher.filter(goroutines, matcher.filters)
if err != nil {
return false, err
}
if len(matcher.leaked) == 0 {
return false, nil
}
return true, nil // we have leak(ed)
}
// FailureMessage returns a failure message if there are leaked goroutines.
func (matcher *HaveLeakedMatcher) FailureMessage(actual interface{}) (message string) {
return fmt.Sprintf("Expected to leak %d goroutines:\n%s", len(matcher.leaked), matcher.listGoroutines(matcher.leaked, 1))
}
// NegatedFailureMessage returns a negated failure message if there aren't any leaked goroutines.
func (matcher *HaveLeakedMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return fmt.Sprintf("Expected not to leak %d goroutines:\n%s", len(matcher.leaked), matcher.listGoroutines(matcher.leaked, 1))
}
// listGoroutines returns a somewhat compact textual representation of the
// specified goroutines, by ignoring the often quite lengthy backtrace
// information.
func (matcher *HaveLeakedMatcher) listGoroutines(gs []Goroutine, indentation uint) string {
var buff strings.Builder
indent := strings.Repeat(format.Indent, int(indentation))
backtraceIdent := strings.Repeat(format.Indent, int(indentation+1))
for gidx, g := range gs {
if gidx > 0 {
buff.WriteRune('\n')
}
buff.WriteString(indent)
buff.WriteString("goroutine ")
buff.WriteString(strconv.FormatUint(g.ID, 10))
buff.WriteString(" [")
buff.WriteString(g.State)
buff.WriteString("]\n")
backtrace := g.Backtrace
for backtrace != "" {
buff.WriteString(backtraceIdent)
// take the next two lines (function name and file name plus line
// number) and output them as a single indented line.
nlIdx := strings.IndexRune(backtrace, '\n')
if nlIdx < 0 {
// ...a dodgy single line
buff.WriteString(backtrace)
break
}
calledFuncName := backtrace[:nlIdx]
// Take care of not mangling the optional "created by " prefix is
// present, when formatting the location to use either long or
// shortened filenames and paths.
location := backtrace[nlIdx+1:]
nnlIdx := strings.IndexRune(location, '\n')
if nnlIdx >= 0 {
backtrace, location = location[nnlIdx+1:], location[:nnlIdx]
} else {
backtrace = "" // ...the next location line is missing
}
// Don't accidentally strip off the "created by" prefix when
// shortening the call site location filename...
location = strings.TrimSpace(location) // strip of indentation
lineno := ""
if linenoIdx := strings.LastIndex(location, ":"); linenoIdx >= 0 {
location, lineno = location[:linenoIdx], location[linenoIdx+1:]
}
location = formatFilename(location) + ":" + lineno
// Add to compact backtrace
buff.WriteString(calledFuncName)
buff.WriteString(" at ")
// Don't output any program counter hex offsets, so strip them out
// here, if present; well, they should always be present, but better
// safe than sorry.
if offsetIdx := strings.LastIndexFunc(location,
func(r rune) bool { return r == ' ' }); offsetIdx >= 0 {
buff.WriteString(location[:offsetIdx])
} else {
buff.WriteString(location)
}
if backtrace != "" {
buff.WriteRune('\n')
}
}
}
return buff.String()
}
// filter returns a list of leaked goroutines by removing all expected
// goroutines from the given list of goroutines, using the specified checkers.
// The calling goroutine is always filtered out automatically. A checker checks
// if a certain goroutine is expected (then it gets filtered out), or not. If
// all checkers do not signal that they expect a certain goroutine then this
// goroutine is considered to be a leak.
func (matcher *HaveLeakedMatcher) filter(
goroutines []Goroutine, filters []types.GomegaMatcher,
) ([]Goroutine, error) {
gs := make([]Goroutine, 0, len(goroutines))
myID := goroutine.Current().ID
nextgoroutine:
for _, g := range goroutines {
if g.ID == myID {
continue
}
for _, filter := range filters {
matches, err := filter.Match(g)
if err != nil {
return nil, err
}
if matches {
continue nextgoroutine
}
}
gs = append(gs, g)
}
return gs, nil
}
// formatFilename takes the ReportFilenameWithPath setting into account to
// either return the full specified filename with a path or alternatively
// shortening it to contain only the package name and the filename, but not the
// full path.
func formatFilename(filename string) string {
if ReportFilenameWithPath {
return filename
}
dir := filepath.Dir(filename)
pkg := filepath.Base(dir)
switch pkg {
case ".", "..", "/", "\\":
pkg = ""
}
// Go dumps stacks always with file locations containing forward slashes,
// even on Windows. Thus, we do NOT use filepath.Join here, but instead
// path.Join in order to keep with using forward slashes.
return path.Join(pkg, filepath.ToSlash(filepath.Base(filename)))
}
golang-gomega-1.27.10/gleak/have_leaked_matcher_test.go 0000664 0000000 0000000 00000015265 14462163431 0023007 0 ustar 00root root 0000000 0000000 package gleak
import (
"os"
"os/signal"
"sync"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
// Note: Go's stack dumps (backtraces) always contain forward slashes, even on
// Windows. The following tests thus work the same both on *nix and Windows.
var _ = Describe("HaveLeaked", func() {
It("renders indented goroutine information including (malformed) backtrace", func() {
gs := []Goroutine{
{
ID: 42,
State: "stoned",
Backtrace: `main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo
/home/foo/test.go:5 +0x64
`,
},
}
m := HaveLeaked().(*HaveLeakedMatcher)
Expect(m.listGoroutines(gs, 1)).To(Equal(` goroutine 42 [stoned]
main.foo.func1() at foo/test.go:6
created by main.foo at foo/test.go:5`))
gs = []Goroutine{
{
ID: 42,
State: "stoned",
Backtrace: `main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo
/home/foo/test.go:5 +0x64`,
},
}
Expect(m.listGoroutines(gs, 1)).To(Equal(` goroutine 42 [stoned]
main.foo.func1() at foo/test.go:6
created by main.foo at foo/test.go:5`))
gs = []Goroutine{
{
ID: 42,
State: "stoned",
Backtrace: `main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo
/home/foo/test.go:5`,
},
}
Expect(m.listGoroutines(gs, 1)).To(Equal(` goroutine 42 [stoned]
main.foo.func1() at foo/test.go:6
created by main.foo at foo/test.go:5`))
gs = []Goroutine{
{
ID: 42,
State: "stoned",
Backtrace: `main.foo.func1()
/home/foo/test.go:6 +0x28
created by main.foo`,
},
}
Expect(m.listGoroutines(gs, 1)).To(Equal(` goroutine 42 [stoned]
main.foo.func1() at foo/test.go:6
created by main.foo`))
})
It("considers testing and runtime goroutines not to be leaks", func() {
Eventually(Goroutines).WithTimeout(2*time.Second).WithPolling(250*time.Millisecond).
ShouldNot(HaveLeaked(), "should not find any leaks by default")
})
When("using signals", func() {
It("doesn't find leaks", func() {
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt)
Eventually(Goroutines).WithTimeout(2*time.Second).WithPolling(250*time.Millisecond).
ShouldNot(HaveLeaked(), "found signal.Notify leaks")
signal.Reset(os.Interrupt)
Eventually(Goroutines).WithTimeout(2*time.Second).WithPolling(250*time.Millisecond).
ShouldNot(HaveLeaked(), "found signal.Reset leaks")
})
})
It("checks against list of expected goroutines", func() {
By("taking a snapshot")
gs := Goroutines()
m := HaveLeaked(gs)
By("starting a goroutine")
done := make(chan struct{})
var once sync.Once
go func() {
<-done
}()
defer once.Do(func() { close(done) })
By("detecting the goroutine")
Expect(m.Match(Goroutines())).To(BeTrue())
By("terminating the goroutine and ensuring it has terminated")
once.Do(func() { close(done) })
Eventually(func() (bool, error) {
return m.Match(Goroutines())
}).Should(BeFalse())
})
Context("failure messages", func() {
var snapshot []Goroutine
BeforeEach(func() {
snapshot = Goroutines()
done := make(chan struct{})
go func() {
<-done
}()
DeferCleanup(func() {
close(done)
Eventually(Goroutines).ShouldNot(HaveLeaked(snapshot))
})
})
It("returns a failure message", func() {
m := HaveLeaked(snapshot)
gs := Goroutines()
Expect(m.Match(gs)).To(BeTrue())
Expect(m.FailureMessage(gs)).To(MatchRegexp(`Expected to leak 1 goroutines:
goroutine \d+ \[.+\]
.* at .*:\d+
created by .* at .*:\d+`))
})
It("returns a negated failure message", func() {
m := HaveLeaked(snapshot)
gs := Goroutines()
Expect(m.Match(gs)).To(BeTrue())
Expect(m.NegatedFailureMessage(gs)).To(MatchRegexp(`Expected not to leak 1 goroutines:
goroutine \d+ \[.+\]
.* at .*:\d+
created by .* at .*:\d+`))
})
When("things go wrong", func() {
It("rejects unsupported filter args types", func() {
Expect(func() { _ = HaveLeaked(42) }).To(PanicWith(
"HaveLeaked expected a string, []Goroutine, or GomegaMatcher, but got:\n : 42"))
})
It("accepts plain strings as filters", func() {
m := HaveLeaked("foo.bar")
Expect(m.Match([]Goroutine{
{TopFunction: "foo.bar"},
})).To(BeFalse())
})
It("expects actual to be a slice of Goroutine", func() {
m := HaveLeaked()
Expect(m.Match(nil)).Error().To(MatchError(
"HaveLeaked matcher expects an array or slice of goroutines. Got:\n : nil"))
Expect(m.Match("foo!")).Error().To(MatchError(
"HaveLeaked matcher expects an array or slice of goroutines. Got:\n : foo!"))
Expect(m.Match([]string{"foo!"})).Error().To(MatchError(
"HaveLeaked matcher expects an array or slice of goroutines. Got:\n <[]string | len:1, cap:1>: [\"foo!\"]"))
})
It("handles filter matcher errors", func() {
m := HaveLeaked(HaveField("foobar", BeNil()))
Expect(m.Match([]Goroutine{
{ID: 0},
})).Error().To(HaveOccurred())
})
})
})
Context("wrapped around test nodes", func() {
var snapshot []Goroutine
When("not leaking", func() {
BeforeEach(func() {
snapshot = Goroutines()
})
AfterEach(func() {
Eventually(Goroutines).ShouldNot(HaveLeaked(snapshot))
})
It("doesn't leak in test", func() {
// nothing
})
})
When("leaking", func() {
done := make(chan struct{})
BeforeEach(func() {
snapshot = Goroutines()
})
AfterEach(func() {
Expect(Goroutines()).To(HaveLeaked(snapshot))
close(done)
Eventually(Goroutines).ShouldNot(HaveLeaked(snapshot))
})
It("leaks in test", func() {
go func() {
<-done
}()
})
})
})
Context("handling file names and paths in backtraces", func() {
When("ReportFilenameWithPath is true", Ordered, func() {
var oldState bool
BeforeAll(func() {
oldState = ReportFilenameWithPath
ReportFilenameWithPath = true
DeferCleanup(func() {
ReportFilenameWithPath = oldState
})
})
It("doesn't shorten filenames", func() {
Expect(formatFilename("/home/foo/bar/baz.go")).To(Equal("/home/foo/bar/baz.go"))
})
})
When("ReportFilenameWithPath is false", Ordered, func() {
var oldState bool
BeforeAll(func() {
oldState = ReportFilenameWithPath
ReportFilenameWithPath = false
DeferCleanup(func() {
ReportFilenameWithPath = oldState
})
})
It("does return only package and filename, but no path", func() {
Expect(formatFilename("/home/foo/bar/baz.go")).To(Equal("bar/baz.go"))
Expect(formatFilename("/bar/baz.go")).To(Equal("bar/baz.go"))
Expect(formatFilename("/baz.go")).To(Equal("baz.go"))
Expect(formatFilename("/")).To(Equal("/"))
})
})
})
})
golang-gomega-1.27.10/gleak/ignoring_creator.go 0000664 0000000 0000000 00000004700 14462163431 0021340 0 ustar 00root root 0000000 0000000 package gleak
import (
"fmt"
"strings"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
// IgnoringCreator succeeds if the goroutine was created by a function matching
// the specified name. The expected creator function name is either in the form
// of "creatorfunction-name" or "creatorfunction-name...".
//
// An ellipsis "..." after a creatorfunction-name matches any creator function
// name if creatorfunction-name is a prefix and the goroutine's creator function
// name is at least one level deeper. For instance, "foo.bar..." matches
// "foo.bar.baz", but doesn't match "foo.bar".
func IgnoringCreator(creatorfname string) types.GomegaMatcher {
if strings.HasSuffix(creatorfname, "...") {
expectedCreatorFunction := creatorfname[:len(creatorfname)-3+1] // ...one trailing dot still expected
return &ignoringCreator{
expectedCreatorFunction: expectedCreatorFunction,
matchPrefix: true,
}
}
return &ignoringCreator{
expectedCreatorFunction: creatorfname,
}
}
type ignoringCreator struct {
expectedCreatorFunction string
matchPrefix bool
}
// Match succeeds if an actual goroutine's creator function in the backtrace
// matches the specified function name or function name prefix.
func (matcher *ignoringCreator) Match(actual interface{}) (success bool, err error) {
g, err := G(actual, "IgnoringCreator")
if err != nil {
return false, err
}
if matcher.matchPrefix {
return strings.HasPrefix(g.CreatorFunction, matcher.expectedCreatorFunction), nil
}
return g.CreatorFunction == matcher.expectedCreatorFunction, nil
}
// FailureMessage returns a failure message if the actual goroutine doesn't have
// the specified function name/prefix (and optional state) at the top of the
// backtrace.
func (matcher *ignoringCreator) FailureMessage(actual interface{}) (message string) {
return format.Message(actual, matcher.message())
}
// NegatedFailureMessage returns a failure message if the actual goroutine has
// the specified function name/prefix (and optional state) at the top of the
// backtrace.
func (matcher *ignoringCreator) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, "not "+matcher.message())
}
func (matcher *ignoringCreator) message() string {
if matcher.matchPrefix {
return fmt.Sprintf("to be created by a function with prefix %q", matcher.expectedCreatorFunction)
}
return fmt.Sprintf("to be created by %q", matcher.expectedCreatorFunction)
}
golang-gomega-1.27.10/gleak/ignoring_creator_test.go 0000664 0000000 0000000 00000004046 14462163431 0022402 0 ustar 00root root 0000000 0000000 package gleak
import (
"reflect"
"github.com/onsi/gomega/gleak/goroutine"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
func creator() Goroutine {
ch := make(chan Goroutine)
go func() {
ch <- goroutine.Current()
}()
return <-ch
}
var _ = Describe("IgnoringCreator matcher", func() {
It("returns an error for an invalid actual", func() {
m := IgnoringCreator("foo.bar")
Expect(m.Match(nil)).Error().To(MatchError("IgnoringCreator matcher expects a Goroutine or *Goroutine. Got:\n : nil"))
})
It("matches a creator function by full name", func() {
type T struct{}
pkg := reflect.TypeOf(T{}).PkgPath()
ignore := pkg + ".creator"
m := IgnoringCreator(ignore)
g := creator()
Expect(m.Match(g)).To(BeTrue(), "creator: %v\ntried to ignore: %s",
g.String(), ignore)
Expect(m.Match(goroutine.Current())).To(BeFalse())
})
It("matches a toplevel function by prefix", func() {
type T struct{}
pkg := reflect.TypeOf(T{}).PkgPath()
m := IgnoringCreator(pkg + "...")
g := creator()
Expect(m.Match(g)).To(BeTrue(), "creator %v", g.String())
Expect(m.Match(goroutine.Current())).To(BeFalse())
Expect(m.Match(Goroutine{
TopFunction: "spanish.inquisition",
})).To(BeFalse())
})
It("returns failure messages", func() {
m := IgnoringCreator("foo.bar")
Expect(m.FailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nto be created by \"foo.bar\""))
Expect(m.NegatedFailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nnot to be created by \"foo.bar\""))
m = IgnoringCreator("foo...")
Expect(m.FailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nto be created by a function with prefix \"foo.\""))
})
})
golang-gomega-1.27.10/gleak/ignoring_goroutines.go 0000664 0000000 0000000 00000004047 14462163431 0022103 0 ustar 00root root 0000000 0000000 package gleak
import (
"sort"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
// IgnoringGoroutines succeeds if an actual goroutine, identified by its ID, is
// in a slice of expected goroutines. A typical use of the IgnoringGoroutines
// matcher is to take a snapshot of the current goroutines just right before a
// test and then at the end of a test filtering out these "good" and known
// goroutines.
func IgnoringGoroutines(goroutines []Goroutine) types.GomegaMatcher {
m := &ignoringGoroutinesMatcher{
ignoreGoids: map[uint64]struct{}{},
}
for _, g := range goroutines {
m.ignoreGoids[g.ID] = struct{}{}
}
return m
}
type ignoringGoroutinesMatcher struct {
ignoreGoids map[uint64]struct{}
}
// Match succeeds if actual is a Goroutine and its ID is in the set of
// goroutine IDs to expect and thus to ignore in leak checks.
func (matcher *ignoringGoroutinesMatcher) Match(actual interface{}) (success bool, err error) {
g, err := G(actual, "IgnoringGoroutines")
if err != nil {
return false, err
}
_, ok := matcher.ignoreGoids[g.ID]
return ok, nil
}
// FailureMessage returns a failure message if the actual goroutine isn't in the
// set of goroutines to be ignored.
func (matcher *ignoringGoroutinesMatcher) FailureMessage(actual interface{}) (message string) {
return format.Message(actual, "to be contained in the list of expected goroutine IDs", matcher.expectedGoids())
}
// NegatedFailureMessage returns a negated failure message if the actual
// goroutine actually is in the set of goroutines to be ignored.
func (matcher *ignoringGoroutinesMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, "not to be contained in the list of expected goroutine IDs", matcher.expectedGoids())
}
// expectedGoids returns the sorted list of expected goroutine IDs.
func (matcher *ignoringGoroutinesMatcher) expectedGoids() []uint64 {
ids := make([]uint64, 0, len(matcher.ignoreGoids))
for id := range matcher.ignoreGoids {
ids = append(ids, id)
}
sort.Sort(Uint64Slice(ids))
return ids
}
golang-gomega-1.27.10/gleak/ignoring_goroutines_test.go 0000664 0000000 0000000 00000002312 14462163431 0023133 0 ustar 00root root 0000000 0000000 package gleak
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("IgnoringGoroutines matcher", func() {
It("returns an error for an invalid actual", func() {
m := IgnoringGoroutines(Goroutines())
Expect(m.Match(nil)).Error().To(MatchError(
"IgnoringGoroutines matcher expects a Goroutine or *Goroutine. Got:\n : nil"))
})
It("matches", func() {
gs := Goroutines()
me := gs[0]
m := IgnoringGoroutines(gs)
Expect(m.Match(me)).To(BeTrue())
Expect(m.Match(gs[1])).To(BeTrue())
Expect(m.Match(Goroutine{})).To(BeFalse())
})
It("returns failure messages", func() {
m := IgnoringGoroutines(Goroutines())
Expect(m.FailureMessage(Goroutine{})).To(MatchRegexp(
`Expected\n : {ID: 0, State: "", TopFunction: "", CreatorFunction: "", BornAt: ""}\nto be contained in the list of expected goroutine IDs\n <\[\]uint64 | len:\d+, cap:\d+>: [.*]`))
Expect(m.NegatedFailureMessage(Goroutine{})).To(MatchRegexp(
`Expected\n : {ID: 0, State: "", TopFunction: "", CreatorFunction: "", BornAt: ""}\nnot to be contained in the list of expected goroutine IDs\n <\[\]uint64 | len:\d+, cap:\d+>: [.*]`))
})
})
golang-gomega-1.27.10/gleak/ignoring_in_backtrace.go 0000664 0000000 0000000 00000002551 14462163431 0022310 0 ustar 00root root 0000000 0000000 package gleak
import (
"fmt"
"strings"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
// IgnoringInBacktrace succeeds if a function name is contained in the backtrace
// of the actual goroutine description.
func IgnoringInBacktrace(fname string) types.GomegaMatcher {
return &ignoringInBacktraceMatcher{fname: fname}
}
type ignoringInBacktraceMatcher struct {
fname string
}
// Match succeeds if actual's backtrace contains the specified function name.
func (matcher *ignoringInBacktraceMatcher) Match(actual interface{}) (success bool, err error) {
g, err := G(actual, "IgnoringInBacktrace")
if err != nil {
return false, err
}
return strings.Contains(g.Backtrace, matcher.fname), nil
}
// FailureMessage returns a failure message if the actual's backtrace does not
// contain the specified function name.
func (matcher *ignoringInBacktraceMatcher) FailureMessage(actual interface{}) (message string) {
return format.Message(actual, fmt.Sprintf("to contain %q in the goroutine's backtrace", matcher.fname))
}
// NegatedFailureMessage returns a failure message if the actual's backtrace
// does contain the specified function name.
func (matcher *ignoringInBacktraceMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, fmt.Sprintf("not to contain %q in the goroutine's backtrace", matcher.fname))
}
golang-gomega-1.27.10/gleak/ignoring_in_backtrace_test.go 0000664 0000000 0000000 00000002347 14462163431 0023352 0 ustar 00root root 0000000 0000000 package gleak
import (
"reflect"
"github.com/onsi/gomega/gleak/goroutine"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("IgnoringInBacktrace matcher", func() {
It("returns an error for an invalid actual", func() {
m := IgnoringInBacktrace("foo.bar")
Expect(m.Match(nil)).Error().To(MatchError(
"IgnoringInBacktrace matcher expects a Goroutine or *Goroutine. Got:\n : nil"))
})
It("matches", func() {
type T struct{}
pkg := reflect.TypeOf(T{}).PkgPath()
m := IgnoringInBacktrace(pkg + "/goroutine.stacks")
Expect(m.Match(somefunction())).To(BeTrue())
})
It("returns failure messages", func() {
m := IgnoringInBacktrace("foo.bar")
Expect(m.FailureMessage(Goroutine{Backtrace: "abc"})).To(MatchRegexp(
`Expected\n : {ID: 0, State: "", TopFunction: "", CreatorFunction: "", BornAt: ""}\nto contain "foo.bar" in the goroutine's backtrace`))
Expect(m.NegatedFailureMessage(Goroutine{Backtrace: "abc"})).To(MatchRegexp(
`Expected\n : {ID: 0, State: "", TopFunction: "", CreatorFunction: "", BornAt: ""}\nnot to contain "foo.bar" in the goroutine's backtrace`))
})
})
func somefunction() Goroutine {
return goroutine.Current()
}
golang-gomega-1.27.10/gleak/ignoring_top_function.go 0000664 0000000 0000000 00000007021 14462163431 0022407 0 ustar 00root root 0000000 0000000 package gleak
import (
"fmt"
"strings"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
// IgnoringTopFunction succeeds if the topmost function in the backtrace of an
// actual goroutine has the specified function name, and optionally the actual
// goroutine has the specified goroutine state.
//
// The expected top function name topfn is either in the form of
// "topfunction-name", "topfunction-name...", or "topfunction-name [state]".
//
// An ellipsis "..." after a topfunction-name matches any goroutine's top
// function name if topfunction-name is a prefix and the goroutine's top
// function name is at least one level deeper. For instance, "foo.bar..."
// matches "foo.bar.baz", but doesn't match "foo.bar".
//
// If the optional expected state is specified, then a goroutine's state needs
// to start with this expected state text. For instance, "foo.bar [running]"
// matches a goroutine where the name of the top function is "foo.bar" and the
// goroutine's state starts with "running".
func IgnoringTopFunction(topfname string) types.GomegaMatcher {
if brIndex := strings.Index(topfname, "["); brIndex >= 0 {
expectedState := strings.Trim(topfname[brIndex:], "[]")
expectedTopFunction := strings.Trim(topfname[:brIndex], " ")
return &ignoringTopFunctionMatcher{
expectedTopFunction: expectedTopFunction,
expectedState: expectedState,
}
}
if strings.HasSuffix(topfname, "...") {
expectedTopFunction := topfname[:len(topfname)-3+1] // ...one trailing dot still expected
return &ignoringTopFunctionMatcher{
expectedTopFunction: expectedTopFunction,
matchPrefix: true,
}
}
return &ignoringTopFunctionMatcher{
expectedTopFunction: topfname,
}
}
type ignoringTopFunctionMatcher struct {
expectedTopFunction string
expectedState string
matchPrefix bool
}
// Match succeeds if an actual goroutine's top function in the backtrace matches
// the specified function name or function name prefix, or name and goroutine
// state.
func (matcher *ignoringTopFunctionMatcher) Match(actual interface{}) (success bool, err error) {
g, err := G(actual, "IgnoringTopFunction")
if err != nil {
return false, err
}
if matcher.matchPrefix {
return strings.HasPrefix(g.TopFunction, matcher.expectedTopFunction), nil
}
if g.TopFunction != matcher.expectedTopFunction {
return false, nil
}
if matcher.expectedState == "" {
return true, nil
}
return strings.HasPrefix(g.State, matcher.expectedState), nil
}
// FailureMessage returns a failure message if the actual goroutine doesn't have
// the specified function name/prefix (and optional state) at the top of the
// backtrace.
func (matcher *ignoringTopFunctionMatcher) FailureMessage(actual interface{}) (message string) {
return format.Message(actual, matcher.message())
}
// NegatedFailureMessage returns a failure message if the actual goroutine has
// the specified function name/prefix (and optional state) at the top of the
// backtrace.
func (matcher *ignoringTopFunctionMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, "not "+matcher.message())
}
func (matcher *ignoringTopFunctionMatcher) message() string {
if matcher.matchPrefix {
return fmt.Sprintf("to have the prefix %q for its topmost function", matcher.expectedTopFunction)
}
if matcher.expectedState != "" {
return fmt.Sprintf("to have the topmost function %q and the state %q",
matcher.expectedTopFunction, matcher.expectedState)
}
return fmt.Sprintf("to have the topmost function %q", matcher.expectedTopFunction)
}
golang-gomega-1.27.10/gleak/ignoring_top_function_test.go 0000664 0000000 0000000 00000004672 14462163431 0023457 0 ustar 00root root 0000000 0000000 package gleak
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("IgnoringTopFunction matcher", func() {
It("returns an error for an invalid actual", func() {
m := IgnoringTopFunction("foo.bar")
Expect(m.Match(nil)).Error().To(MatchError("IgnoringTopFunction matcher expects a Goroutine or *Goroutine. Got:\n : nil"))
})
It("matches a toplevel function by full name", func() {
m := IgnoringTopFunction("foo.bar")
Expect(m.Match(Goroutine{
TopFunction: "foo.bar",
})).To(BeTrue())
Expect(m.Match(Goroutine{
TopFunction: "main.main",
})).To(BeFalse())
})
It("matches a toplevel function by prefix", func() {
m := IgnoringTopFunction("foo...")
Expect(m.Match(Goroutine{
TopFunction: "foo.bar",
})).To(BeTrue())
Expect(m.Match(Goroutine{
TopFunction: "foo",
})).To(BeFalse())
Expect(m.Match(Goroutine{
TopFunction: "spanish.inquisition",
})).To(BeFalse())
})
It("matches a toplevel function by name and state prefix", func() {
m := IgnoringTopFunction("foo.bar [worried]")
Expect(m.Match(Goroutine{
TopFunction: "foo.bar",
State: "worried, stalled",
})).To(BeTrue())
Expect(m.Match(Goroutine{
TopFunction: "foo.bar",
State: "uneasy, anxious",
})).To(BeFalse())
})
It("returns failure messages", func() {
m := IgnoringTopFunction("foo.bar")
Expect(m.FailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nto have the topmost function \"foo.bar\""))
Expect(m.NegatedFailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nnot to have the topmost function \"foo.bar\""))
m = IgnoringTopFunction("foo.bar [worried]")
Expect(m.FailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nto have the topmost function \"foo.bar\" and the state \"worried\""))
m = IgnoringTopFunction("foo...")
Expect(m.FailureMessage(Goroutine{ID: 42, TopFunction: "foo"})).To(Equal(
"Expected\n : {ID: 42, State: \"\", TopFunction: \"foo\", CreatorFunction: \"\", BornAt: \"\"}\nto have the prefix \"foo.\" for its topmost function"))
})
})
golang-gomega-1.27.10/gleak/util.go 0000664 0000000 0000000 00000002643 14462163431 0016766 0 ustar 00root root 0000000 0000000 package gleak
import (
"fmt"
"sort"
"strconv"
"strings"
"github.com/onsi/gomega/format"
)
// G takes an actual "any" untyped value and returns it as a typed Goroutine, if
// possible. It returns an error if actual isn't of either type Goroutine or a
// pointer to it. G is intended to be mainly used by goroutine-related Gomega
// matchers, such as IgnoringTopFunction, et cetera.
func G(actual interface{}, matchername string) (Goroutine, error) {
if actual != nil {
switch actual := actual.(type) {
case Goroutine:
return actual, nil
case *Goroutine:
return *actual, nil
}
}
return Goroutine{},
fmt.Errorf("%s matcher expects a Goroutine or *Goroutine. Got:\n%s",
matchername, format.Object(actual, 1))
}
// goids returns a (sorted) list of Goroutine IDs in textual format.
func goids(gs []Goroutine) string {
ids := make([]uint64, len(gs))
for idx, g := range gs {
ids[idx] = g.ID
}
sort.Sort(Uint64Slice(ids))
var buff strings.Builder
for idx, id := range ids {
if idx > 0 {
buff.WriteString(", ")
}
buff.WriteString(strconv.FormatInt(int64(id), 10))
}
return buff.String()
}
// Uint64Slice implements the sort.Interface for a []uint64 to sort in
// increasing order.
type Uint64Slice []uint64
func (s Uint64Slice) Len() int { return len(s) }
func (s Uint64Slice) Less(a, b int) bool { return s[a] < s[b] }
func (s Uint64Slice) Swap(a, b int) { s[a], s[b] = s[b], s[a] }
golang-gomega-1.27.10/gleak/util_test.go 0000664 0000000 0000000 00000002335 14462163431 0020023 0 ustar 00root root 0000000 0000000 package gleak
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("utilities", func() {
Context("G(oroutine) descriptions", func() {
It("returns an error for actual ", func() {
Expect(func() { _, _ = G(nil, "foo") }).NotTo(Panic())
Expect(G(nil, "foo")).Error().To(MatchError("foo matcher expects a Goroutine or *Goroutine. Got:\n : nil"))
})
It("returns an error when passing something that's not a goroutine by any means", func() {
Expect(func() { _, _ = G("foobar", "foo") }).NotTo(Panic())
Expect(G("foobar", "foo")).Error().To(MatchError("foo matcher expects a Goroutine or *Goroutine. Got:\n : foobar"))
})
It("returns a goroutine", func() {
actual := Goroutine{ID: 42}
g, err := G(actual, "foo")
Expect(err).NotTo(HaveOccurred())
Expect(g.ID).To(Equal(uint64(42)))
g, err = G(&actual, "foo")
Expect(err).NotTo(HaveOccurred())
Expect(g.ID).To(Equal(uint64(42)))
})
})
It("returns a list of Goroutine IDs in textual format", func() {
Expect(goids(nil)).To(BeEmpty())
Expect(goids([]Goroutine{
{ID: 666},
{ID: 42},
})).To(Equal("42, 666"))
Expect(goids([]Goroutine{
{ID: 42},
})).To(Equal("42"))
})
})
golang-gomega-1.27.10/gmeasure/ 0000775 0000000 0000000 00000000000 14462163431 0016202 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gmeasure/cache.go 0000664 0000000 0000000 00000012344 14462163431 0017600 0 ustar 00root root 0000000 0000000 package gmeasure
import (
"crypto/md5"
"encoding/json"
"fmt"
"os"
"path/filepath"
"github.com/onsi/gomega/internal/gutil"
)
const CACHE_EXT = ".gmeasure-cache"
/*
ExperimentCache provides a director-and-file based cache of experiments
*/
type ExperimentCache struct {
Path string
}
/*
NewExperimentCache creates and initializes a new cache. Path must point to a directory (if path does not exist, NewExperimentCache will create a directory at path).
Cached Experiments are stored as separate files in the cache directory - the filename is a hash of the Experiment name. Each file contains two JSON-encoded objects - a CachedExperimentHeader that includes the experiment's name and cache version number, and then the Experiment itself.
*/
func NewExperimentCache(path string) (ExperimentCache, error) {
stat, err := os.Stat(path)
if os.IsNotExist(err) {
err := os.MkdirAll(path, 0777)
if err != nil {
return ExperimentCache{}, err
}
} else if !stat.IsDir() {
return ExperimentCache{}, fmt.Errorf("%s is not a directory", path)
}
return ExperimentCache{
Path: path,
}, nil
}
/*
CachedExperimentHeader captures the name of the Cached Experiment and its Version
*/
type CachedExperimentHeader struct {
Name string
Version int
}
func (cache ExperimentCache) hashOf(name string) string {
return fmt.Sprintf("%x", md5.Sum([]byte(name)))
}
func (cache ExperimentCache) readHeader(filename string) (CachedExperimentHeader, error) {
out := CachedExperimentHeader{}
f, err := os.Open(filepath.Join(cache.Path, filename))
if err != nil {
return out, err
}
defer f.Close()
err = json.NewDecoder(f).Decode(&out)
return out, err
}
/*
List returns a list of all Cached Experiments found in the cache.
*/
func (cache ExperimentCache) List() ([]CachedExperimentHeader, error) {
var out []CachedExperimentHeader
names, err := gutil.ReadDir(cache.Path)
if err != nil {
return out, err
}
for _, name := range names {
if filepath.Ext(name) != CACHE_EXT {
continue
}
header, err := cache.readHeader(name)
if err != nil {
return out, err
}
out = append(out, header)
}
return out, nil
}
/*
Clear empties out the cache - this will delete any and all detected cache files in the cache directory. Use with caution!
*/
func (cache ExperimentCache) Clear() error {
names, err := gutil.ReadDir(cache.Path)
if err != nil {
return err
}
for _, name := range names {
if filepath.Ext(name) != CACHE_EXT {
continue
}
err := os.Remove(filepath.Join(cache.Path, name))
if err != nil {
return err
}
}
return nil
}
/*
Load fetches an experiment from the cache. Lookup occurs by name. Load requires that the version numer in the cache is equal to or greater than the passed-in version.
If an experiment with corresponding name and version >= the passed-in version is found, it is unmarshaled and returned.
If no experiment is found, or the cached version is smaller than the passed-in version, Load will return nil.
When paired with Ginkgo you can cache experiments and prevent potentially expensive recomputation with this pattern:
const EXPERIMENT_VERSION = 1 //bump this to bust the cache and recompute _all_ experiments
Describe("some experiments", func() {
var cache gmeasure.ExperimentCache
var experiment *gmeasure.Experiment
BeforeEach(func() {
cache = gmeasure.NewExperimentCache("./gmeasure-cache")
name := CurrentSpecReport().LeafNodeText
experiment = cache.Load(name, EXPERIMENT_VERSION)
if experiment != nil {
AddReportEntry(experiment)
Skip("cached")
}
experiment = gmeasure.NewExperiment(name)
AddReportEntry(experiment)
})
It("foo runtime", func() {
experiment.SampleDuration("runtime", func() {
//do stuff
}, gmeasure.SamplingConfig{N:100})
})
It("bar runtime", func() {
experiment.SampleDuration("runtime", func() {
//do stuff
}, gmeasure.SamplingConfig{N:100})
})
AfterEach(func() {
if !CurrentSpecReport().State.Is(types.SpecStateSkipped) {
cache.Save(experiment.Name, EXPERIMENT_VERSION, experiment)
}
})
})
*/
func (cache ExperimentCache) Load(name string, version int) *Experiment {
path := filepath.Join(cache.Path, cache.hashOf(name)+CACHE_EXT)
f, err := os.Open(path)
if err != nil {
return nil
}
defer f.Close()
dec := json.NewDecoder(f)
header := CachedExperimentHeader{}
dec.Decode(&header)
if header.Version < version {
return nil
}
out := NewExperiment("")
err = dec.Decode(out)
if err != nil {
return nil
}
return out
}
/*
Save stores the passed-in experiment to the cache with the passed-in name and version.
*/
func (cache ExperimentCache) Save(name string, version int, experiment *Experiment) error {
path := filepath.Join(cache.Path, cache.hashOf(name)+CACHE_EXT)
f, err := os.Create(path)
if err != nil {
return err
}
defer f.Close()
enc := json.NewEncoder(f)
err = enc.Encode(CachedExperimentHeader{
Name: name,
Version: version,
})
if err != nil {
return err
}
return enc.Encode(experiment)
}
/*
Delete removes the experiment with the passed-in name from the cache
*/
func (cache ExperimentCache) Delete(name string) error {
path := filepath.Join(cache.Path, cache.hashOf(name)+CACHE_EXT)
return os.Remove(path)
}
golang-gomega-1.27.10/gmeasure/cache_test.go 0000664 0000000 0000000 00000005525 14462163431 0020642 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"fmt"
"os"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gmeasure"
)
var _ = Describe("Cache", func() {
var path string
var cache gmeasure.ExperimentCache
var e1, e2 *gmeasure.Experiment
BeforeEach(func() {
var err error
path = fmt.Sprintf("./cache-%d", GinkgoParallelProcess())
cache, err = gmeasure.NewExperimentCache(path)
Ω(err).ShouldNot(HaveOccurred())
e1 = gmeasure.NewExperiment("Experiment-1")
e1.RecordValue("foo", 32)
e2 = gmeasure.NewExperiment("Experiment-2")
e2.RecordValue("bar", 64)
})
AfterEach(func() {
Ω(os.RemoveAll(path)).Should(Succeed())
})
Describe("when creating a cache that points to a file", func() {
It("errors", func() {
f, err := os.Create("cache-temp-file")
Ω(err).ShouldNot(HaveOccurred())
f.Close()
cache, err := gmeasure.NewExperimentCache("cache-temp-file")
Ω(err).Should(MatchError("cache-temp-file is not a directory"))
Ω(cache).Should(BeZero())
Ω(os.RemoveAll("cache-temp-file")).Should(Succeed())
})
})
Describe("the happy path", func() {
It("can save, load, list, delete, and clear the cache", func() {
Ω(cache.Save("e1", 1, e1)).Should(Succeed())
Ω(cache.Save("e2", 7, e2)).Should(Succeed())
Ω(cache.Load("e1", 1)).Should(Equal(e1))
Ω(cache.Load("e2", 7)).Should(Equal(e2))
Ω(cache.List()).Should(ConsistOf(
gmeasure.CachedExperimentHeader{"e1", 1},
gmeasure.CachedExperimentHeader{"e2", 7},
))
Ω(cache.Delete("e2")).Should(Succeed())
Ω(cache.Load("e1", 1)).Should(Equal(e1))
Ω(cache.Load("e2", 7)).Should(BeNil())
Ω(cache.List()).Should(ConsistOf(
gmeasure.CachedExperimentHeader{"e1", 1},
))
Ω(cache.Clear()).Should(Succeed())
Ω(cache.List()).Should(BeEmpty())
Ω(cache.Load("e1", 1)).Should(BeNil())
Ω(cache.Load("e2", 7)).Should(BeNil())
})
})
Context("with an empty cache", func() {
It("should list nothing", func() {
Ω(cache.List()).Should(BeEmpty())
})
It("should not error when clearing", func() {
Ω(cache.Clear()).Should(Succeed())
})
It("returs nil when loading a non-existing experiment", func() {
Ω(cache.Load("floop", 17)).Should(BeNil())
})
})
Describe("version management", func() {
BeforeEach(func() {
Ω(cache.Save("e1", 7, e1)).Should(Succeed())
})
Context("when the cached version is older than the requested version", func() {
It("returns nil", func() {
Ω(cache.Load("e1", 8)).Should(BeNil())
})
})
Context("when the cached version equals the requested version", func() {
It("returns the cached version", func() {
Ω(cache.Load("e1", 7)).Should(Equal(e1))
})
})
Context("when the cached version is newer than the requested version", func() {
It("returns the cached version", func() {
Ω(cache.Load("e1", 6)).Should(Equal(e1))
})
})
})
})
golang-gomega-1.27.10/gmeasure/enum_support.go 0000664 0000000 0000000 00000001636 14462163431 0021277 0 ustar 00root root 0000000 0000000 package gmeasure
import "encoding/json"
type enumSupport struct {
toString map[uint]string
toEnum map[string]uint
maxEnum uint
}
func newEnumSupport(toString map[uint]string) enumSupport {
toEnum, maxEnum := map[string]uint{}, uint(0)
for k, v := range toString {
toEnum[v] = k
if maxEnum < k {
maxEnum = k
}
}
return enumSupport{toString: toString, toEnum: toEnum, maxEnum: maxEnum}
}
func (es enumSupport) String(e uint) string {
if e > es.maxEnum {
return es.toString[0]
}
return es.toString[e]
}
func (es enumSupport) UnmarshJSON(b []byte) (uint, error) {
var dec string
if err := json.Unmarshal(b, &dec); err != nil {
return 0, err
}
out := es.toEnum[dec] // if we miss we get 0 which is what we want anyway
return out, nil
}
func (es enumSupport) MarshJSON(e uint) ([]byte, error) {
if e == 0 || e > es.maxEnum {
return json.Marshal(nil)
}
return json.Marshal(es.toString[e])
}
golang-gomega-1.27.10/gmeasure/experiment.go 0000664 0000000 0000000 00000053127 14462163431 0020721 0 ustar 00root root 0000000 0000000 /*
Package gomega/gmeasure provides support for benchmarking and measuring code. It is intended as a more robust replacement for Ginkgo V1's Measure nodes.
gmeasure is organized around the metaphor of an Experiment that can record multiple Measurements. A Measurement is a named collection of data points and gmeasure supports
measuring Values (of type float64) and Durations (of type time.Duration).
Experiments allows the user to record Measurements directly by passing in Values (i.e. float64) or Durations (i.e. time.Duration)
or to measure measurements by passing in functions to measure. When measuring functions Experiments take care of timing the duration of functions (for Duration measurements)
and/or recording returned values (for Value measurements). Experiments also support sampling functions - when told to sample Experiments will run functions repeatedly
and measure and record results. The sampling behavior is configured by passing in a SamplingConfig that can control the maximum number of samples, the maximum duration for sampling (or both)
and the number of concurrent samples to take.
Measurements can be decorated with additional information. This is supported by passing in special typed decorators when recording measurements. These include:
- Units("any string") - to attach units to a Value Measurement (Duration Measurements always have units of "duration")
- Style("any Ginkgo color style string") - to attach styling to a Measurement. This styling is used when rendering console information about the measurement in reports. Color style strings are documented at TODO.
- Precision(integer or time.Duration) - to attach precision to a Measurement. This controls how many decimal places to show for Value Measurements and how to round Duration Measurements when rendering them to screen.
In addition, individual data points in a Measurement can be annotated with an Annotation("any string"). The annotation is associated with the individual data point and is intended to convey additional context about the data point.
Once measurements are complete, an Experiment can generate a comprehensive report by calling its String() or ColorableString() method.
Users can also access and analyze the resulting Measurements directly. Use Experiment.Get(NAME) to fetch the Measurement named NAME. This returned struct will have fields containing
all the data points and annotations recorded by the experiment. You can subsequently fetch the Measurement.Stats() to get a Stats struct that contains basic statistical information about the
Measurement (min, max, median, mean, standard deviation). You can order these Stats objects using RankStats() to identify best/worst performers across multpile experiments or measurements.
gmeasure also supports caching Experiments via an ExperimentCache. The cache supports storing and retreiving experiments by name and version. This allows you to rerun code without
repeating expensive experiments that may not have changed (which can be controlled by the cache version number). It also enables you to compare new experiment runs with older runs to detect
variations in performance/behavior.
When used with Ginkgo, you can emit experiment reports and encode them in test reports easily using Ginkgo V2's support for Report Entries.
Simply pass your experiment to AddReportEntry to get a report every time the tests run. You can also use AddReportEntry with Measurements to emit all the captured data
and Rankings to emit measurement summaries in rank order.
Finally, Experiments provide an additional mechanism to measure durations called a Stopwatch. The Stopwatch makes it easy to pepper code with statements that measure elapsed time across
different sections of code and can be useful when debugging or evaluating bottlenecks in a given codepath.
*/
package gmeasure
import (
"fmt"
"math"
"reflect"
"sync"
"time"
"github.com/onsi/gomega/gmeasure/table"
)
/*
SamplingConfig configures the Sample family of experiment methods.
These methods invoke passed-in functions repeatedly to sample and record a given measurement.
SamplingConfig is used to control the maximum number of samples or time spent sampling (or both). When both are specified sampling ends as soon as one of the conditions is met.
SamplingConfig can also ensure a minimum interval between samples and can enable concurrent sampling.
*/
type SamplingConfig struct {
// N - the maximum number of samples to record
N int
// Duration - the maximum amount of time to spend recording samples
Duration time.Duration
// MinSamplingInterval - the minimum time that must elapse between samplings. It is an error to specify both MinSamplingInterval and NumParallel.
MinSamplingInterval time.Duration
// NumParallel - the number of parallel workers to spin up to record samples. It is an error to specify both MinSamplingInterval and NumParallel.
NumParallel int
}
// The Units decorator allows you to specify units (an arbitrary string) when recording values. It is ignored when recording durations.
//
// e := gmeasure.NewExperiment("My Experiment")
// e.RecordValue("length", 3.141, gmeasure.Units("inches"))
//
// Units are only set the first time a value of a given name is recorded. In the example above any subsequent calls to e.RecordValue("length", X) will maintain the "inches" units even if a new set of Units("UNIT") are passed in later.
type Units string
// The Annotation decorator allows you to attach an annotation to a given recorded data-point:
//
// For example:
//
// e := gmeasure.NewExperiment("My Experiment")
// e.RecordValue("length", 3.141, gmeasure.Annotation("bob"))
// e.RecordValue("length", 2.71, gmeasure.Annotation("jane"))
//
// ...will result in a Measurement named "length" that records two values )[3.141, 2.71]) annotation with (["bob", "jane"])
type Annotation string
// The Style decorator allows you to associate a style with a measurement. This is used to generate colorful console reports using Ginkgo V2's
// console formatter. Styles are strings in curly brackets that correspond to a color or style.
//
// For example:
//
// e := gmeasure.NewExperiment("My Experiment")
// e.RecordValue("length", 3.141, gmeasure.Style("{{blue}}{{bold}}"))
// e.RecordValue("length", 2.71)
// e.RecordDuration("cooking time", 3 * time.Second, gmeasure.Style("{{red}}{{underline}}"))
// e.RecordDuration("cooking time", 2 * time.Second)
//
// will emit a report with blue bold entries for the length measurement and red underlined entries for the cooking time measurement.
//
// Units are only set the first time a value or duration of a given name is recorded. In the example above any subsequent calls to e.RecordValue("length", X) will maintain the "{{blue}}{{bold}}" style even if a new Style is passed in later.
type Style string
// The PrecisionBundle decorator controls the rounding of value and duration measurements. See Precision().
type PrecisionBundle struct {
Duration time.Duration
ValueFormat string
}
// Precision() allows you to specify the precision of a value or duration measurement - this precision is used when rendering the measurement to screen.
//
// To control the precision of Value measurements, pass Precision an integer. This will denote the number of decimal places to render (equivalen to the format string "%.Nf")
// To control the precision of Duration measurements, pass Precision a time.Duration. Duration measurements will be rounded oo the nearest time.Duration when rendered.
//
// For example:
//
// e := gmeasure.NewExperiment("My Experiment")
// e.RecordValue("length", 3.141, gmeasure.Precision(2))
// e.RecordValue("length", 2.71)
// e.RecordDuration("cooking time", 3214 * time.Millisecond, gmeasure.Precision(100*time.Millisecond))
// e.RecordDuration("cooking time", 2623 * time.Millisecond)
func Precision(p interface{}) PrecisionBundle {
out := DefaultPrecisionBundle
switch reflect.TypeOf(p) {
case reflect.TypeOf(time.Duration(0)):
out.Duration = p.(time.Duration)
case reflect.TypeOf(int(0)):
out.ValueFormat = fmt.Sprintf("%%.%df", p.(int))
default:
panic("invalid precision type, must be time.Duration or int")
}
return out
}
// DefaultPrecisionBundle captures the default precisions for Vale and Duration measurements.
var DefaultPrecisionBundle = PrecisionBundle{
Duration: 100 * time.Microsecond,
ValueFormat: "%.3f",
}
type extractedDecorations struct {
annotation Annotation
units Units
precisionBundle PrecisionBundle
style Style
}
func extractDecorations(args []interface{}) extractedDecorations {
var out extractedDecorations
out.precisionBundle = DefaultPrecisionBundle
for _, arg := range args {
switch reflect.TypeOf(arg) {
case reflect.TypeOf(out.annotation):
out.annotation = arg.(Annotation)
case reflect.TypeOf(out.units):
out.units = arg.(Units)
case reflect.TypeOf(out.precisionBundle):
out.precisionBundle = arg.(PrecisionBundle)
case reflect.TypeOf(out.style):
out.style = arg.(Style)
default:
panic(fmt.Sprintf("unrecognized argument %#v", arg))
}
}
return out
}
/*
Experiment is gmeasure's core data type. You use experiments to record Measurements and generate reports.
Experiments are thread-safe and all methods can be called from multiple goroutines.
*/
type Experiment struct {
Name string
// Measurements includes all Measurements recorded by this experiment. You should access them by name via Get() and GetStats()
Measurements Measurements
lock *sync.Mutex
}
/*
NexExperiment creates a new experiment with the passed-in name.
When using Ginkgo we recommend immediately registering the experiment as a ReportEntry:
experiment = NewExperiment("My Experiment")
AddReportEntry(experiment.Name, experiment)
this will ensure an experiment report is emitted as part of the test output and exported with any test reports.
*/
func NewExperiment(name string) *Experiment {
experiment := &Experiment{
Name: name,
lock: &sync.Mutex{},
}
return experiment
}
func (e *Experiment) report(enableStyling bool) string {
t := table.NewTable()
t.TableStyle.EnableTextStyling = enableStyling
t.AppendRow(table.R(
table.C("Name"), table.C("N"), table.C("Min"), table.C("Median"), table.C("Mean"), table.C("StdDev"), table.C("Max"),
table.Divider("="),
"{{bold}}",
))
for _, measurement := range e.Measurements {
r := table.R(measurement.Style)
t.AppendRow(r)
switch measurement.Type {
case MeasurementTypeNote:
r.AppendCell(table.C(measurement.Note))
case MeasurementTypeValue, MeasurementTypeDuration:
name := measurement.Name
if measurement.Units != "" {
name += " [" + measurement.Units + "]"
}
r.AppendCell(table.C(name))
r.AppendCell(measurement.Stats().cells()...)
}
}
out := e.Name + "\n"
if enableStyling {
out = "{{bold}}" + out + "{{/}}"
}
out += t.Render()
return out
}
/*
ColorableString returns a Ginkgo formatted summary of the experiment and all its Measurements.
It is called automatically by Ginkgo's reporting infrastructure when the Experiment is registered as a ReportEntry via AddReportEntry.
*/
func (e *Experiment) ColorableString() string {
return e.report(true)
}
/*
ColorableString returns an unformatted summary of the experiment and all its Measurements.
*/
func (e *Experiment) String() string {
return e.report(false)
}
/*
RecordNote records a Measurement of type MeasurementTypeNote - this is simply a textual note to annotate the experiment. It will be emitted in any experiment reports.
RecordNote supports the Style() decoration.
*/
func (e *Experiment) RecordNote(note string, args ...interface{}) {
decorations := extractDecorations(args)
e.lock.Lock()
defer e.lock.Unlock()
e.Measurements = append(e.Measurements, Measurement{
ExperimentName: e.Name,
Type: MeasurementTypeNote,
Note: note,
Style: string(decorations.style),
})
}
/*
RecordDuration records the passed-in duration on a Duration Measurement with the passed-in name. If the Measurement does not exist it is created.
RecordDuration supports the Style(), Precision(), and Annotation() decorations.
*/
func (e *Experiment) RecordDuration(name string, duration time.Duration, args ...interface{}) {
decorations := extractDecorations(args)
e.recordDuration(name, duration, decorations)
}
/*
MeasureDuration runs the passed-in callback and times how long it takes to complete. The resulting duration is recorded on a Duration Measurement with the passed-in name. If the Measurement does not exist it is created.
MeasureDuration supports the Style(), Precision(), and Annotation() decorations.
*/
func (e *Experiment) MeasureDuration(name string, callback func(), args ...interface{}) time.Duration {
t := time.Now()
callback()
duration := time.Since(t)
e.RecordDuration(name, duration, args...)
return duration
}
/*
SampleDuration samples the passed-in callback and times how long it takes to complete each sample.
The resulting durations are recorded on a Duration Measurement with the passed-in name. If the Measurement does not exist it is created.
The callback is given a zero-based index that increments by one between samples. The Sampling is configured via the passed-in SamplingConfig
SampleDuration supports the Style(), Precision(), and Annotation() decorations. When passed an Annotation() the same annotation is applied to all sample measurements.
*/
func (e *Experiment) SampleDuration(name string, callback func(idx int), samplingConfig SamplingConfig, args ...interface{}) {
decorations := extractDecorations(args)
e.Sample(func(idx int) {
t := time.Now()
callback(idx)
duration := time.Since(t)
e.recordDuration(name, duration, decorations)
}, samplingConfig)
}
/*
SampleDuration samples the passed-in callback and times how long it takes to complete each sample.
The resulting durations are recorded on a Duration Measurement with the passed-in name. If the Measurement does not exist it is created.
The callback is given a zero-based index that increments by one between samples. The callback must return an Annotation - this annotation is attached to the measured duration.
The Sampling is configured via the passed-in SamplingConfig
SampleAnnotatedDuration supports the Style() and Precision() decorations.
*/
func (e *Experiment) SampleAnnotatedDuration(name string, callback func(idx int) Annotation, samplingConfig SamplingConfig, args ...interface{}) {
decorations := extractDecorations(args)
e.Sample(func(idx int) {
t := time.Now()
decorations.annotation = callback(idx)
duration := time.Since(t)
e.recordDuration(name, duration, decorations)
}, samplingConfig)
}
func (e *Experiment) recordDuration(name string, duration time.Duration, decorations extractedDecorations) {
e.lock.Lock()
defer e.lock.Unlock()
idx := e.Measurements.IdxWithName(name)
if idx == -1 {
measurement := Measurement{
ExperimentName: e.Name,
Type: MeasurementTypeDuration,
Name: name,
Units: "duration",
Durations: []time.Duration{duration},
PrecisionBundle: decorations.precisionBundle,
Style: string(decorations.style),
Annotations: []string{string(decorations.annotation)},
}
e.Measurements = append(e.Measurements, measurement)
} else {
if e.Measurements[idx].Type != MeasurementTypeDuration {
panic(fmt.Sprintf("attempting to record duration with name '%s'. That name is already in-use for recording values.", name))
}
e.Measurements[idx].Durations = append(e.Measurements[idx].Durations, duration)
e.Measurements[idx].Annotations = append(e.Measurements[idx].Annotations, string(decorations.annotation))
}
}
/*
NewStopwatch() returns a stopwatch configured to record duration measurements with this experiment.
*/
func (e *Experiment) NewStopwatch() *Stopwatch {
return newStopwatch(e)
}
/*
RecordValue records the passed-in value on a Value Measurement with the passed-in name. If the Measurement does not exist it is created.
RecordValue supports the Style(), Units(), Precision(), and Annotation() decorations.
*/
func (e *Experiment) RecordValue(name string, value float64, args ...interface{}) {
decorations := extractDecorations(args)
e.recordValue(name, value, decorations)
}
/*
MeasureValue runs the passed-in callback and records the return value on a Value Measurement with the passed-in name. If the Measurement does not exist it is created.
MeasureValue supports the Style(), Units(), Precision(), and Annotation() decorations.
*/
func (e *Experiment) MeasureValue(name string, callback func() float64, args ...interface{}) float64 {
value := callback()
e.RecordValue(name, value, args...)
return value
}
/*
SampleValue samples the passed-in callback and records the return value on a Value Measurement with the passed-in name. If the Measurement does not exist it is created.
The callback is given a zero-based index that increments by one between samples. The callback must return a float64. The Sampling is configured via the passed-in SamplingConfig
SampleValue supports the Style(), Units(), Precision(), and Annotation() decorations. When passed an Annotation() the same annotation is applied to all sample measurements.
*/
func (e *Experiment) SampleValue(name string, callback func(idx int) float64, samplingConfig SamplingConfig, args ...interface{}) {
decorations := extractDecorations(args)
e.Sample(func(idx int) {
value := callback(idx)
e.recordValue(name, value, decorations)
}, samplingConfig)
}
/*
SampleAnnotatedValue samples the passed-in callback and records the return value on a Value Measurement with the passed-in name. If the Measurement does not exist it is created.
The callback is given a zero-based index that increments by one between samples. The callback must return a float64 and an Annotation - the annotation is attached to the recorded value.
The Sampling is configured via the passed-in SamplingConfig
SampleValue supports the Style(), Units(), and Precision() decorations.
*/
func (e *Experiment) SampleAnnotatedValue(name string, callback func(idx int) (float64, Annotation), samplingConfig SamplingConfig, args ...interface{}) {
decorations := extractDecorations(args)
e.Sample(func(idx int) {
var value float64
value, decorations.annotation = callback(idx)
e.recordValue(name, value, decorations)
}, samplingConfig)
}
func (e *Experiment) recordValue(name string, value float64, decorations extractedDecorations) {
e.lock.Lock()
defer e.lock.Unlock()
idx := e.Measurements.IdxWithName(name)
if idx == -1 {
measurement := Measurement{
ExperimentName: e.Name,
Type: MeasurementTypeValue,
Name: name,
Style: string(decorations.style),
Units: string(decorations.units),
PrecisionBundle: decorations.precisionBundle,
Values: []float64{value},
Annotations: []string{string(decorations.annotation)},
}
e.Measurements = append(e.Measurements, measurement)
} else {
if e.Measurements[idx].Type != MeasurementTypeValue {
panic(fmt.Sprintf("attempting to record value with name '%s'. That name is already in-use for recording durations.", name))
}
e.Measurements[idx].Values = append(e.Measurements[idx].Values, value)
e.Measurements[idx].Annotations = append(e.Measurements[idx].Annotations, string(decorations.annotation))
}
}
/*
Sample samples the passed-in callback repeatedly. The sampling is governed by the passed in SamplingConfig.
The SamplingConfig can limit the total number of samples and/or the total time spent sampling the callback.
The SamplingConfig can also instruct Sample to run with multiple concurrent workers.
The callback is called with a zero-based index that incerements by one between samples.
*/
func (e *Experiment) Sample(callback func(idx int), samplingConfig SamplingConfig) {
if samplingConfig.N == 0 && samplingConfig.Duration == 0 {
panic("you must specify at least one of SamplingConfig.N and SamplingConfig.Duration")
}
if samplingConfig.MinSamplingInterval > 0 && samplingConfig.NumParallel > 1 {
panic("you cannot specify both SamplingConfig.MinSamplingInterval and SamplingConfig.NumParallel")
}
maxTime := time.Now().Add(100000 * time.Hour)
if samplingConfig.Duration > 0 {
maxTime = time.Now().Add(samplingConfig.Duration)
}
maxN := math.MaxInt32
if samplingConfig.N > 0 {
maxN = samplingConfig.N
}
numParallel := 1
if samplingConfig.NumParallel > numParallel {
numParallel = samplingConfig.NumParallel
}
minSamplingInterval := samplingConfig.MinSamplingInterval
work := make(chan int)
defer close(work)
if numParallel > 1 {
for worker := 0; worker < numParallel; worker++ {
go func() {
for idx := range work {
callback(idx)
}
}()
}
}
idx := 0
var avgDt time.Duration
for {
t := time.Now()
if numParallel > 1 {
work <- idx
} else {
callback(idx)
}
dt := time.Since(t)
if numParallel == 1 && dt < minSamplingInterval {
time.Sleep(minSamplingInterval - dt)
dt = time.Since(t)
}
if idx >= numParallel {
avgDt = (avgDt*time.Duration(idx-numParallel) + dt) / time.Duration(idx-numParallel+1)
}
idx += 1
if idx >= maxN {
return
}
if time.Now().Add(avgDt).After(maxTime) {
return
}
}
}
/*
Get returns the Measurement with the associated name. If no Measurement is found a zero Measurement{} is returned.
*/
func (e *Experiment) Get(name string) Measurement {
e.lock.Lock()
defer e.lock.Unlock()
idx := e.Measurements.IdxWithName(name)
if idx == -1 {
return Measurement{}
}
return e.Measurements[idx]
}
/*
GetStats returns the Stats for the Measurement with the associated name. If no Measurement is found a zero Stats{} is returned.
experiment.GetStats(name) is equivalent to experiment.Get(name).Stats()
*/
func (e *Experiment) GetStats(name string) Stats {
measurement := e.Get(name)
e.lock.Lock()
defer e.lock.Unlock()
return measurement.Stats()
}
golang-gomega-1.27.10/gmeasure/experiment_test.go 0000664 0000000 0000000 00000041204 14462163431 0021751 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"fmt"
"strings"
"sync"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gmeasure"
)
var _ = Describe("Experiment", func() {
var e *gmeasure.Experiment
BeforeEach(func() {
e = gmeasure.NewExperiment("Test Experiment")
})
Describe("Recording Notes", func() {
It("creates a note Measurement", func() {
e.RecordNote("I'm a note", gmeasure.Style("{{blue}}"))
measurement := e.Measurements[0]
Ω(measurement.Type).Should(Equal(gmeasure.MeasurementTypeNote))
Ω(measurement.ExperimentName).Should(Equal("Test Experiment"))
Ω(measurement.Note).Should(Equal("I'm a note"))
Ω(measurement.Style).Should(Equal("{{blue}}"))
})
})
Describe("Recording Durations", func() {
commonMeasurementAssertions := func() gmeasure.Measurement {
measurement := e.Get("runtime")
Ω(measurement.Type).Should(Equal(gmeasure.MeasurementTypeDuration))
Ω(measurement.ExperimentName).Should(Equal("Test Experiment"))
Ω(measurement.Name).Should(Equal("runtime"))
Ω(measurement.Units).Should(Equal("duration"))
Ω(measurement.Style).Should(Equal("{{red}}"))
Ω(measurement.PrecisionBundle.Duration).Should(Equal(time.Millisecond))
return measurement
}
BeforeEach(func() {
e.RecordDuration("runtime", time.Second, gmeasure.Annotation("first"), gmeasure.Style("{{red}}"), gmeasure.Precision(time.Millisecond), gmeasure.Units("ignored"))
})
Describe("RecordDuration", func() {
It("generates a measurement and records the passed-in duration along with any relevant decorations", func() {
e.RecordDuration("runtime", time.Minute, gmeasure.Annotation("second"))
measurement := commonMeasurementAssertions()
Ω(measurement.Durations).Should(Equal([]time.Duration{time.Second, time.Minute}))
Ω(measurement.Annotations).Should(Equal([]string{"first", "second"}))
})
})
Describe("MeasureDuration", func() {
It("measure the duration of the passed-in function", func() {
e.MeasureDuration("runtime", func() {
time.Sleep(200 * time.Millisecond)
}, gmeasure.Annotation("second"))
measurement := commonMeasurementAssertions()
Ω(measurement.Durations[0]).Should(Equal(time.Second))
Ω(measurement.Durations[1]).Should(BeNumerically("~", 200*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Annotations).Should(Equal([]string{"first", "second"}))
})
})
Describe("SampleDuration", func() {
It("samples the passed-in function according to SampleConfig and records the measured durations", func() {
e.SampleDuration("runtime", func(_ int) {
time.Sleep(100 * time.Millisecond)
}, gmeasure.SamplingConfig{N: 3}, gmeasure.Annotation("sampled"))
measurement := commonMeasurementAssertions()
Ω(measurement.Durations[0]).Should(Equal(time.Second))
Ω(measurement.Durations[1]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Durations[2]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Durations[3]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Annotations).Should(Equal([]string{"first", "sampled", "sampled", "sampled"}))
})
})
Describe("SampleAnnotatedDuration", func() {
It("samples the passed-in function according to SampleConfig and records the measured durations and returned annotations", func() {
e.SampleAnnotatedDuration("runtime", func(idx int) gmeasure.Annotation {
time.Sleep(100 * time.Millisecond)
return gmeasure.Annotation(fmt.Sprintf("sampled-%d", idx+1))
}, gmeasure.SamplingConfig{N: 3}, gmeasure.Annotation("ignored"))
measurement := commonMeasurementAssertions()
Ω(measurement.Durations[0]).Should(Equal(time.Second))
Ω(measurement.Durations[1]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Durations[2]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Durations[3]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Annotations).Should(Equal([]string{"first", "sampled-1", "sampled-2", "sampled-3"}))
})
})
})
Describe("Stopwatch Support", func() {
It("can generate a new stopwatch tied to the experiment", func() {
s := e.NewStopwatch()
time.Sleep(50 * time.Millisecond)
s.Record("runtime", gmeasure.Annotation("first")).Reset()
time.Sleep(100 * time.Millisecond)
s.Record("runtime", gmeasure.Annotation("second")).Reset()
time.Sleep(150 * time.Millisecond)
s.Record("runtime", gmeasure.Annotation("third"))
measurement := e.Get("runtime")
Ω(measurement.Durations[0]).Should(BeNumerically("~", 50*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Durations[1]).Should(BeNumerically("~", 100*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Durations[2]).Should(BeNumerically("~", 150*time.Millisecond, 20*time.Millisecond))
Ω(measurement.Annotations).Should(Equal([]string{"first", "second", "third"}))
})
})
Describe("Recording Values", func() {
commonMeasurementAssertions := func() gmeasure.Measurement {
measurement := e.Get("sprockets")
Ω(measurement.Type).Should(Equal(gmeasure.MeasurementTypeValue))
Ω(measurement.ExperimentName).Should(Equal("Test Experiment"))
Ω(measurement.Name).Should(Equal("sprockets"))
Ω(measurement.Units).Should(Equal("widgets"))
Ω(measurement.Style).Should(Equal("{{yellow}}"))
Ω(measurement.PrecisionBundle.ValueFormat).Should(Equal("%.0f"))
return measurement
}
BeforeEach(func() {
e.RecordValue("sprockets", 3.2, gmeasure.Annotation("first"), gmeasure.Style("{{yellow}}"), gmeasure.Precision(0), gmeasure.Units("widgets"))
})
Describe("RecordValue", func() {
It("generates a measurement and records the passed-in value along with any relevant decorations", func() {
e.RecordValue("sprockets", 17.4, gmeasure.Annotation("second"))
measurement := commonMeasurementAssertions()
Ω(measurement.Values).Should(Equal([]float64{3.2, 17.4}))
Ω(measurement.Annotations).Should(Equal([]string{"first", "second"}))
})
})
Describe("MeasureValue", func() {
It("records the value returned by the passed-in function", func() {
e.MeasureValue("sprockets", func() float64 {
return 17.4
}, gmeasure.Annotation("second"))
measurement := commonMeasurementAssertions()
Ω(measurement.Values).Should(Equal([]float64{3.2, 17.4}))
Ω(measurement.Annotations).Should(Equal([]string{"first", "second"}))
})
})
Describe("SampleValue", func() {
It("samples the passed-in function according to SampleConfig and records the resulting values", func() {
e.SampleValue("sprockets", func(idx int) float64 {
return 17.4 + float64(idx)
}, gmeasure.SamplingConfig{N: 3}, gmeasure.Annotation("sampled"))
measurement := commonMeasurementAssertions()
Ω(measurement.Values).Should(Equal([]float64{3.2, 17.4, 18.4, 19.4}))
Ω(measurement.Annotations).Should(Equal([]string{"first", "sampled", "sampled", "sampled"}))
})
})
Describe("SampleAnnotatedValue", func() {
It("samples the passed-in function according to SampleConfig and records the returned values and annotations", func() {
e.SampleAnnotatedValue("sprockets", func(idx int) (float64, gmeasure.Annotation) {
return 17.4 + float64(idx), gmeasure.Annotation(fmt.Sprintf("sampled-%d", idx+1))
}, gmeasure.SamplingConfig{N: 3}, gmeasure.Annotation("ignored"))
measurement := commonMeasurementAssertions()
Ω(measurement.Values).Should(Equal([]float64{3.2, 17.4, 18.4, 19.4}))
Ω(measurement.Annotations).Should(Equal([]string{"first", "sampled-1", "sampled-2", "sampled-3"}))
})
})
})
Describe("Sampling", func() {
var indices []int
BeforeEach(func() {
indices = []int{}
})
ints := func(n int) []int {
out := []int{}
for i := 0; i < n; i++ {
out = append(out, i)
}
return out
}
It("calls the function repeatedly passing in an index", func() {
e.Sample(func(idx int) {
indices = append(indices, idx)
}, gmeasure.SamplingConfig{N: 3})
Ω(indices).Should(Equal(ints(3)))
})
It("can cap the maximum number of samples", func() {
e.Sample(func(idx int) {
indices = append(indices, idx)
}, gmeasure.SamplingConfig{N: 10, Duration: time.Minute})
Ω(indices).Should(Equal(ints(10)))
})
It("can cap the maximum sample time", func() {
e.Sample(func(idx int) {
indices = append(indices, idx)
time.Sleep(10 * time.Millisecond)
}, gmeasure.SamplingConfig{N: 100, Duration: 100 * time.Millisecond, MinSamplingInterval: 5 * time.Millisecond})
Ω(len(indices)).Should(BeNumerically("~", 10, 3))
Ω(indices).Should(Equal(ints(len(indices))))
})
It("can ensure a minimum interval between samples", func() {
times := map[int]time.Time{}
e.Sample(func(idx int) {
times[idx] = time.Now()
}, gmeasure.SamplingConfig{N: 10, Duration: 200 * time.Millisecond, MinSamplingInterval: 50 * time.Millisecond, NumParallel: 1})
Ω(len(times)).Should(BeNumerically("~", 4, 2))
Ω(times[1]).Should(BeTemporally(">", times[0], 50*time.Millisecond))
Ω(times[2]).Should(BeTemporally(">", times[1], 50*time.Millisecond))
})
It("can run samples in parallel", func() {
lock := &sync.Mutex{}
e.Sample(func(idx int) {
lock.Lock()
indices = append(indices, idx)
lock.Unlock()
time.Sleep(10 * time.Millisecond)
}, gmeasure.SamplingConfig{N: 100, Duration: 100 * time.Millisecond, NumParallel: 3})
lock.Lock()
defer lock.Unlock()
Ω(len(indices)).Should(BeNumerically("~", 30, 10))
Ω(indices).Should(ConsistOf(ints(len(indices))))
})
It("panics if the SamplingConfig does not specify a ceiling", func() {
Expect(func() {
e.Sample(func(_ int) {}, gmeasure.SamplingConfig{MinSamplingInterval: time.Second})
}).To(PanicWith("you must specify at least one of SamplingConfig.N and SamplingConfig.Duration"))
})
It("panics if the SamplingConfig includes both a minimum interval and a directive to run in parallel", func() {
Expect(func() {
e.Sample(func(_ int) {}, gmeasure.SamplingConfig{N: 10, MinSamplingInterval: time.Second, NumParallel: 2})
}).To(PanicWith("you cannot specify both SamplingConfig.MinSamplingInterval and SamplingConfig.NumParallel"))
})
})
Describe("recording multiple entries", func() {
It("always appends to the correct measurement (by name)", func() {
e.RecordDuration("alpha", time.Second)
e.RecordDuration("beta", time.Minute)
e.RecordValue("gamma", 1)
e.RecordValue("delta", 2.71)
e.RecordDuration("alpha", 2*time.Second)
e.RecordDuration("beta", 2*time.Minute)
e.RecordValue("gamma", 2)
e.RecordValue("delta", 3.141)
Ω(e.Measurements).Should(HaveLen(4))
Ω(e.Get("alpha").Durations).Should(Equal([]time.Duration{time.Second, 2 * time.Second}))
Ω(e.Get("beta").Durations).Should(Equal([]time.Duration{time.Minute, 2 * time.Minute}))
Ω(e.Get("gamma").Values).Should(Equal([]float64{1, 2}))
Ω(e.Get("delta").Values).Should(Equal([]float64{2.71, 3.141}))
})
It("panics if you incorrectly mix types", func() {
e.RecordDuration("runtime", time.Second)
Ω(func() {
e.RecordValue("runtime", 3.141)
}).Should(PanicWith("attempting to record value with name 'runtime'. That name is already in-use for recording durations."))
e.RecordValue("sprockets", 2)
Ω(func() {
e.RecordDuration("sprockets", time.Minute)
}).Should(PanicWith("attempting to record duration with name 'sprockets'. That name is already in-use for recording values."))
})
})
Describe("Decorators", func() {
It("uses the default precisions when none is specified", func() {
e.RecordValue("sprockets", 2)
e.RecordDuration("runtime", time.Minute)
Ω(e.Get("sprockets").PrecisionBundle.ValueFormat).Should(Equal("%.3f"))
Ω(e.Get("runtime").PrecisionBundle.Duration).Should(Equal(100 * time.Microsecond))
})
It("panics if an unsupported type is passed into Precision", func() {
Ω(func() {
gmeasure.Precision("aardvark")
}).Should(PanicWith("invalid precision type, must be time.Duration or int"))
})
It("panics if an unrecognized argumnet is passed in", func() {
Ω(func() {
e.RecordValue("sprockets", 2, "boom")
}).Should(PanicWith(`unrecognized argument "boom"`))
})
})
Describe("Getting Measurements", func() {
Context("when the Measurement does not exist", func() {
It("returns the zero Measurement", func() {
Ω(e.Get("not here")).Should(BeZero())
})
})
})
Describe("Getting Stats", func() {
It("returns the Measurement's Stats", func() {
e.RecordValue("alpha", 1)
e.RecordValue("alpha", 2)
e.RecordValue("alpha", 3)
Ω(e.GetStats("alpha")).Should(Equal(e.Get("alpha").Stats()))
})
})
Describe("Generating Reports", func() {
BeforeEach(func() {
e.RecordNote("A note")
e.RecordValue("sprockets", 7, gmeasure.Units("widgets"), gmeasure.Precision(0), gmeasure.Style("{{yellow}}"), gmeasure.Annotation("sprockets-1"))
e.RecordDuration("runtime", time.Second, gmeasure.Precision(100*time.Millisecond), gmeasure.Style("{{red}}"), gmeasure.Annotation("runtime-1"))
e.RecordNote("A blue note", gmeasure.Style("{{blue}}"))
e.RecordValue("gear ratio", 10.3, gmeasure.Precision(2), gmeasure.Style("{{green}}"), gmeasure.Annotation("ratio-1"))
e.RecordValue("sprockets", 8, gmeasure.Annotation("sprockets-2"))
e.RecordValue("sprockets", 9, gmeasure.Annotation("sprockets-3"))
e.RecordDuration("runtime", 2*time.Second, gmeasure.Annotation("runtime-2"))
e.RecordValue("gear ratio", 13.758, gmeasure.Precision(2), gmeasure.Annotation("ratio-2"))
})
It("emits a nicely formatted table", func() {
expected := strings.Join([]string{
"Test Experiment",
"Name | N | Min | Median | Mean | StdDev | Max ",
"=============================================================================",
"A note ",
"-----------------------------------------------------------------------------",
"sprockets [widgets] | 3 | 7 | 8 | 8 | 1 | 9 ",
" | | sprockets-1 | | | | sprockets-3",
"-----------------------------------------------------------------------------",
"runtime [duration] | 2 | 1s | 1.5s | 1.5s | 500ms | 2s ",
" | | runtime-1 | | | | runtime-2 ",
"-----------------------------------------------------------------------------",
"A blue note ",
"-----------------------------------------------------------------------------",
"gear ratio | 2 | 10.30 | 12.03 | 12.03 | 1.73 | 13.76 ",
" | | ratio-1 | | | | ratio-2 ",
"",
}, "\n")
Ω(e.String()).Should(Equal(expected))
})
It("can also emit a styled table", func() {
expected := strings.Join([]string{
"{{bold}}Test Experiment",
"{{/}}{{bold}}Name {{/}} | {{bold}}N{{/}} | {{bold}}Min {{/}} | {{bold}}Median{{/}} | {{bold}}Mean {{/}} | {{bold}}StdDev{{/}} | {{bold}}Max {{/}}",
"=============================================================================",
"A note ",
"-----------------------------------------------------------------------------",
"{{yellow}}sprockets [widgets]{{/}} | {{yellow}}3{{/}} | {{yellow}}7 {{/}} | {{yellow}}8 {{/}} | {{yellow}}8 {{/}} | {{yellow}}1 {{/}} | {{yellow}}9 {{/}}",
" | | {{yellow}}sprockets-1{{/}} | | | | {{yellow}}sprockets-3{{/}}",
"-----------------------------------------------------------------------------",
"{{red}}runtime [duration] {{/}} | {{red}}2{{/}} | {{red}}1s {{/}} | {{red}}1.5s {{/}} | {{red}}1.5s {{/}} | {{red}}500ms {{/}} | {{red}}2s {{/}}",
" | | {{red}}runtime-1 {{/}} | | | | {{red}}runtime-2 {{/}}",
"-----------------------------------------------------------------------------",
"{{blue}}A blue note {{/}}",
"-----------------------------------------------------------------------------",
"{{green}}gear ratio {{/}} | {{green}}2{{/}} | {{green}}10.30 {{/}} | {{green}}12.03 {{/}} | {{green}}12.03{{/}} | {{green}}1.73 {{/}} | {{green}}13.76 {{/}}",
" | | {{green}}ratio-1 {{/}} | | | | {{green}}ratio-2 {{/}}",
"",
}, "\n")
Ω(e.ColorableString()).Should(Equal(expected))
})
})
})
golang-gomega-1.27.10/gmeasure/gmeasure_suite_test.go 0000664 0000000 0000000 00000000572 14462163431 0022615 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"testing"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gleak"
)
func TestGmeasure(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Gmeasure Suite")
}
var _ = BeforeEach(func() {
g := gleak.Goroutines()
DeferCleanup(func() {
Eventually(gleak.Goroutines).ShouldNot(gleak.HaveLeaked(g))
})
})
golang-gomega-1.27.10/gmeasure/measurement.go 0000664 0000000 0000000 00000016667 14462163431 0021076 0 ustar 00root root 0000000 0000000 package gmeasure
import (
"fmt"
"math"
"sort"
"time"
"github.com/onsi/gomega/gmeasure/table"
)
type MeasurementType uint
const (
MeasurementTypeInvalid MeasurementType = iota
MeasurementTypeNote
MeasurementTypeDuration
MeasurementTypeValue
)
var letEnumSupport = newEnumSupport(map[uint]string{uint(MeasurementTypeInvalid): "INVALID LOG ENTRY TYPE", uint(MeasurementTypeNote): "Note", uint(MeasurementTypeDuration): "Duration", uint(MeasurementTypeValue): "Value"})
func (s MeasurementType) String() string { return letEnumSupport.String(uint(s)) }
func (s *MeasurementType) UnmarshalJSON(b []byte) error {
out, err := letEnumSupport.UnmarshJSON(b)
*s = MeasurementType(out)
return err
}
func (s MeasurementType) MarshalJSON() ([]byte, error) { return letEnumSupport.MarshJSON(uint(s)) }
/*
Measurement records all captured data for a given measurement. You generally don't make Measurements directly - but you can fetch them from Experiments using Get().
When using Ginkgo, you can register Measurements as Report Entries via AddReportEntry. This will emit all the captured data points when Ginkgo generates the report.
*/
type Measurement struct {
// Type is the MeasurementType - one of MeasurementTypeNote, MeasurementTypeDuration, or MeasurementTypeValue
Type MeasurementType
// ExperimentName is the name of the experiment that this Measurement is associated with
ExperimentName string
// If Type is MeasurementTypeNote, Note is populated with the note text.
Note string
// If Type is MeasurementTypeDuration or MeasurementTypeValue, Name is the name of the recorded measurement
Name string
// Style captures the styling information (if any) for this Measurement
Style string
// Units capture the units (if any) for this Measurement. Units is set to "duration" if the Type is MeasurementTypeDuration
Units string
// PrecisionBundle captures the precision to use when rendering data for this Measurement.
// If Type is MeasurementTypeDuration then PrecisionBundle.Duration is used to round any durations before presentation.
// If Type is MeasurementTypeValue then PrecisionBundle.ValueFormat is used to format any values before presentation
PrecisionBundle PrecisionBundle
// If Type is MeasurementTypeDuration, Durations will contain all durations recorded for this measurement
Durations []time.Duration
// If Type is MeasurementTypeValue, Values will contain all float64s recorded for this measurement
Values []float64
// If Type is MeasurementTypeDuration or MeasurementTypeValue then Annotations will include string annotations for all recorded Durations or Values.
// If the user does not pass-in an Annotation() decoration for a particular value or duration, the corresponding entry in the Annotations slice will be the empty string ""
Annotations []string
}
type Measurements []Measurement
func (m Measurements) IdxWithName(name string) int {
for idx, measurement := range m {
if measurement.Name == name {
return idx
}
}
return -1
}
func (m Measurement) report(enableStyling bool) string {
out := ""
style := m.Style
if !enableStyling {
style = ""
}
switch m.Type {
case MeasurementTypeNote:
out += fmt.Sprintf("%s - Note\n%s\n", m.ExperimentName, m.Note)
if style != "" {
out = style + out + "{{/}}"
}
return out
case MeasurementTypeValue, MeasurementTypeDuration:
out += fmt.Sprintf("%s - %s", m.ExperimentName, m.Name)
if m.Units != "" {
out += " [" + m.Units + "]"
}
if style != "" {
out = style + out + "{{/}}"
}
out += "\n"
out += m.Stats().String() + "\n"
}
t := table.NewTable()
t.TableStyle.EnableTextStyling = enableStyling
switch m.Type {
case MeasurementTypeValue:
t.AppendRow(table.R(table.C("Value", table.AlignTypeCenter), table.C("Annotation", table.AlignTypeCenter), table.Divider("="), style))
for idx := range m.Values {
t.AppendRow(table.R(
table.C(fmt.Sprintf(m.PrecisionBundle.ValueFormat, m.Values[idx]), table.AlignTypeRight),
table.C(m.Annotations[idx], "{{gray}}", table.AlignTypeLeft),
))
}
case MeasurementTypeDuration:
t.AppendRow(table.R(table.C("Duration", table.AlignTypeCenter), table.C("Annotation", table.AlignTypeCenter), table.Divider("="), style))
for idx := range m.Durations {
t.AppendRow(table.R(
table.C(m.Durations[idx].Round(m.PrecisionBundle.Duration).String(), style, table.AlignTypeRight),
table.C(m.Annotations[idx], "{{gray}}", table.AlignTypeLeft),
))
}
}
out += t.Render()
return out
}
/*
ColorableString generates a styled report that includes all the data points for this Measurement.
It is called automatically by Ginkgo's reporting infrastructure when the Measurement is registered as a ReportEntry via AddReportEntry.
*/
func (m Measurement) ColorableString() string {
return m.report(true)
}
/*
String generates an unstyled report that includes all the data points for this Measurement.
*/
func (m Measurement) String() string {
return m.report(false)
}
/*
Stats returns a Stats struct summarizing the statistic of this measurement
*/
func (m Measurement) Stats() Stats {
if m.Type == MeasurementTypeInvalid || m.Type == MeasurementTypeNote {
return Stats{}
}
out := Stats{
ExperimentName: m.ExperimentName,
MeasurementName: m.Name,
Style: m.Style,
Units: m.Units,
PrecisionBundle: m.PrecisionBundle,
}
switch m.Type {
case MeasurementTypeValue:
out.Type = StatsTypeValue
out.N = len(m.Values)
if out.N == 0 {
return out
}
indices, sum := make([]int, len(m.Values)), 0.0
for idx, v := range m.Values {
indices[idx] = idx
sum += v
}
sort.Slice(indices, func(i, j int) bool {
return m.Values[indices[i]] < m.Values[indices[j]]
})
out.ValueBundle = map[Stat]float64{
StatMin: m.Values[indices[0]],
StatMax: m.Values[indices[out.N-1]],
StatMean: sum / float64(out.N),
StatStdDev: 0.0,
}
out.AnnotationBundle = map[Stat]string{
StatMin: m.Annotations[indices[0]],
StatMax: m.Annotations[indices[out.N-1]],
}
if out.N%2 == 0 {
out.ValueBundle[StatMedian] = (m.Values[indices[out.N/2]] + m.Values[indices[out.N/2-1]]) / 2.0
} else {
out.ValueBundle[StatMedian] = m.Values[indices[(out.N-1)/2]]
}
for _, v := range m.Values {
out.ValueBundle[StatStdDev] += (v - out.ValueBundle[StatMean]) * (v - out.ValueBundle[StatMean])
}
out.ValueBundle[StatStdDev] = math.Sqrt(out.ValueBundle[StatStdDev] / float64(out.N))
case MeasurementTypeDuration:
out.Type = StatsTypeDuration
out.N = len(m.Durations)
if out.N == 0 {
return out
}
indices, sum := make([]int, len(m.Durations)), time.Duration(0)
for idx, v := range m.Durations {
indices[idx] = idx
sum += v
}
sort.Slice(indices, func(i, j int) bool {
return m.Durations[indices[i]] < m.Durations[indices[j]]
})
out.DurationBundle = map[Stat]time.Duration{
StatMin: m.Durations[indices[0]],
StatMax: m.Durations[indices[out.N-1]],
StatMean: sum / time.Duration(out.N),
}
out.AnnotationBundle = map[Stat]string{
StatMin: m.Annotations[indices[0]],
StatMax: m.Annotations[indices[out.N-1]],
}
if out.N%2 == 0 {
out.DurationBundle[StatMedian] = (m.Durations[indices[out.N/2]] + m.Durations[indices[out.N/2-1]]) / 2
} else {
out.DurationBundle[StatMedian] = m.Durations[indices[(out.N-1)/2]]
}
stdDev := 0.0
for _, v := range m.Durations {
stdDev += float64(v-out.DurationBundle[StatMean]) * float64(v-out.DurationBundle[StatMean])
}
out.DurationBundle[StatStdDev] = time.Duration(math.Sqrt(stdDev / float64(out.N)))
}
return out
}
golang-gomega-1.27.10/gmeasure/measurement_test.go 0000664 0000000 0000000 00000022222 14462163431 0022115 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"math"
"strings"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gmeasure"
)
var _ = Describe("Measurement", func() {
var e *gmeasure.Experiment
var measurement gmeasure.Measurement
BeforeEach(func() {
e = gmeasure.NewExperiment("Test Experiment")
})
Describe("Note Measurement", func() {
BeforeEach(func() {
e.RecordNote("I'm a red note", gmeasure.Style("{{red}}"))
measurement = e.Measurements[0]
})
Describe("Generating Stats", func() {
It("returns an empty stats", func() {
Ω(measurement.Stats()).Should(BeZero())
})
})
Describe("Emitting an unstyled report", func() {
It("does not include styling", func() {
Ω(measurement.String()).Should(Equal("Test Experiment - Note\nI'm a red note\n"))
})
})
Describe("Emitting a styled report", func() {
It("does include styling", func() {
Ω(measurement.ColorableString()).Should(Equal("{{red}}Test Experiment - Note\nI'm a red note\n{{/}}"))
})
})
})
Describe("Value Measurement", func() {
var min, median, mean, stdDev, max float64
BeforeEach(func() {
e.RecordValue("flange widths", 7.128, gmeasure.Annotation("A"), gmeasure.Precision(2), gmeasure.Units("inches"), gmeasure.Style("{{blue}}"))
e.RecordValue("flange widths", 3.141, gmeasure.Annotation("B"))
e.RecordValue("flange widths", 9.28223, gmeasure.Annotation("C"))
e.RecordValue("flange widths", 14.249, gmeasure.Annotation("D"))
e.RecordValue("flange widths", 8.975, gmeasure.Annotation("E"))
measurement = e.Measurements[0]
min = 3.141
max = 14.249
median = 8.975
mean = (7.128 + 3.141 + 9.28223 + 14.249 + 8.975) / 5.0
stdDev = (7.128-mean)*(7.128-mean) + (3.141-mean)*(3.141-mean) + (9.28223-mean)*(9.28223-mean) + (14.249-mean)*(14.249-mean) + (8.975-mean)*(8.975-mean)
stdDev = math.Sqrt(stdDev / 5.0)
})
Describe("Generating Stats", func() {
It("generates a correctly configured Stats with correct values", func() {
stats := measurement.Stats()
Ω(stats.ExperimentName).Should(Equal("Test Experiment"))
Ω(stats.MeasurementName).Should(Equal("flange widths"))
Ω(stats.Style).Should(Equal("{{blue}}"))
Ω(stats.Units).Should(Equal("inches"))
Ω(stats.PrecisionBundle.ValueFormat).Should(Equal("%.2f"))
Ω(stats.ValueBundle[gmeasure.StatMin]).Should(Equal(min))
Ω(stats.AnnotationBundle[gmeasure.StatMin]).Should(Equal("B"))
Ω(stats.ValueBundle[gmeasure.StatMax]).Should(Equal(max))
Ω(stats.AnnotationBundle[gmeasure.StatMax]).Should(Equal("D"))
Ω(stats.ValueBundle[gmeasure.StatMedian]).Should(Equal(median))
Ω(stats.ValueBundle[gmeasure.StatMean]).Should(Equal(mean))
Ω(stats.ValueBundle[gmeasure.StatStdDev]).Should(BeNumerically("~", stdDev))
})
})
Describe("Emitting an unstyled report", func() {
It("does not include styling", func() {
expected := strings.Join([]string{
"Test Experiment - flange widths [inches]",
"3.14 < [8.97] | <8.56> ±3.59 < 14.25",
"Value | Annotation",
"==================",
" 7.13 | A ",
"------------------",
" 3.14 | B ",
"------------------",
" 9.28 | C ",
"------------------",
"14.25 | D ",
"------------------",
" 8.97 | E ",
"",
}, "\n")
Ω(measurement.String()).Should(Equal(expected))
})
})
Describe("Emitting a styled report", func() {
It("does include styling", func() {
expected := strings.Join([]string{
"{{blue}}Test Experiment - flange widths [inches]{{/}}",
"3.14 < [8.97] | <8.56> ±3.59 < 14.25",
"{{blue}}Value{{/}} | {{blue}}Annotation{{/}}",
"==================",
" 7.13 | {{gray}}A {{/}}",
"------------------",
" 3.14 | {{gray}}B {{/}}",
"------------------",
" 9.28 | {{gray}}C {{/}}",
"------------------",
"14.25 | {{gray}}D {{/}}",
"------------------",
" 8.97 | {{gray}}E {{/}}",
"",
}, "\n")
Ω(measurement.ColorableString()).Should(Equal(expected))
})
})
Describe("Computing medians", func() {
Context("with an odd number of values", func() {
It("returns the middle element", func() {
e.RecordValue("odd", 5)
e.RecordValue("odd", 1)
e.RecordValue("odd", 2)
e.RecordValue("odd", 4)
e.RecordValue("odd", 3)
Ω(e.GetStats("odd").ValueBundle[gmeasure.StatMedian]).Should(Equal(3.0))
})
})
Context("when an even number of values", func() {
It("returns the mean of the two middle elements", func() {
e.RecordValue("even", 1)
e.RecordValue("even", 2)
e.RecordValue("even", 4)
e.RecordValue("even", 3)
Ω(e.GetStats("even").ValueBundle[gmeasure.StatMedian]).Should(Equal(2.5))
})
})
})
})
Describe("Duration Measurement", func() {
var min, median, mean, stdDev, max time.Duration
BeforeEach(func() {
e.RecordDuration("runtime", 7128*time.Millisecond, gmeasure.Annotation("A"), gmeasure.Precision(time.Millisecond*100), gmeasure.Style("{{blue}}"))
e.RecordDuration("runtime", 3141*time.Millisecond, gmeasure.Annotation("B"))
e.RecordDuration("runtime", 9282*time.Millisecond, gmeasure.Annotation("C"))
e.RecordDuration("runtime", 14249*time.Millisecond, gmeasure.Annotation("D"))
e.RecordDuration("runtime", 8975*time.Millisecond, gmeasure.Annotation("E"))
measurement = e.Measurements[0]
min = 3141 * time.Millisecond
max = 14249 * time.Millisecond
median = 8975 * time.Millisecond
mean = ((7128 + 3141 + 9282 + 14249 + 8975) * time.Millisecond) / 5
stdDev = time.Duration(math.Sqrt((float64(7128*time.Millisecond-mean)*float64(7128*time.Millisecond-mean) + float64(3141*time.Millisecond-mean)*float64(3141*time.Millisecond-mean) + float64(9282*time.Millisecond-mean)*float64(9282*time.Millisecond-mean) + float64(14249*time.Millisecond-mean)*float64(14249*time.Millisecond-mean) + float64(8975*time.Millisecond-mean)*float64(8975*time.Millisecond-mean)) / 5.0))
})
Describe("Generating Stats", func() {
It("generates a correctly configured Stats with correct values", func() {
stats := measurement.Stats()
Ω(stats.ExperimentName).Should(Equal("Test Experiment"))
Ω(stats.MeasurementName).Should(Equal("runtime"))
Ω(stats.Style).Should(Equal("{{blue}}"))
Ω(stats.Units).Should(Equal("duration"))
Ω(stats.PrecisionBundle.Duration).Should(Equal(time.Millisecond * 100))
Ω(stats.DurationBundle[gmeasure.StatMin]).Should(Equal(min))
Ω(stats.AnnotationBundle[gmeasure.StatMin]).Should(Equal("B"))
Ω(stats.DurationBundle[gmeasure.StatMax]).Should(Equal(max))
Ω(stats.AnnotationBundle[gmeasure.StatMax]).Should(Equal("D"))
Ω(stats.DurationBundle[gmeasure.StatMedian]).Should(Equal(median))
Ω(stats.DurationBundle[gmeasure.StatMean]).Should(Equal(mean))
Ω(stats.DurationBundle[gmeasure.StatStdDev]).Should(Equal(stdDev))
})
})
Describe("Emitting an unstyled report", func() {
It("does not include styling", func() {
expected := strings.Join([]string{
"Test Experiment - runtime [duration]",
"3.1s < [9s] | <8.6s> ±3.6s < 14.2s",
"Duration | Annotation",
"=====================",
" 7.1s | A ",
"---------------------",
" 3.1s | B ",
"---------------------",
" 9.3s | C ",
"---------------------",
" 14.2s | D ",
"---------------------",
" 9s | E ",
"",
}, "\n")
Ω(measurement.String()).Should(Equal(expected))
})
})
Describe("Emitting a styled report", func() {
It("does include styling", func() {
expected := strings.Join([]string{
"{{blue}}Test Experiment - runtime [duration]{{/}}",
"3.1s < [9s] | <8.6s> ±3.6s < 14.2s",
"{{blue}}Duration{{/}} | {{blue}}Annotation{{/}}",
"=====================",
"{{blue}} 7.1s{{/}} | {{gray}}A {{/}}",
"---------------------",
"{{blue}} 3.1s{{/}} | {{gray}}B {{/}}",
"---------------------",
"{{blue}} 9.3s{{/}} | {{gray}}C {{/}}",
"---------------------",
"{{blue}} 14.2s{{/}} | {{gray}}D {{/}}",
"---------------------",
"{{blue}} 9s{{/}} | {{gray}}E {{/}}",
"",
}, "\n")
Ω(measurement.ColorableString()).Should(Equal(expected))
})
})
Describe("Computing medians", func() {
Context("with an odd number of values", func() {
It("returns the middle element", func() {
e.RecordDuration("odd", 5*time.Second)
e.RecordDuration("odd", 1*time.Second)
e.RecordDuration("odd", 2*time.Second)
e.RecordDuration("odd", 4*time.Second)
e.RecordDuration("odd", 3*time.Second)
Ω(e.GetStats("odd").DurationBundle[gmeasure.StatMedian]).Should(Equal(3 * time.Second))
})
})
Context("when an even number of values", func() {
It("returns the mean of the two middle elements", func() {
e.RecordDuration("even", 1*time.Second)
e.RecordDuration("even", 2*time.Second)
e.RecordDuration("even", 4*time.Second)
e.RecordDuration("even", 3*time.Second)
Ω(e.GetStats("even").DurationBundle[gmeasure.StatMedian]).Should(Equal(2500 * time.Millisecond))
})
})
})
})
})
golang-gomega-1.27.10/gmeasure/rank.go 0000664 0000000 0000000 00000010747 14462163431 0017475 0 ustar 00root root 0000000 0000000 package gmeasure
import (
"fmt"
"sort"
"github.com/onsi/gomega/gmeasure/table"
)
/*
RankingCriteria is an enum representing the criteria by which Stats should be ranked. The enum names should be self explanatory. e.g. LowerMeanIsBetter means that Stats with lower mean values are considered more beneficial, with the lowest mean being declared the "winner" .
*/
type RankingCriteria uint
const (
LowerMeanIsBetter RankingCriteria = iota
HigherMeanIsBetter
LowerMedianIsBetter
HigherMedianIsBetter
LowerMinIsBetter
HigherMinIsBetter
LowerMaxIsBetter
HigherMaxIsBetter
)
var rcEnumSupport = newEnumSupport(map[uint]string{uint(LowerMeanIsBetter): "Lower Mean is Better", uint(HigherMeanIsBetter): "Higher Mean is Better", uint(LowerMedianIsBetter): "Lower Median is Better", uint(HigherMedianIsBetter): "Higher Median is Better", uint(LowerMinIsBetter): "Lower Mins is Better", uint(HigherMinIsBetter): "Higher Min is Better", uint(LowerMaxIsBetter): "Lower Max is Better", uint(HigherMaxIsBetter): "Higher Max is Better"})
func (s RankingCriteria) String() string { return rcEnumSupport.String(uint(s)) }
func (s *RankingCriteria) UnmarshalJSON(b []byte) error {
out, err := rcEnumSupport.UnmarshJSON(b)
*s = RankingCriteria(out)
return err
}
func (s RankingCriteria) MarshalJSON() ([]byte, error) { return rcEnumSupport.MarshJSON(uint(s)) }
/*
Ranking ranks a set of Stats by a specified RankingCritera. Use RankStats to create a Ranking.
When using Ginkgo, you can register Rankings as Report Entries via AddReportEntry. This will emit a formatted table representing the Stats in rank-order when Ginkgo generates the report.
*/
type Ranking struct {
Criteria RankingCriteria
Stats []Stats
}
/*
RankStats creates a new ranking of the passed-in stats according to the passed-in criteria.
*/
func RankStats(criteria RankingCriteria, stats ...Stats) Ranking {
sort.Slice(stats, func(i int, j int) bool {
switch criteria {
case LowerMeanIsBetter:
return stats[i].FloatFor(StatMean) < stats[j].FloatFor(StatMean)
case HigherMeanIsBetter:
return stats[i].FloatFor(StatMean) > stats[j].FloatFor(StatMean)
case LowerMedianIsBetter:
return stats[i].FloatFor(StatMedian) < stats[j].FloatFor(StatMedian)
case HigherMedianIsBetter:
return stats[i].FloatFor(StatMedian) > stats[j].FloatFor(StatMedian)
case LowerMinIsBetter:
return stats[i].FloatFor(StatMin) < stats[j].FloatFor(StatMin)
case HigherMinIsBetter:
return stats[i].FloatFor(StatMin) > stats[j].FloatFor(StatMin)
case LowerMaxIsBetter:
return stats[i].FloatFor(StatMax) < stats[j].FloatFor(StatMax)
case HigherMaxIsBetter:
return stats[i].FloatFor(StatMax) > stats[j].FloatFor(StatMax)
}
return false
})
out := Ranking{
Criteria: criteria,
Stats: stats,
}
return out
}
/*
Winner returns the Stats with the most optimal rank based on the specified ranking criteria. For example, if the RankingCriteria is LowerMaxIsBetter then the Stats with the lowest value or duration for StatMax will be returned as the "winner"
*/
func (c Ranking) Winner() Stats {
if len(c.Stats) == 0 {
return Stats{}
}
return c.Stats[0]
}
func (c Ranking) report(enableStyling bool) string {
if len(c.Stats) == 0 {
return "Empty Ranking"
}
t := table.NewTable()
t.TableStyle.EnableTextStyling = enableStyling
t.AppendRow(table.R(
table.C("Experiment"), table.C("Name"), table.C("N"), table.C("Min"), table.C("Median"), table.C("Mean"), table.C("StdDev"), table.C("Max"),
table.Divider("="),
"{{bold}}",
))
for idx, stats := range c.Stats {
name := stats.MeasurementName
if stats.Units != "" {
name = name + " [" + stats.Units + "]"
}
experimentName := stats.ExperimentName
style := stats.Style
if idx == 0 {
style = "{{bold}}" + style
name += "\n*Winner*"
experimentName += "\n*Winner*"
}
r := table.R(style)
t.AppendRow(r)
r.AppendCell(table.C(experimentName), table.C(name))
r.AppendCell(stats.cells()...)
}
out := fmt.Sprintf("Ranking Criteria: %s\n", c.Criteria)
if enableStyling {
out = "{{bold}}" + out + "{{/}}"
}
out += t.Render()
return out
}
/*
ColorableString generates a styled report that includes a table of the rank-ordered Stats
It is called automatically by Ginkgo's reporting infrastructure when the Ranking is registered as a ReportEntry via AddReportEntry.
*/
func (c Ranking) ColorableString() string {
return c.report(true)
}
/*
String generates an unstyled report that includes a table of the rank-ordered Stats
*/
func (c Ranking) String() string {
return c.report(false)
}
golang-gomega-1.27.10/gmeasure/rank_test.go 0000664 0000000 0000000 00000021442 14462163431 0020526 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"strings"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gmeasure"
)
var _ = Describe("Rank", func() {
var A, B, C, D gmeasure.Stats
Describe("Ranking Values", func() {
makeStats := func(name string, min float64, max float64, mean float64, median float64) gmeasure.Stats {
return gmeasure.Stats{
Type: gmeasure.StatsTypeValue,
ExperimentName: "Exp-" + name,
MeasurementName: name,
N: 100,
PrecisionBundle: gmeasure.Precision(2),
ValueBundle: map[gmeasure.Stat]float64{
gmeasure.StatMin: min,
gmeasure.StatMax: max,
gmeasure.StatMean: mean,
gmeasure.StatMedian: median,
gmeasure.StatStdDev: 2.0,
},
}
}
BeforeEach(func() {
A = makeStats("A", 1, 2, 3, 4)
B = makeStats("B", 2, 3, 4, 1)
C = makeStats("C", 3, 4, 1, 2)
D = makeStats("D", 4, 1, 2, 3)
})
DescribeTable("ranking by criteria",
func(criteria gmeasure.RankingCriteria, expectedOrder func() []gmeasure.Stats) {
ranking := gmeasure.RankStats(criteria, A, B, C, D)
expected := expectedOrder()
Ω(ranking.Winner()).Should(Equal(expected[0]))
Ω(ranking.Stats).Should(Equal(expected))
},
Entry("entry", gmeasure.LowerMeanIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{C, D, A, B} }),
Entry("entry", gmeasure.HigherMeanIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{B, A, D, C} }),
Entry("entry", gmeasure.LowerMedianIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{B, C, D, A} }),
Entry("entry", gmeasure.HigherMedianIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{A, D, C, B} }),
Entry("entry", gmeasure.LowerMinIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{A, B, C, D} }),
Entry("entry", gmeasure.HigherMinIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{D, C, B, A} }),
Entry("entry", gmeasure.LowerMaxIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{D, A, B, C} }),
Entry("entry", gmeasure.HigherMaxIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{C, B, A, D} }),
)
Describe("Generating Reports", func() {
It("can generate an unstyled report", func() {
ranking := gmeasure.RankStats(gmeasure.LowerMeanIsBetter, A, B, C, D)
Ω(ranking.String()).Should(Equal(strings.Join([]string{
"Ranking Criteria: Lower Mean is Better",
"Experiment | Name | N | Min | Median | Mean | StdDev | Max ",
"==================================================================",
"Exp-C | C | 100 | 3.00 | 2.00 | 1.00 | 2.00 | 4.00",
"*Winner* | *Winner* | | | | | | ",
"------------------------------------------------------------------",
"Exp-D | D | 100 | 4.00 | 3.00 | 2.00 | 2.00 | 1.00",
"------------------------------------------------------------------",
"Exp-A | A | 100 | 1.00 | 4.00 | 3.00 | 2.00 | 2.00",
"------------------------------------------------------------------",
"Exp-B | B | 100 | 2.00 | 1.00 | 4.00 | 2.00 | 3.00",
"",
}, "\n")))
})
It("can generate a styled report", func() {
ranking := gmeasure.RankStats(gmeasure.LowerMeanIsBetter, A, B, C, D)
Ω(ranking.ColorableString()).Should(Equal(strings.Join([]string{
"{{bold}}Ranking Criteria: Lower Mean is Better",
"{{/}}{{bold}}Experiment{{/}} | {{bold}}Name {{/}} | {{bold}}N {{/}} | {{bold}}Min {{/}} | {{bold}}Median{{/}} | {{bold}}Mean{{/}} | {{bold}}StdDev{{/}} | {{bold}}Max {{/}}",
"==================================================================",
"{{bold}}Exp-C {{/}} | {{bold}}C {{/}} | {{bold}}100{{/}} | {{bold}}3.00{{/}} | {{bold}}2.00 {{/}} | {{bold}}1.00{{/}} | {{bold}}2.00 {{/}} | {{bold}}4.00{{/}}",
"{{bold}}*Winner* {{/}} | {{bold}}*Winner*{{/}} | | | | | | ",
"------------------------------------------------------------------",
"Exp-D | D | 100 | 4.00 | 3.00 | 2.00 | 2.00 | 1.00",
"------------------------------------------------------------------",
"Exp-A | A | 100 | 1.00 | 4.00 | 3.00 | 2.00 | 2.00",
"------------------------------------------------------------------",
"Exp-B | B | 100 | 2.00 | 1.00 | 4.00 | 2.00 | 3.00",
"",
}, "\n")))
})
})
})
Describe("Ranking Durations", func() {
makeStats := func(name string, min time.Duration, max time.Duration, mean time.Duration, median time.Duration) gmeasure.Stats {
return gmeasure.Stats{
Type: gmeasure.StatsTypeDuration,
ExperimentName: "Exp-" + name,
MeasurementName: name,
N: 100,
PrecisionBundle: gmeasure.Precision(time.Millisecond * 100),
DurationBundle: map[gmeasure.Stat]time.Duration{
gmeasure.StatMin: min,
gmeasure.StatMax: max,
gmeasure.StatMean: mean,
gmeasure.StatMedian: median,
gmeasure.StatStdDev: 2.0,
},
}
}
BeforeEach(func() {
A = makeStats("A", 1*time.Second, 2*time.Second, 3*time.Second, 4*time.Second)
B = makeStats("B", 2*time.Second, 3*time.Second, 4*time.Second, 1*time.Second)
C = makeStats("C", 3*time.Second, 4*time.Second, 1*time.Second, 2*time.Second)
D = makeStats("D", 4*time.Second, 1*time.Second, 2*time.Second, 3*time.Second)
})
DescribeTable("ranking by criteria",
func(criteria gmeasure.RankingCriteria, expectedOrder func() []gmeasure.Stats) {
ranking := gmeasure.RankStats(criteria, A, B, C, D)
expected := expectedOrder()
Ω(ranking.Winner()).Should(Equal(expected[0]))
Ω(ranking.Stats).Should(Equal(expected))
},
Entry("entry", gmeasure.LowerMeanIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{C, D, A, B} }),
Entry("entry", gmeasure.HigherMeanIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{B, A, D, C} }),
Entry("entry", gmeasure.LowerMedianIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{B, C, D, A} }),
Entry("entry", gmeasure.HigherMedianIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{A, D, C, B} }),
Entry("entry", gmeasure.LowerMinIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{A, B, C, D} }),
Entry("entry", gmeasure.HigherMinIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{D, C, B, A} }),
Entry("entry", gmeasure.LowerMaxIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{D, A, B, C} }),
Entry("entry", gmeasure.HigherMaxIsBetter, func() []gmeasure.Stats { return []gmeasure.Stats{C, B, A, D} }),
)
Describe("Generating Reports", func() {
It("can generate an unstyled report", func() {
ranking := gmeasure.RankStats(gmeasure.LowerMeanIsBetter, A, B, C, D)
Ω(ranking.String()).Should(Equal(strings.Join([]string{
"Ranking Criteria: Lower Mean is Better",
"Experiment | Name | N | Min | Median | Mean | StdDev | Max",
"================================================================",
"Exp-C | C | 100 | 3s | 2s | 1s | 0s | 4s ",
"*Winner* | *Winner* | | | | | | ",
"----------------------------------------------------------------",
"Exp-D | D | 100 | 4s | 3s | 2s | 0s | 1s ",
"----------------------------------------------------------------",
"Exp-A | A | 100 | 1s | 4s | 3s | 0s | 2s ",
"----------------------------------------------------------------",
"Exp-B | B | 100 | 2s | 1s | 4s | 0s | 3s ",
"",
}, "\n")))
})
It("can generate a styled report", func() {
ranking := gmeasure.RankStats(gmeasure.LowerMeanIsBetter, A, B, C, D)
Ω(ranking.ColorableString()).Should(Equal(strings.Join([]string{
"{{bold}}Ranking Criteria: Lower Mean is Better",
"{{/}}{{bold}}Experiment{{/}} | {{bold}}Name {{/}} | {{bold}}N {{/}} | {{bold}}Min{{/}} | {{bold}}Median{{/}} | {{bold}}Mean{{/}} | {{bold}}StdDev{{/}} | {{bold}}Max{{/}}",
"================================================================",
"{{bold}}Exp-C {{/}} | {{bold}}C {{/}} | {{bold}}100{{/}} | {{bold}}3s {{/}} | {{bold}}2s {{/}} | {{bold}}1s {{/}} | {{bold}}0s {{/}} | {{bold}}4s {{/}}",
"{{bold}}*Winner* {{/}} | {{bold}}*Winner*{{/}} | | | | | | ",
"----------------------------------------------------------------",
"Exp-D | D | 100 | 4s | 3s | 2s | 0s | 1s ",
"----------------------------------------------------------------",
"Exp-A | A | 100 | 1s | 4s | 3s | 0s | 2s ",
"----------------------------------------------------------------",
"Exp-B | B | 100 | 2s | 1s | 4s | 0s | 3s ",
"",
}, "\n")))
})
})
})
})
golang-gomega-1.27.10/gmeasure/stats.go 0000664 0000000 0000000 00000012731 14462163431 0017673 0 ustar 00root root 0000000 0000000 package gmeasure
import (
"fmt"
"time"
"github.com/onsi/gomega/gmeasure/table"
)
/*
Stat is an enum representing the statistics you can request of a Stats struct
*/
type Stat uint
const (
StatInvalid Stat = iota
StatMin
StatMax
StatMean
StatMedian
StatStdDev
)
var statEnumSupport = newEnumSupport(map[uint]string{uint(StatInvalid): "INVALID STAT", uint(StatMin): "Min", uint(StatMax): "Max", uint(StatMean): "Mean", uint(StatMedian): "Median", uint(StatStdDev): "StdDev"})
func (s Stat) String() string { return statEnumSupport.String(uint(s)) }
func (s *Stat) UnmarshalJSON(b []byte) error {
out, err := statEnumSupport.UnmarshJSON(b)
*s = Stat(out)
return err
}
func (s Stat) MarshalJSON() ([]byte, error) { return statEnumSupport.MarshJSON(uint(s)) }
type StatsType uint
const (
StatsTypeInvalid StatsType = iota
StatsTypeValue
StatsTypeDuration
)
var statsTypeEnumSupport = newEnumSupport(map[uint]string{uint(StatsTypeInvalid): "INVALID STATS TYPE", uint(StatsTypeValue): "StatsTypeValue", uint(StatsTypeDuration): "StatsTypeDuration"})
func (s StatsType) String() string { return statsTypeEnumSupport.String(uint(s)) }
func (s *StatsType) UnmarshalJSON(b []byte) error {
out, err := statsTypeEnumSupport.UnmarshJSON(b)
*s = StatsType(out)
return err
}
func (s StatsType) MarshalJSON() ([]byte, error) { return statsTypeEnumSupport.MarshJSON(uint(s)) }
/*
Stats records the key statistics for a given measurement. You generally don't make Stats directly - but you can fetch them from Experiments using GetStats() and from Measurements using Stats().
When using Ginkgo, you can register Measurements as Report Entries via AddReportEntry. This will emit all the captured data points when Ginkgo generates the report.
*/
type Stats struct {
// Type is the StatType - one of StatTypeDuration or StatTypeValue
Type StatsType
// ExperimentName is the name of the Experiment that recorded the Measurement from which this Stat is derived
ExperimentName string
// MeasurementName is the name of the Measurement from which this Stat is derived
MeasurementName string
// Units captures the Units of the Measurement from which this Stat is derived
Units string
// Style captures the Style of the Measurement from which this Stat is derived
Style string
// PrecisionBundle captures the precision to use when rendering data for this Measurement.
// If Type is StatTypeDuration then PrecisionBundle.Duration is used to round any durations before presentation.
// If Type is StatTypeValue then PrecisionBundle.ValueFormat is used to format any values before presentation
PrecisionBundle PrecisionBundle
// N represents the total number of data points in the Meassurement from which this Stat is derived
N int
// If Type is StatTypeValue, ValueBundle will be populated with float64s representing this Stat's statistics
ValueBundle map[Stat]float64
// If Type is StatTypeDuration, DurationBundle will be populated with float64s representing this Stat's statistics
DurationBundle map[Stat]time.Duration
// AnnotationBundle is populated with Annotations corresponding to the data points that can be associated with a Stat.
// For example AnnotationBundle[StatMin] will return the Annotation for the data point that has the minimum value/duration.
AnnotationBundle map[Stat]string
}
// String returns a minimal summary of the stats of the form "MIN < [MEDIAN] | ±STDDEV < MAX"
func (s Stats) String() string {
return fmt.Sprintf("%s < [%s] | <%s> ±%s < %s", s.StringFor(StatMin), s.StringFor(StatMedian), s.StringFor(StatMean), s.StringFor(StatStdDev), s.StringFor(StatMax))
}
// ValueFor returns the float64 value for a particular Stat. You should only use this if the Stats has Type StatsTypeValue
// For example:
//
// median := experiment.GetStats("length").ValueFor(gmeasure.StatMedian)
//
// will return the median data point for the "length" Measurement.
func (s Stats) ValueFor(stat Stat) float64 {
return s.ValueBundle[stat]
}
// DurationFor returns the time.Duration for a particular Stat. You should only use this if the Stats has Type StatsTypeDuration
// For example:
//
// mean := experiment.GetStats("runtime").ValueFor(gmeasure.StatMean)
//
// will return the mean duration for the "runtime" Measurement.
func (s Stats) DurationFor(stat Stat) time.Duration {
return s.DurationBundle[stat]
}
// FloatFor returns a float64 representation of the passed-in Stat.
// When Type is StatsTypeValue this is equivalent to s.ValueFor(stat).
// When Type is StatsTypeDuration this is equivalent to float64(s.DurationFor(stat))
func (s Stats) FloatFor(stat Stat) float64 {
switch s.Type {
case StatsTypeValue:
return s.ValueFor(stat)
case StatsTypeDuration:
return float64(s.DurationFor(stat))
}
return 0
}
// StringFor returns a formatted string representation of the passed-in Stat.
// The formatting honors the precision directives provided in stats.PrecisionBundle
func (s Stats) StringFor(stat Stat) string {
switch s.Type {
case StatsTypeValue:
return fmt.Sprintf(s.PrecisionBundle.ValueFormat, s.ValueFor(stat))
case StatsTypeDuration:
return s.DurationFor(stat).Round(s.PrecisionBundle.Duration).String()
}
return ""
}
func (s Stats) cells() []table.Cell {
out := []table.Cell{}
out = append(out, table.C(fmt.Sprintf("%d", s.N)))
for _, stat := range []Stat{StatMin, StatMedian, StatMean, StatStdDev, StatMax} {
content := s.StringFor(stat)
if s.AnnotationBundle[stat] != "" {
content += "\n" + s.AnnotationBundle[stat]
}
out = append(out, table.C(content))
}
return out
}
golang-gomega-1.27.10/gmeasure/stats_test.go 0000664 0000000 0000000 00000006432 14462163431 0020733 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gmeasure"
)
var _ = Describe("Stats", func() {
var stats gmeasure.Stats
Describe("Stats representing values", func() {
BeforeEach(func() {
stats = gmeasure.Stats{
Type: gmeasure.StatsTypeValue,
ExperimentName: "My Test Experiment",
MeasurementName: "Sprockets",
Units: "widgets",
N: 100,
PrecisionBundle: gmeasure.Precision(2),
ValueBundle: map[gmeasure.Stat]float64{
gmeasure.StatMin: 17.48992,
gmeasure.StatMax: 293.4820,
gmeasure.StatMean: 187.3023,
gmeasure.StatMedian: 87.2235,
gmeasure.StatStdDev: 73.6394,
},
}
})
Describe("String()", func() {
It("returns a one-line summary", func() {
Ω(stats.String()).Should(Equal("17.49 < [87.22] | <187.30> ±73.64 < 293.48"))
})
})
Describe("ValueFor()", func() {
It("returns the value for the requested stat", func() {
Ω(stats.ValueFor(gmeasure.StatMin)).Should(Equal(17.48992))
Ω(stats.ValueFor(gmeasure.StatMean)).Should(Equal(187.3023))
})
})
Describe("FloatFor", func() {
It("returns the requested stat as a float", func() {
Ω(stats.FloatFor(gmeasure.StatMin)).Should(Equal(17.48992))
Ω(stats.FloatFor(gmeasure.StatMean)).Should(Equal(187.3023))
})
})
Describe("StringFor", func() {
It("returns the requested stat rendered with the configured precision", func() {
Ω(stats.StringFor(gmeasure.StatMin)).Should(Equal("17.49"))
Ω(stats.StringFor(gmeasure.StatMean)).Should(Equal("187.30"))
})
})
})
Describe("Stats representing durations", func() {
BeforeEach(func() {
stats = gmeasure.Stats{
Type: gmeasure.StatsTypeDuration,
ExperimentName: "My Test Experiment",
MeasurementName: "Runtime",
N: 100,
PrecisionBundle: gmeasure.Precision(time.Millisecond * 100),
DurationBundle: map[gmeasure.Stat]time.Duration{
gmeasure.StatMin: 17375 * time.Millisecond,
gmeasure.StatMax: 890321 * time.Millisecond,
gmeasure.StatMean: 328712 * time.Millisecond,
gmeasure.StatMedian: 552390 * time.Millisecond,
gmeasure.StatStdDev: 186259 * time.Millisecond,
},
}
})
Describe("String()", func() {
It("returns a one-line summary", func() {
Ω(stats.String()).Should(Equal("17.4s < [9m12.4s] | <5m28.7s> ±3m6.3s < 14m50.3s"))
})
})
Describe("DurationFor()", func() {
It("returns the duration for the requested stat", func() {
Ω(stats.DurationFor(gmeasure.StatMin)).Should(Equal(17375 * time.Millisecond))
Ω(stats.DurationFor(gmeasure.StatMean)).Should(Equal(328712 * time.Millisecond))
})
})
Describe("FloatFor", func() {
It("returns the float64 representation for the requested duration stat", func() {
Ω(stats.FloatFor(gmeasure.StatMin)).Should(Equal(float64(17375 * time.Millisecond)))
Ω(stats.FloatFor(gmeasure.StatMean)).Should(Equal(float64(328712 * time.Millisecond)))
})
})
Describe("StringFor", func() {
It("returns the requested stat rendered with the configured precision", func() {
Ω(stats.StringFor(gmeasure.StatMin)).Should(Equal("17.4s"))
Ω(stats.StringFor(gmeasure.StatMean)).Should(Equal("5m28.7s"))
})
})
})
})
golang-gomega-1.27.10/gmeasure/stopwatch.go 0000664 0000000 0000000 00000010407 14462163431 0020547 0 ustar 00root root 0000000 0000000 package gmeasure
import "time"
/*
Stopwatch provides a convenient abstraction for recording durations. There are two ways to make a Stopwatch:
You can make a Stopwatch from an Experiment via experiment.NewStopwatch(). This is how you first get a hold of a Stopwatch.
You can subsequently call stopwatch.NewStopwatch() to get a fresh Stopwatch.
This is only necessary if you need to record durations on a different goroutine as a single Stopwatch is not considered thread-safe.
The Stopwatch starts as soon as it is created. You can Pause() the stopwatch and Reset() it as needed.
Stopwatches refer back to their parent Experiment. They use this reference to record any measured durations back with the Experiment.
*/
type Stopwatch struct {
Experiment *Experiment
t time.Time
pauseT time.Time
pauseDuration time.Duration
running bool
}
func newStopwatch(experiment *Experiment) *Stopwatch {
return &Stopwatch{
Experiment: experiment,
t: time.Now(),
running: true,
}
}
/*
NewStopwatch returns a new Stopwatch pointing to the same Experiment as this Stopwatch
*/
func (s *Stopwatch) NewStopwatch() *Stopwatch {
return newStopwatch(s.Experiment)
}
/*
Record captures the amount of time that has passed since the Stopwatch was created or most recently Reset(). It records the duration on it's associated Experiment in a Measurement with the passed-in name.
Record takes all the decorators that experiment.RecordDuration takes (e.g. Annotation("...") can be used to annotate this duration)
Note that Record does not Reset the Stopwatch. It does, however, return the Stopwatch so the following pattern is common:
stopwatch := experiment.NewStopwatch()
// first expensive operation
stopwatch.Record("first operation").Reset() //records the duration of the first operation and resets the stopwatch.
// second expensive operation
stopwatch.Record("second operation").Reset() //records the duration of the second operation and resets the stopwatch.
omitting the Reset() after the first operation would cause the duration recorded for the second operation to include the time elapsed by both the first _and_ second operations.
The Stopwatch must be running (i.e. not paused) when Record is called.
*/
func (s *Stopwatch) Record(name string, args ...interface{}) *Stopwatch {
if !s.running {
panic("stopwatch is not running - call Resume or Reset before calling Record")
}
duration := time.Since(s.t) - s.pauseDuration
s.Experiment.RecordDuration(name, duration, args...)
return s
}
/*
Reset resets the Stopwatch. Subsequent recorded durations will measure the time elapsed from the moment Reset was called.
If the Stopwatch was Paused it is unpaused after calling Reset.
*/
func (s *Stopwatch) Reset() *Stopwatch {
s.running = true
s.t = time.Now()
s.pauseDuration = 0
return s
}
/*
Pause pauses the Stopwatch. While pasued the Stopwatch does not accumulate elapsed time. This is useful for ignoring expensive operations that are incidental to the behavior you are attempting to characterize.
Note: You must call Resume() before you can Record() subsequent measurements.
For example:
stopwatch := experiment.NewStopwatch()
// first expensive operation
stopwatch.Record("first operation").Reset()
// second expensive operation - part 1
stopwatch.Pause()
// something expensive that we don't care about
stopwatch.Resume()
// second expensive operation - part 2
stopwatch.Record("second operation").Reset() // the recorded duration captures the time elapsed during parts 1 and 2 of the second expensive operation, but not the bit in between
The Stopwatch must be running when Pause is called.
*/
func (s *Stopwatch) Pause() *Stopwatch {
if !s.running {
panic("stopwatch is not running - call Resume or Reset before calling Pause")
}
s.running = false
s.pauseT = time.Now()
return s
}
/*
Resume resumes a paused Stopwatch. Any time that elapses after Resume is called will be accumulated as elapsed time when a subsequent duration is Recorded.
The Stopwatch must be Paused when Resume is called
*/
func (s *Stopwatch) Resume() *Stopwatch {
if s.running {
panic("stopwatch is running - call Pause before calling Resume")
}
s.running = true
s.pauseDuration = s.pauseDuration + time.Since(s.pauseT)
return s
}
golang-gomega-1.27.10/gmeasure/stopwatch_test.go 0000664 0000000 0000000 00000004135 14462163431 0021607 0 ustar 00root root 0000000 0000000 package gmeasure_test
import (
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"github.com/onsi/gomega/gmeasure"
)
var _ = Describe("Stopwatch", func() {
var e *gmeasure.Experiment
var stopwatch *gmeasure.Stopwatch
BeforeEach(func() {
e = gmeasure.NewExperiment("My Test Experiment")
stopwatch = e.NewStopwatch()
})
It("records durations", func() {
time.Sleep(100 * time.Millisecond)
stopwatch.Record("recordings", gmeasure.Annotation("A"))
time.Sleep(100 * time.Millisecond)
stopwatch.Record("recordings", gmeasure.Annotation("B")).Reset()
time.Sleep(100 * time.Millisecond)
stopwatch.Record("recordings", gmeasure.Annotation("C")).Reset()
time.Sleep(100 * time.Millisecond)
stopwatch.Pause()
time.Sleep(100 * time.Millisecond)
stopwatch.Resume()
time.Sleep(100 * time.Millisecond)
stopwatch.Pause()
time.Sleep(100 * time.Millisecond)
stopwatch.Resume()
time.Sleep(100 * time.Millisecond)
stopwatch.Record("recordings", gmeasure.Annotation("D"))
durations := e.Get("recordings").Durations
annotations := e.Get("recordings").Annotations
Ω(annotations).Should(Equal([]string{"A", "B", "C", "D"}))
Ω(durations[0]).Should(BeNumerically("~", 100*time.Millisecond, 50*time.Millisecond))
Ω(durations[1]).Should(BeNumerically("~", 200*time.Millisecond, 50*time.Millisecond))
Ω(durations[2]).Should(BeNumerically("~", 100*time.Millisecond, 50*time.Millisecond))
Ω(durations[3]).Should(BeNumerically("~", 300*time.Millisecond, 50*time.Millisecond))
})
It("panics when asked to record but not running", func() {
stopwatch.Pause()
Ω(func() {
stopwatch.Record("A")
}).Should(PanicWith("stopwatch is not running - call Resume or Reset before calling Record"))
})
It("panics when paused but not running", func() {
stopwatch.Pause()
Ω(func() {
stopwatch.Pause()
}).Should(PanicWith("stopwatch is not running - call Resume or Reset before calling Pause"))
})
It("panics when asked to resume but not paused", func() {
Ω(func() {
stopwatch.Resume()
}).Should(PanicWith("stopwatch is running - call Pause before calling Resume"))
})
})
golang-gomega-1.27.10/gmeasure/table/ 0000775 0000000 0000000 00000000000 14462163431 0017271 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gmeasure/table/table.go 0000664 0000000 0000000 00000020311 14462163431 0020704 0 ustar 00root root 0000000 0000000 package table
// This is a temporary package - Table will move to github.com/onsi/consolable once some more dust settles
import (
"reflect"
"strings"
"unicode/utf8"
)
type AlignType uint
const (
AlignTypeLeft AlignType = iota
AlignTypeCenter
AlignTypeRight
)
type Divider string
type Row struct {
Cells []Cell
Divider string
Style string
}
func R(args ...interface{}) *Row {
r := &Row{
Divider: "-",
}
for _, arg := range args {
switch reflect.TypeOf(arg) {
case reflect.TypeOf(Divider("")):
r.Divider = string(arg.(Divider))
case reflect.TypeOf(r.Style):
r.Style = arg.(string)
case reflect.TypeOf(Cell{}):
r.Cells = append(r.Cells, arg.(Cell))
}
}
return r
}
func (r *Row) AppendCell(cells ...Cell) *Row {
r.Cells = append(r.Cells, cells...)
return r
}
func (r *Row) Render(widths []int, totalWidth int, tableStyle TableStyle, isLastRow bool) string {
out := ""
if len(r.Cells) == 1 {
out += strings.Join(r.Cells[0].render(totalWidth, r.Style, tableStyle), "\n") + "\n"
} else {
if len(r.Cells) != len(widths) {
panic("row vs width mismatch")
}
renderedCells := make([][]string, len(r.Cells))
maxHeight := 0
for colIdx, cell := range r.Cells {
renderedCells[colIdx] = cell.render(widths[colIdx], r.Style, tableStyle)
if len(renderedCells[colIdx]) > maxHeight {
maxHeight = len(renderedCells[colIdx])
}
}
for colIdx := range r.Cells {
for len(renderedCells[colIdx]) < maxHeight {
renderedCells[colIdx] = append(renderedCells[colIdx], strings.Repeat(" ", widths[colIdx]))
}
}
border := strings.Repeat(" ", tableStyle.Padding)
if tableStyle.VerticalBorders {
border += "|" + border
}
for lineIdx := 0; lineIdx < maxHeight; lineIdx++ {
for colIdx := range r.Cells {
out += renderedCells[colIdx][lineIdx]
if colIdx < len(r.Cells)-1 {
out += border
}
}
out += "\n"
}
}
if tableStyle.HorizontalBorders && !isLastRow && r.Divider != "" {
out += strings.Repeat(string(r.Divider), totalWidth) + "\n"
}
return out
}
type Cell struct {
Contents []string
Style string
Align AlignType
}
func C(contents string, args ...interface{}) Cell {
c := Cell{
Contents: strings.Split(contents, "\n"),
}
for _, arg := range args {
switch reflect.TypeOf(arg) {
case reflect.TypeOf(c.Style):
c.Style = arg.(string)
case reflect.TypeOf(c.Align):
c.Align = arg.(AlignType)
}
}
return c
}
func (c Cell) Width() (int, int) {
w, minW := 0, 0
for _, line := range c.Contents {
lineWidth := utf8.RuneCountInString(line)
if lineWidth > w {
w = lineWidth
}
for _, word := range strings.Split(line, " ") {
wordWidth := utf8.RuneCountInString(word)
if wordWidth > minW {
minW = wordWidth
}
}
}
return w, minW
}
func (c Cell) alignLine(line string, width int) string {
lineWidth := utf8.RuneCountInString(line)
if lineWidth == width {
return line
}
if lineWidth < width {
gap := width - lineWidth
switch c.Align {
case AlignTypeLeft:
return line + strings.Repeat(" ", gap)
case AlignTypeRight:
return strings.Repeat(" ", gap) + line
case AlignTypeCenter:
leftGap := gap / 2
rightGap := gap - leftGap
return strings.Repeat(" ", leftGap) + line + strings.Repeat(" ", rightGap)
}
}
return line
}
func (c Cell) splitWordToWidth(word string, width int) []string {
out := []string{}
n, subWord := 0, ""
for _, c := range word {
subWord += string(c)
n += 1
if n == width-1 {
out = append(out, subWord+"-")
n, subWord = 0, ""
}
}
return out
}
func (c Cell) splitToWidth(line string, width int) []string {
lineWidth := utf8.RuneCountInString(line)
if lineWidth <= width {
return []string{line}
}
outLines := []string{}
words := strings.Split(line, " ")
outWords := []string{words[0]}
length := utf8.RuneCountInString(words[0])
if length > width {
splitWord := c.splitWordToWidth(words[0], width)
lastIdx := len(splitWord) - 1
outLines = append(outLines, splitWord[:lastIdx]...)
outWords = []string{splitWord[lastIdx]}
length = utf8.RuneCountInString(splitWord[lastIdx])
}
for _, word := range words[1:] {
wordLength := utf8.RuneCountInString(word)
if length+wordLength+1 <= width {
length += wordLength + 1
outWords = append(outWords, word)
continue
}
outLines = append(outLines, strings.Join(outWords, " "))
outWords = []string{word}
length = wordLength
if length > width {
splitWord := c.splitWordToWidth(word, width)
lastIdx := len(splitWord) - 1
outLines = append(outLines, splitWord[:lastIdx]...)
outWords = []string{splitWord[lastIdx]}
length = utf8.RuneCountInString(splitWord[lastIdx])
}
}
if len(outWords) > 0 {
outLines = append(outLines, strings.Join(outWords, " "))
}
return outLines
}
func (c Cell) render(width int, style string, tableStyle TableStyle) []string {
out := []string{}
for _, line := range c.Contents {
out = append(out, c.splitToWidth(line, width)...)
}
for idx := range out {
out[idx] = c.alignLine(out[idx], width)
}
if tableStyle.EnableTextStyling {
style = style + c.Style
if style != "" {
for idx := range out {
out[idx] = style + out[idx] + "{{/}}"
}
}
}
return out
}
type TableStyle struct {
Padding int
VerticalBorders bool
HorizontalBorders bool
MaxTableWidth int
MaxColWidth int
EnableTextStyling bool
}
var DefaultTableStyle = TableStyle{
Padding: 1,
VerticalBorders: true,
HorizontalBorders: true,
MaxTableWidth: 120,
MaxColWidth: 40,
EnableTextStyling: true,
}
type Table struct {
Rows []*Row
TableStyle TableStyle
}
func NewTable() *Table {
return &Table{
TableStyle: DefaultTableStyle,
}
}
func (t *Table) AppendRow(row *Row) *Table {
t.Rows = append(t.Rows, row)
return t
}
func (t *Table) Render() string {
out := ""
totalWidth, widths := t.computeWidths()
for rowIdx, row := range t.Rows {
out += row.Render(widths, totalWidth, t.TableStyle, rowIdx == len(t.Rows)-1)
}
return out
}
func (t *Table) computeWidths() (int, []int) {
nCol := 0
for _, row := range t.Rows {
if len(row.Cells) > nCol {
nCol = len(row.Cells)
}
}
// lets compute the contribution to width from the borders + padding
borderWidth := t.TableStyle.Padding
if t.TableStyle.VerticalBorders {
borderWidth += 1 + t.TableStyle.Padding
}
totalBorderWidth := borderWidth * (nCol - 1)
// lets compute the width of each column
widths := make([]int, nCol)
minWidths := make([]int, nCol)
for colIdx := range widths {
for _, row := range t.Rows {
if colIdx >= len(row.Cells) {
// ignore rows with fewer columns
continue
}
w, minWid := row.Cells[colIdx].Width()
if w > widths[colIdx] {
widths[colIdx] = w
}
if minWid > minWidths[colIdx] {
minWidths[colIdx] = minWid
}
}
}
// do we already fit?
if sum(widths)+totalBorderWidth <= t.TableStyle.MaxTableWidth {
// yes! we're done
return sum(widths) + totalBorderWidth, widths
}
// clamp the widths and minWidths to MaxColWidth
for colIdx := range widths {
widths[colIdx] = min(widths[colIdx], t.TableStyle.MaxColWidth)
minWidths[colIdx] = min(minWidths[colIdx], t.TableStyle.MaxColWidth)
}
// do we fit now?
if sum(widths)+totalBorderWidth <= t.TableStyle.MaxTableWidth {
// yes! we're done
return sum(widths) + totalBorderWidth, widths
}
// hmm... still no... can we possibly squeeze the table in without violating minWidths?
if sum(minWidths)+totalBorderWidth >= t.TableStyle.MaxTableWidth {
// nope - we're just going to have to exceed MaxTableWidth
return sum(minWidths) + totalBorderWidth, minWidths
}
// looks like we don't fit yet, but we should be able to fit without violating minWidths
// lets start scaling down
n := 0
for sum(widths)+totalBorderWidth > t.TableStyle.MaxTableWidth {
budget := t.TableStyle.MaxTableWidth - totalBorderWidth
baseline := sum(widths)
for colIdx := range widths {
widths[colIdx] = max((widths[colIdx]*budget)/baseline, minWidths[colIdx])
}
n += 1
if n > 100 {
break // in case we somehow fail to converge
}
}
return sum(widths) + totalBorderWidth, widths
}
func sum(s []int) int {
out := 0
for _, v := range s {
out += v
}
return out
}
func min(a int, b int) int {
if a < b {
return a
}
return b
}
func max(a int, b int) int {
if a > b {
return a
}
return b
}
golang-gomega-1.27.10/go.mod 0000664 0000000 0000000 00000001101 14462163431 0015471 0 ustar 00root root 0000000 0000000 module github.com/onsi/gomega
go 1.18
require (
github.com/golang/protobuf v1.5.3
github.com/google/go-cmp v0.5.9
github.com/onsi/ginkgo/v2 v2.11.0
golang.org/x/net v0.12.0
gopkg.in/yaml.v3 v3.0.1
)
require (
github.com/go-logr/logr v1.2.4 // indirect
github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 // indirect
github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38 // indirect
golang.org/x/sys v0.10.0 // indirect
golang.org/x/text v0.11.0 // indirect
golang.org/x/tools v0.9.3 // indirect
google.golang.org/protobuf v1.28.0 // indirect
)
golang-gomega-1.27.10/go.sum 0000664 0000000 0000000 00000010117 14462163431 0015525 0 ustar 00root root 0000000 0000000 github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/go-logr/logr v1.2.4 h1:g01GSCwiDw2xSZfjJ2/T9M+S6pFdcNtFYsp+Y43HYDQ=
github.com/go-logr/logr v1.2.4/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 h1:tfuBGBXKqDEevZMzYi5KSi8KkcZtzBcTgAUUtapy0OI=
github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572/go.mod h1:9Pwr4B2jHnOSGXyyzV8ROjYa2ojvAY6HCGYYfMoC3Ls=
github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
github.com/golang/protobuf v1.5.3 h1:KhyjKVUg7Usr/dYsdSqoFveMYd5ko72D+zANwlG1mmg=
github.com/golang/protobuf v1.5.3/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38 h1:yAJXTCF9TqKcTiHJAE8dj7HMvPfh66eeA2JYW7eFpSE=
github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE=
github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
github.com/onsi/ginkgo/v2 v2.11.0 h1:WgqUCUt/lT6yXoQ8Wef0fsNn5cAuMK7+KT9UFRz2tcU=
github.com/onsi/ginkgo/v2 v2.11.0/go.mod h1:ZhrRA5XmEE3x3rhlzamx/JJvujdZoJ2uvgI7kR0iZvM=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/testify v1.6.1 h1:hDPOHmpOpP40lSULcqw7IrRb/u7w6RpDC9399XyoNd0=
github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
golang.org/x/mod v0.10.0 h1:lFO9qtOdlre5W1jxS3r/4szv2/6iXxScdzjoBMXNhYk=
golang.org/x/net v0.12.0 h1:cfawfvKITfUsFCeJIHJrbSxpeu/E81khclypR0GVT50=
golang.org/x/net v0.12.0/go.mod h1:zEVYFnQC7m/vmpQFELhcD1EWkZlX69l4oqgmer6hfKA=
golang.org/x/sys v0.0.0-20191204072324-ce4227a45e2e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.10.0 h1:SqMFp9UcQJZa+pmYuAKjd9xq1f0j5rLcDIk0mj4qAsA=
golang.org/x/sys v0.10.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/text v0.11.0 h1:LAntKIrcmeSKERyiOh0XMV39LXS8IE9UL2yP7+f5ij4=
golang.org/x/text v0.11.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
golang.org/x/tools v0.9.3 h1:Gn1I8+64MsuTb/HpH+LmQtNas23LhUVr3rYZ0eKuaMM=
golang.org/x/tools v0.9.3/go.mod h1:owI94Op576fPu3cIGQeHs3joujW/2Oc6MtlxbF5dfNc=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
google.golang.org/protobuf v1.28.0 h1:w43yiav+6bVFTBQFZX0r7ipe9JQ1QsbMgHwbBziscLw=
google.golang.org/protobuf v1.28.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
golang-gomega-1.27.10/gomega_dsl.go 0000664 0000000 0000000 00000062331 14462163431 0017027 0 ustar 00root root 0000000 0000000 /*
Gomega is the Ginkgo BDD-style testing framework's preferred matcher library.
The godoc documentation describes Gomega's API. More comprehensive documentation (with examples!) is available at http://onsi.github.io/gomega/
Gomega on Github: http://github.com/onsi/gomega
Learn more about Ginkgo online: http://onsi.github.io/ginkgo
Ginkgo on Github: http://github.com/onsi/ginkgo
Gomega is MIT-Licensed
*/
package gomega
import (
"errors"
"fmt"
"time"
"github.com/onsi/gomega/internal"
"github.com/onsi/gomega/types"
)
const GOMEGA_VERSION = "1.27.10"
const nilGomegaPanic = `You are trying to make an assertion, but haven't registered Gomega's fail handler.
If you're using Ginkgo then you probably forgot to put your assertion in an It().
Alternatively, you may have forgotten to register a fail handler with RegisterFailHandler() or RegisterTestingT().
Depending on your vendoring solution you may be inadvertently importing gomega and subpackages (e.g. ghhtp, gexec,...) from different locations.
`
// Gomega describes the essential Gomega DSL. This interface allows libraries
// to abstract between the standard package-level function implementations
// and alternatives like *WithT.
//
// The types in the top-level DSL have gotten a bit messy due to earlier deprecations that avoid stuttering
// and due to an accidental use of a concrete type (*WithT) in an earlier release.
//
// As of 1.15 both the WithT and Ginkgo variants of Gomega are implemented by the same underlying object
// however one (the Ginkgo variant) is exported as an interface (types.Gomega) whereas the other (the withT variant)
// is shared as a concrete type (*WithT, which is aliased to *internal.Gomega). 1.15 did not clean this mess up to ensure
// that declarations of *WithT in existing code are not broken by the upgrade to 1.15.
type Gomega = types.Gomega
// DefaultGomega supplies the standard package-level implementation
var Default = Gomega(internal.NewGomega(internal.FetchDefaultDurationBundle()))
// NewGomega returns an instance of Gomega wired into the passed-in fail handler.
// You generally don't need to use this when using Ginkgo - RegisterFailHandler will wire up the global gomega
// However creating a NewGomega with a custom fail handler can be useful in contexts where you want to use Gomega's
// rich ecosystem of matchers without causing a test to fail. For example, to aggregate a series of potential failures
// or for use in a non-test setting.
func NewGomega(fail types.GomegaFailHandler) Gomega {
return internal.NewGomega(internalGomega(Default).DurationBundle).ConfigureWithFailHandler(fail)
}
// WithT wraps a *testing.T and provides `Expect`, `Eventually`, and `Consistently` methods. This allows you to leverage
// Gomega's rich ecosystem of matchers in standard `testing` test suites.
//
// Use `NewWithT` to instantiate a `WithT`
//
// As of 1.15 both the WithT and Ginkgo variants of Gomega are implemented by the same underlying object
// however one (the Ginkgo variant) is exported as an interface (types.Gomega) whereas the other (the withT variant)
// is shared as a concrete type (*WithT, which is aliased to *internal.Gomega). 1.15 did not clean this mess up to ensure
// that declarations of *WithT in existing code are not broken by the upgrade to 1.15.
type WithT = internal.Gomega
// GomegaWithT is deprecated in favor of gomega.WithT, which does not stutter.
type GomegaWithT = WithT
// inner is an interface that allows users to provide a wrapper around Default. The wrapper
// must implement the inner interface and return either the original Default or the result of
// a call to NewGomega().
type inner interface {
Inner() Gomega
}
func internalGomega(g Gomega) *internal.Gomega {
if v, ok := g.(inner); ok {
return v.Inner().(*internal.Gomega)
}
return g.(*internal.Gomega)
}
// NewWithT takes a *testing.T and returns a `gomega.WithT` allowing you to use `Expect`, `Eventually`, and `Consistently` along with
// Gomega's rich ecosystem of matchers in standard `testing` test suits.
//
// func TestFarmHasCow(t *testing.T) {
// g := gomega.NewWithT(t)
//
// f := farm.New([]string{"Cow", "Horse"})
// g.Expect(f.HasCow()).To(BeTrue(), "Farm should have cow")
// }
func NewWithT(t types.GomegaTestingT) *WithT {
return internal.NewGomega(internalGomega(Default).DurationBundle).ConfigureWithT(t)
}
// NewGomegaWithT is deprecated in favor of gomega.NewWithT, which does not stutter.
var NewGomegaWithT = NewWithT
// RegisterFailHandler connects Ginkgo to Gomega. When a matcher fails
// the fail handler passed into RegisterFailHandler is called.
func RegisterFailHandler(fail types.GomegaFailHandler) {
internalGomega(Default).ConfigureWithFailHandler(fail)
}
// RegisterFailHandlerWithT is deprecated and will be removed in a future release.
// users should use RegisterFailHandler, or RegisterTestingT
func RegisterFailHandlerWithT(_ types.GomegaTestingT, fail types.GomegaFailHandler) {
fmt.Println("RegisterFailHandlerWithT is deprecated. Please use RegisterFailHandler or RegisterTestingT instead.")
internalGomega(Default).ConfigureWithFailHandler(fail)
}
// RegisterTestingT connects Gomega to Golang's XUnit style
// Testing.T tests. It is now deprecated and you should use NewWithT() instead to get a fresh instance of Gomega for each test.
func RegisterTestingT(t types.GomegaTestingT) {
internalGomega(Default).ConfigureWithT(t)
}
// InterceptGomegaFailures runs a given callback and returns an array of
// failure messages generated by any Gomega assertions within the callback.
// Execution continues after the first failure allowing users to collect all failures
// in the callback.
//
// This is most useful when testing custom matchers, but can also be used to check
// on a value using a Gomega assertion without causing a test failure.
func InterceptGomegaFailures(f func()) []string {
originalHandler := internalGomega(Default).Fail
failures := []string{}
internalGomega(Default).Fail = func(message string, callerSkip ...int) {
failures = append(failures, message)
}
defer func() {
internalGomega(Default).Fail = originalHandler
}()
f()
return failures
}
// InterceptGomegaFailure runs a given callback and returns the first
// failure message generated by any Gomega assertions within the callback, wrapped in an error.
//
// The callback ceases execution as soon as the first failed assertion occurs, however Gomega
// does not register a failure with the FailHandler registered via RegisterFailHandler - it is up
// to the user to decide what to do with the returned error
func InterceptGomegaFailure(f func()) (err error) {
originalHandler := internalGomega(Default).Fail
internalGomega(Default).Fail = func(message string, callerSkip ...int) {
err = errors.New(message)
panic("stop execution")
}
defer func() {
internalGomega(Default).Fail = originalHandler
if e := recover(); e != nil {
if err == nil {
panic(e)
}
}
}()
f()
return err
}
func ensureDefaultGomegaIsConfigured() {
if !internalGomega(Default).IsConfigured() {
panic(nilGomegaPanic)
}
}
// Ω wraps an actual value allowing assertions to be made on it:
//
// Ω("foo").Should(Equal("foo"))
//
// If Ω is passed more than one argument it will pass the *first* argument to the matcher.
// All subsequent arguments will be required to be nil/zero.
//
// This is convenient if you want to make an assertion on a method/function that returns
// a value and an error - a common patter in Go.
//
// For example, given a function with signature:
//
// func MyAmazingThing() (int, error)
//
// Then:
//
// Ω(MyAmazingThing()).Should(Equal(3))
//
// Will succeed only if `MyAmazingThing()` returns `(3, nil)`
//
// Ω and Expect are identical
func Ω(actual interface{}, extra ...interface{}) Assertion {
ensureDefaultGomegaIsConfigured()
return Default.Ω(actual, extra...)
}
// Expect wraps an actual value allowing assertions to be made on it:
//
// Expect("foo").To(Equal("foo"))
//
// If Expect is passed more than one argument it will pass the *first* argument to the matcher.
// All subsequent arguments will be required to be nil/zero.
//
// This is convenient if you want to make an assertion on a method/function that returns
// a value and an error - a common pattern in Go.
//
// For example, given a function with signature:
//
// func MyAmazingThing() (int, error)
//
// Then:
//
// Expect(MyAmazingThing()).Should(Equal(3))
//
// Will succeed only if `MyAmazingThing()` returns `(3, nil)`
//
// Expect and Ω are identical
func Expect(actual interface{}, extra ...interface{}) Assertion {
ensureDefaultGomegaIsConfigured()
return Default.Expect(actual, extra...)
}
// ExpectWithOffset wraps an actual value allowing assertions to be made on it:
//
// ExpectWithOffset(1, "foo").To(Equal("foo"))
//
// Unlike `Expect` and `Ω`, `ExpectWithOffset` takes an additional integer argument
// that is used to modify the call-stack offset when computing line numbers. It is
// the same as `Expect(...).WithOffset`.
//
// This is most useful in helper functions that make assertions. If you want Gomega's
// error message to refer to the calling line in the test (as opposed to the line in the helper function)
// set the first argument of `ExpectWithOffset` appropriately.
func ExpectWithOffset(offset int, actual interface{}, extra ...interface{}) Assertion {
ensureDefaultGomegaIsConfigured()
return Default.ExpectWithOffset(offset, actual, extra...)
}
/*
Eventually enables making assertions on asynchronous behavior.
Eventually checks that an assertion *eventually* passes. Eventually blocks when called and attempts an assertion periodically until it passes or a timeout occurs. Both the timeout and polling interval are configurable as optional arguments.
The first optional argument is the timeout (which defaults to 1s), the second is the polling interval (which defaults to 10ms). Both intervals can be specified as time.Duration, parsable duration strings or floats/integers (in which case they are interpreted as seconds). In addition an optional context.Context can be passed in - Eventually will keep trying until either the timeout epxires or the context is cancelled, whichever comes first.
Eventually works with any Gomega compatible matcher and supports making assertions against three categories of actual value:
**Category 1: Making Eventually assertions on values**
There are several examples of values that can change over time. These can be passed in to Eventually and will be passed to the matcher repeatedly until a match occurs. For example:
c := make(chan bool)
go DoStuff(c)
Eventually(c, "50ms").Should(BeClosed())
will poll the channel repeatedly until it is closed. In this example `Eventually` will block until either the specified timeout of 50ms has elapsed or the channel is closed, whichever comes first.
Several Gomega libraries allow you to use Eventually in this way. For example, the gomega/gexec package allows you to block until a *gexec.Session exits successfully via:
Eventually(session).Should(gexec.Exit(0))
And the gomega/gbytes package allows you to monitor a streaming *gbytes.Buffer until a given string is seen:
Eventually(buffer).Should(gbytes.Say("hello there"))
In these examples, both `session` and `buffer` are designed to be thread-safe when polled by the `Exit` and `Say` matchers. This is not true in general of most raw values, so while it is tempting to do something like:
// THIS IS NOT THREAD-SAFE
var s *string
go mutateStringEventually(s)
Eventually(s).Should(Equal("I've changed"))
this will trigger Go's race detector as the goroutine polling via Eventually will race over the value of s with the goroutine mutating the string. For cases like this you can use channels or introduce your own locking around s by passing Eventually a function.
**Category 2: Make Eventually assertions on functions**
Eventually can be passed functions that **return at least one value**. When configured this way, Eventually will poll the function repeatedly and pass the first returned value to the matcher.
For example:
Eventually(func() int {
return client.FetchCount()
}).Should(BeNumerically(">=", 17))
will repeatedly poll client.FetchCount until the BeNumerically matcher is satisfied. (Note that this example could have been written as Eventually(client.FetchCount).Should(BeNumerically(">=", 17)))
If multiple values are returned by the function, Eventually will pass the first value to the matcher and require that all others are zero-valued. This allows you to pass Eventually a function that returns a value and an error - a common pattern in Go.
For example, consider a method that returns a value and an error:
func FetchFromDB() (string, error)
Then
Eventually(FetchFromDB).Should(Equal("got it"))
will pass only if and when the returned error is nil *and* the returned string satisfies the matcher.
Eventually can also accept functions that take arguments, however you must provide those arguments using .WithArguments(). For example, consider a function that takes a user-id and makes a network request to fetch a full name:
func FetchFullName(userId int) (string, error)
You can poll this function like so:
Eventually(FetchFullName).WithArguments(1138).Should(Equal("Wookie"))
It is important to note that the function passed into Eventually is invoked *synchronously* when polled. Eventually does not (in fact, it cannot) kill the function if it takes longer to return than Eventually's configured timeout. A common practice here is to use a context. Here's an example that combines Ginkgo's spec timeout support with Eventually:
It("fetches the correct count", func(ctx SpecContext) {
Eventually(ctx, func() int {
return client.FetchCount(ctx, "/users")
}).Should(BeNumerically(">=", 17))
}, SpecTimeout(time.Second))
you an also use Eventually().WithContext(ctx) to pass in the context. Passed-in contexts play nicely with paseed-in arguments as long as the context appears first. You can rewrite the above example as:
It("fetches the correct count", func(ctx SpecContext) {
Eventually(client.FetchCount).WithContext(ctx).WithArguments("/users").Should(BeNumerically(">=", 17))
}, SpecTimeout(time.Second))
Either way the context passd to Eventually is also passed to the underlying funciton. Now, when Ginkgo cancels the context both the FetchCount client and Gomega will be informed and can exit.
**Category 3: Making assertions _in_ the function passed into Eventually**
When testing complex systems it can be valuable to assert that a _set_ of assertions passes Eventually. Eventually supports this by accepting functions that take a single Gomega argument and return zero or more values.
Here's an example that makes some assertions and returns a value and error:
Eventually(func(g Gomega) (Widget, error) {
ids, err := client.FetchIDs()
g.Expect(err).NotTo(HaveOccurred())
g.Expect(ids).To(ContainElement(1138))
return client.FetchWidget(1138)
}).Should(Equal(expectedWidget))
will pass only if all the assertions in the polled function pass and the return value satisfied the matcher.
Eventually also supports a special case polling function that takes a single Gomega argument and returns no values. Eventually assumes such a function is making assertions and is designed to work with the Succeed matcher to validate that all assertions have passed.
For example:
Eventually(func(g Gomega) {
model, err := client.Find(1138)
g.Expect(err).NotTo(HaveOccurred())
g.Expect(model.Reticulate()).To(Succeed())
g.Expect(model.IsReticulated()).To(BeTrue())
g.Expect(model.Save()).To(Succeed())
}).Should(Succeed())
will rerun the function until all assertions pass.
You can also pass additional arugments to functions that take a Gomega. The only rule is that the Gomega argument must be first. If you also want to pass the context attached to Eventually you must ensure that is the second argument. For example:
Eventually(func(g Gomega, ctx context.Context, path string, expected ...string){
tok, err := client.GetToken(ctx)
g.Expect(err).NotTo(HaveOccurred())
elements, err := client.Fetch(ctx, tok, path)
g.Expect(err).NotTo(HaveOccurred())
g.Expect(elements).To(ConsistOf(expected))
}).WithContext(ctx).WithArguments("/names", "Joe", "Jane", "Sam").Should(Succeed())
You can ensure that you get a number of consecutive successful tries before succeeding using `MustPassRepeatedly(int)`. For Example:
int count := 0
Eventually(func() bool {
count++
return count > 2
}).MustPassRepeatedly(2).Should(BeTrue())
// Because we had to wait for 2 calls that returned true
Expect(count).To(Equal(3))
Finally, in addition to passing timeouts and a context to Eventually you can be more explicit with Eventually's chaining configuration methods:
Eventually(..., "1s", "2s", ctx).Should(...)
is equivalent to
Eventually(...).WithTimeout(time.Second).WithPolling(2*time.Second).WithContext(ctx).Should(...)
*/
func Eventually(actualOrCtx interface{}, args ...interface{}) AsyncAssertion {
ensureDefaultGomegaIsConfigured()
return Default.Eventually(actualOrCtx, args...)
}
// EventuallyWithOffset operates like Eventually but takes an additional
// initial argument to indicate an offset in the call stack. This is useful when building helper
// functions that contain matchers. To learn more, read about `ExpectWithOffset`.
//
// `EventuallyWithOffset` is the same as `Eventually(...).WithOffset`.
//
// `EventuallyWithOffset` specifying a timeout interval (and an optional polling interval) are
// the same as `Eventually(...).WithOffset(...).WithTimeout` or
// `Eventually(...).WithOffset(...).WithTimeout(...).WithPolling`.
func EventuallyWithOffset(offset int, actualOrCtx interface{}, args ...interface{}) AsyncAssertion {
ensureDefaultGomegaIsConfigured()
return Default.EventuallyWithOffset(offset, actualOrCtx, args...)
}
/*
Consistently, like Eventually, enables making assertions on asynchronous behavior.
Consistently blocks when called for a specified duration. During that duration Consistently repeatedly polls its matcher and ensures that it is satisfied. If the matcher is consistently satisfied, then Consistently will pass. Otherwise Consistently will fail.
Both the total waiting duration and the polling interval are configurable as optional arguments. The first optional argument is the duration that Consistently will run for (defaults to 100ms), and the second argument is the polling interval (defaults to 10ms). As with Eventually, these intervals can be passed in as time.Duration, parsable duration strings or an integer or float number of seconds. You can also pass in an optional context.Context - Consistently will exit early (with a failure) if the context is cancelled before the waiting duration expires.
Consistently accepts the same three categories of actual as Eventually, check the Eventually docs to learn more.
Consistently is useful in cases where you want to assert that something *does not happen* for a period of time. For example, you may want to assert that a goroutine does *not* send data down a channel. In this case you could write:
Consistently(channel, "200ms").ShouldNot(Receive())
This will block for 200 milliseconds and repeatedly check the channel and ensure nothing has been received.
*/
func Consistently(actualOrCtx interface{}, args ...interface{}) AsyncAssertion {
ensureDefaultGomegaIsConfigured()
return Default.Consistently(actualOrCtx, args...)
}
// ConsistentlyWithOffset operates like Consistently but takes an additional
// initial argument to indicate an offset in the call stack. This is useful when building helper
// functions that contain matchers. To learn more, read about `ExpectWithOffset`.
//
// `ConsistentlyWithOffset` is the same as `Consistently(...).WithOffset` and
// optional `WithTimeout` and `WithPolling`.
func ConsistentlyWithOffset(offset int, actualOrCtx interface{}, args ...interface{}) AsyncAssertion {
ensureDefaultGomegaIsConfigured()
return Default.ConsistentlyWithOffset(offset, actualOrCtx, args...)
}
/*
StopTrying can be used to signal to Eventually and Consistentlythat they should abort and stop trying. This always results in a failure of the assertion - and the failure message is the content of the StopTrying signal.
You can send the StopTrying signal by either returning StopTrying("message") as an error from your passed-in function _or_ by calling StopTrying("message").Now() to trigger a panic and end execution.
You can also wrap StopTrying around an error with `StopTrying("message").Wrap(err)` and can attach additional objects via `StopTrying("message").Attach("description", object). When rendered, the signal will include the wrapped error and any attached objects rendered using Gomega's default formatting.
Here are a couple of examples. This is how you might use StopTrying() as an error to signal that Eventually should stop:
playerIndex, numPlayers := 0, 11
Eventually(func() (string, error) {
if playerIndex == numPlayers {
return "", StopTrying("no more players left")
}
name := client.FetchPlayer(playerIndex)
playerIndex += 1
return name, nil
}).Should(Equal("Patrick Mahomes"))
And here's an example where `StopTrying().Now()` is called to halt execution immediately:
Eventually(func() []string {
names, err := client.FetchAllPlayers()
if err == client.IRRECOVERABLE_ERROR {
StopTrying("Irrecoverable error occurred").Wrap(err).Now()
}
return names
}).Should(ContainElement("Patrick Mahomes"))
*/
var StopTrying = internal.StopTrying
/*
TryAgainAfter() allows you to adjust the polling interval for the _next_ iteration of `Eventually` or `Consistently`. Like `StopTrying` you can either return `TryAgainAfter` as an error or trigger it immedieately with `.Now()`
When `TryAgainAfter(` is triggered `Eventually` and `Consistently` will wait for that duration. If a timeout occurs before the next poll is triggered both `Eventually` and `Consistently` will always fail with the content of the TryAgainAfter message. As with StopTrying you can `.Wrap()` and error and `.Attach()` additional objects to `TryAgainAfter`.
*/
var TryAgainAfter = internal.TryAgainAfter
/*
PollingSignalError is the error returned by StopTrying() and TryAgainAfter()
*/
type PollingSignalError = internal.PollingSignalError
// SetDefaultEventuallyTimeout sets the default timeout duration for Eventually. Eventually will repeatedly poll your condition until it succeeds, or until this timeout elapses.
func SetDefaultEventuallyTimeout(t time.Duration) {
Default.SetDefaultEventuallyTimeout(t)
}
// SetDefaultEventuallyPollingInterval sets the default polling interval for Eventually.
func SetDefaultEventuallyPollingInterval(t time.Duration) {
Default.SetDefaultEventuallyPollingInterval(t)
}
// SetDefaultConsistentlyDuration sets the default duration for Consistently. Consistently will verify that your condition is satisfied for this long.
func SetDefaultConsistentlyDuration(t time.Duration) {
Default.SetDefaultConsistentlyDuration(t)
}
// SetDefaultConsistentlyPollingInterval sets the default polling interval for Consistently.
func SetDefaultConsistentlyPollingInterval(t time.Duration) {
Default.SetDefaultConsistentlyPollingInterval(t)
}
// AsyncAssertion is returned by Eventually and Consistently and polls the actual value passed into Eventually against
// the matcher passed to the Should and ShouldNot methods.
//
// Both Should and ShouldNot take a variadic optionalDescription argument.
// This argument allows you to make your failure messages more descriptive.
// If a single argument of type `func() string` is passed, this function will be lazily evaluated if a failure occurs
// and the returned string is used to annotate the failure message.
// Otherwise, this argument is passed on to fmt.Sprintf() and then used to annotate the failure message.
//
// Both Should and ShouldNot return a boolean that is true if the assertion passed and false if it failed.
//
// Example:
//
// Eventually(myChannel).Should(Receive(), "Something should have come down the pipe.")
// Consistently(myChannel).ShouldNot(Receive(), func() string { return "Nothing should have come down the pipe." })
type AsyncAssertion = types.AsyncAssertion
// GomegaAsyncAssertion is deprecated in favor of AsyncAssertion, which does not stutter.
type GomegaAsyncAssertion = types.AsyncAssertion
// Assertion is returned by Ω and Expect and compares the actual value to the matcher
// passed to the Should/ShouldNot and To/ToNot/NotTo methods.
//
// Typically Should/ShouldNot are used with Ω and To/ToNot/NotTo are used with Expect
// though this is not enforced.
//
// All methods take a variadic optionalDescription argument.
// This argument allows you to make your failure messages more descriptive.
// If a single argument of type `func() string` is passed, this function will be lazily evaluated if a failure occurs
// and the returned string is used to annotate the failure message.
// Otherwise, this argument is passed on to fmt.Sprintf() and then used to annotate the failure message.
//
// All methods return a bool that is true if the assertion passed and false if it failed.
//
// Example:
//
// Ω(farm.HasCow()).Should(BeTrue(), "Farm %v should have a cow", farm)
type Assertion = types.Assertion
// GomegaAssertion is deprecated in favor of Assertion, which does not stutter.
type GomegaAssertion = types.Assertion
// OmegaMatcher is deprecated in favor of the better-named and better-organized types.GomegaMatcher but sticks around to support existing code that uses it
type OmegaMatcher = types.GomegaMatcher
golang-gomega-1.27.10/gstruct/ 0000775 0000000 0000000 00000000000 14462163431 0016065 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gstruct/elements.go 0000664 0000000 0000000 00000015667 14462163431 0020247 0 ustar 00root root 0000000 0000000 // untested sections: 6
package gstruct
import (
"errors"
"fmt"
"reflect"
"runtime/debug"
"strconv"
"github.com/onsi/gomega/format"
errorsutil "github.com/onsi/gomega/gstruct/errors"
"github.com/onsi/gomega/types"
)
//MatchAllElements succeeds if every element of a slice matches the element matcher it maps to
//through the id function, and every element matcher is matched.
// idFn := func(element interface{}) string {
// return fmt.Sprintf("%v", element)
// }
//
// Expect([]string{"a", "b"}).To(MatchAllElements(idFn, Elements{
// "a": Equal("a"),
// "b": Equal("b"),
// }))
func MatchAllElements(identifier Identifier, elements Elements) types.GomegaMatcher {
return &ElementsMatcher{
Identifier: identifier,
Elements: elements,
}
}
//MatchAllElementsWithIndex succeeds if every element of a slice matches the element matcher it maps to
//through the id with index function, and every element matcher is matched.
// idFn := func(index int, element interface{}) string {
// return strconv.Itoa(index)
// }
//
// Expect([]string{"a", "b"}).To(MatchAllElements(idFn, Elements{
// "0": Equal("a"),
// "1": Equal("b"),
// }))
func MatchAllElementsWithIndex(identifier IdentifierWithIndex, elements Elements) types.GomegaMatcher {
return &ElementsMatcher{
Identifier: identifier,
Elements: elements,
}
}
//MatchElements succeeds if each element of a slice matches the element matcher it maps to
//through the id function. It can ignore extra elements and/or missing elements.
// idFn := func(element interface{}) string {
// return fmt.Sprintf("%v", element)
// }
//
// Expect([]string{"a", "b", "c"}).To(MatchElements(idFn, IgnoreExtras, Elements{
// "a": Equal("a"),
// "b": Equal("b"),
// }))
// Expect([]string{"a", "c"}).To(MatchElements(idFn, IgnoreMissing, Elements{
// "a": Equal("a"),
// "b": Equal("b"),
// "c": Equal("c"),
// "d": Equal("d"),
// }))
func MatchElements(identifier Identifier, options Options, elements Elements) types.GomegaMatcher {
return &ElementsMatcher{
Identifier: identifier,
Elements: elements,
IgnoreExtras: options&IgnoreExtras != 0,
IgnoreMissing: options&IgnoreMissing != 0,
AllowDuplicates: options&AllowDuplicates != 0,
}
}
//MatchElementsWithIndex succeeds if each element of a slice matches the element matcher it maps to
//through the id with index function. It can ignore extra elements and/or missing elements.
// idFn := func(index int, element interface{}) string {
// return strconv.Itoa(index)
// }
//
// Expect([]string{"a", "b", "c"}).To(MatchElements(idFn, IgnoreExtras, Elements{
// "0": Equal("a"),
// "1": Equal("b"),
// }))
// Expect([]string{"a", "c"}).To(MatchElements(idFn, IgnoreMissing, Elements{
// "0": Equal("a"),
// "1": Equal("b"),
// "2": Equal("c"),
// "3": Equal("d"),
// }))
func MatchElementsWithIndex(identifier IdentifierWithIndex, options Options, elements Elements) types.GomegaMatcher {
return &ElementsMatcher{
Identifier: identifier,
Elements: elements,
IgnoreExtras: options&IgnoreExtras != 0,
IgnoreMissing: options&IgnoreMissing != 0,
AllowDuplicates: options&AllowDuplicates != 0,
}
}
// ElementsMatcher is a NestingMatcher that applies custom matchers to each element of a slice mapped
// by the Identifier function.
// TODO: Extend this to work with arrays & maps (map the key) as well.
type ElementsMatcher struct {
// Matchers for each element.
Elements Elements
// Function mapping an element to the string key identifying its matcher.
Identifier Identify
// Whether to ignore extra elements or consider it an error.
IgnoreExtras bool
// Whether to ignore missing elements or consider it an error.
IgnoreMissing bool
// Whether to key duplicates when matching IDs.
AllowDuplicates bool
// State.
failures []error
}
// Element ID to matcher.
type Elements map[string]types.GomegaMatcher
// Function for identifying (mapping) elements.
type Identifier func(element interface{}) string
// Calls the underlying fucntion with the provided params.
// Identifier drops the index.
func (i Identifier) WithIndexAndElement(index int, element interface{}) string {
return i(element)
}
// Uses the index and element to generate an element name
type IdentifierWithIndex func(index int, element interface{}) string
// Calls the underlying fucntion with the provided params.
// IdentifierWithIndex uses the index.
func (i IdentifierWithIndex) WithIndexAndElement(index int, element interface{}) string {
return i(index, element)
}
// Interface for identifing the element
type Identify interface {
WithIndexAndElement(i int, element interface{}) string
}
// IndexIdentity is a helper function for using an index as
// the key in the element map
func IndexIdentity(index int, _ interface{}) string {
return strconv.Itoa(index)
}
func (m *ElementsMatcher) Match(actual interface{}) (success bool, err error) {
if reflect.TypeOf(actual).Kind() != reflect.Slice {
return false, fmt.Errorf("%v is type %T, expected slice", actual, actual)
}
m.failures = m.matchElements(actual)
if len(m.failures) > 0 {
return false, nil
}
return true, nil
}
func (m *ElementsMatcher) matchElements(actual interface{}) (errs []error) {
// Provide more useful error messages in the case of a panic.
defer func() {
if err := recover(); err != nil {
errs = append(errs, fmt.Errorf("panic checking %+v: %v\n%s", actual, err, debug.Stack()))
}
}()
val := reflect.ValueOf(actual)
elements := map[string]bool{}
for i := 0; i < val.Len(); i++ {
element := val.Index(i).Interface()
id := m.Identifier.WithIndexAndElement(i, element)
if elements[id] {
if !m.AllowDuplicates {
errs = append(errs, fmt.Errorf("found duplicate element ID %s", id))
continue
}
}
elements[id] = true
matcher, expected := m.Elements[id]
if !expected {
if !m.IgnoreExtras {
errs = append(errs, fmt.Errorf("unexpected element %s", id))
}
continue
}
match, err := matcher.Match(element)
if match {
continue
}
if err == nil {
if nesting, ok := matcher.(errorsutil.NestingMatcher); ok {
err = errorsutil.AggregateError(nesting.Failures())
} else {
err = errors.New(matcher.FailureMessage(element))
}
}
errs = append(errs, errorsutil.Nest(fmt.Sprintf("[%s]", id), err))
}
for id := range m.Elements {
if !elements[id] && !m.IgnoreMissing {
errs = append(errs, fmt.Errorf("missing expected element %s", id))
}
}
return errs
}
func (m *ElementsMatcher) FailureMessage(actual interface{}) (message string) {
failure := errorsutil.AggregateError(m.failures)
return format.Message(actual, fmt.Sprintf("to match elements: %v", failure))
}
func (m *ElementsMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, "not to match elements")
}
func (m *ElementsMatcher) Failures() []error {
return m.failures
}
golang-gomega-1.27.10/gstruct/elements_test.go 0000664 0000000 0000000 00000015132 14462163431 0021271 0 ustar 00root root 0000000 0000000 package gstruct_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/gstruct"
)
var _ = Describe("Slice", func() {
allElements := []string{"a", "b"}
missingElements := []string{"a"}
extraElements := []string{"a", "b", "c"}
duplicateElements := []string{"a", "a", "b"}
empty := []string{}
var nils []string
It("should strictly match all elements", func() {
m := MatchAllElements(id, Elements{
"b": Equal("b"),
"a": Equal("a"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(missingElements).ShouldNot(m, "should fail with missing elements")
Expect(extraElements).ShouldNot(m, "should fail with extra elements")
Expect(duplicateElements).ShouldNot(m, "should fail with duplicate elements")
Expect(nils).ShouldNot(m, "should fail with an uninitialized slice")
m = MatchAllElements(id, Elements{
"a": Equal("a"),
"b": Equal("fail"),
})
Expect(allElements).ShouldNot(m, "should run nested matchers")
m = MatchAllElements(id, Elements{})
Expect(empty).Should(m, "should handle empty slices")
Expect(allElements).ShouldNot(m, "should handle only empty slices")
Expect(nils).Should(m, "should handle nil slices")
})
It("should ignore extra elements", func() {
m := MatchElements(id, IgnoreExtras, Elements{
"b": Equal("b"),
"a": Equal("a"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(missingElements).ShouldNot(m, "should fail with missing elements")
Expect(extraElements).Should(m, "should ignore extra elements")
Expect(duplicateElements).ShouldNot(m, "should fail with duplicate elements")
Expect(nils).ShouldNot(m, "should fail with an uninitialized slice")
})
It("should ignore missing elements", func() {
m := MatchElements(id, IgnoreMissing, Elements{
"a": Equal("a"),
"b": Equal("b"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(missingElements).Should(m, "should ignore missing elements")
Expect(extraElements).ShouldNot(m, "should fail with extra elements")
Expect(duplicateElements).ShouldNot(m, "should fail with duplicate elements")
Expect(nils).Should(m, "should ignore an uninitialized slice")
})
It("should ignore missing and extra elements", func() {
m := MatchElements(id, IgnoreMissing|IgnoreExtras, Elements{
"a": Equal("a"),
"b": Equal("b"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(missingElements).Should(m, "should ignore missing elements")
Expect(extraElements).Should(m, "should ignore extra elements")
Expect(duplicateElements).ShouldNot(m, "should fail with duplicate elements")
Expect(nils).Should(m, "should ignore an uninitialized slice")
m = MatchElements(id, IgnoreExtras|IgnoreMissing, Elements{
"a": Equal("a"),
"b": Equal("fail"),
})
Expect(allElements).ShouldNot(m, "should run nested matchers")
})
Context("with elements that share a key", func() {
nonUniqueID := func(element interface{}) string {
return element.(string)[0:1]
}
allElements := []string{"a123", "a213", "b321"}
includingBadElements := []string{"a123", "b123", "b5555"}
extraElements := []string{"a123", "b1234", "c345"}
missingElements := []string{"b123", "b1234", "b1345"}
It("should strictly allow multiple matches", func() {
m := MatchElements(nonUniqueID, AllowDuplicates, Elements{
"a": ContainSubstring("1"),
"b": ContainSubstring("1"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(includingBadElements).ShouldNot(m, "should reject if a member fails the matcher")
Expect(extraElements).ShouldNot(m, "should reject with extra keys")
Expect(missingElements).ShouldNot(m, "should reject with missing keys")
Expect(nils).ShouldNot(m, "should fail with an uninitialized slice")
})
It("should ignore missing", func() {
m := MatchElements(nonUniqueID, AllowDuplicates|IgnoreMissing, Elements{
"a": ContainSubstring("1"),
"b": ContainSubstring("1"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(includingBadElements).ShouldNot(m, "should reject if a member fails the matcher")
Expect(extraElements).ShouldNot(m, "should reject with extra keys")
Expect(missingElements).Should(m, "should allow missing keys")
Expect(nils).Should(m, "should allow an uninitialized slice")
})
It("should ignore extras", func() {
m := MatchElements(nonUniqueID, AllowDuplicates|IgnoreExtras, Elements{
"a": ContainSubstring("1"),
"b": ContainSubstring("1"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(includingBadElements).ShouldNot(m, "should reject if a member fails the matcher")
Expect(extraElements).Should(m, "should allow extra keys")
Expect(missingElements).ShouldNot(m, "should reject missing keys")
Expect(nils).ShouldNot(m, "should reject an uninitialized slice")
})
It("should ignore missing and extras", func() {
m := MatchElements(nonUniqueID, AllowDuplicates|IgnoreExtras|IgnoreMissing, Elements{
"a": ContainSubstring("1"),
"b": ContainSubstring("1"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(includingBadElements).ShouldNot(m, "should reject if a member fails the matcher")
Expect(extraElements).Should(m, "should allow extra keys")
Expect(missingElements).Should(m, "should allow missing keys")
Expect(nils).Should(m, "should allow an uninitialized slice")
})
})
Context("with index identifier", func() {
allElements := []string{"a", "b"}
missingElements := []string{"a"}
extraElements := []string{"a", "b", "c"}
duplicateElements := []string{"a", "a", "b"}
empty := []string{}
var nils []string
It("should use index", func() {
m := MatchAllElementsWithIndex(IndexIdentity, Elements{
"0": Equal("a"),
"1": Equal("b"),
})
Expect(allElements).Should(m, "should match all elements")
Expect(missingElements).ShouldNot(m, "should fail with missing elements")
Expect(extraElements).ShouldNot(m, "should fail with extra elements")
Expect(duplicateElements).ShouldNot(m, "should fail with duplicate elements")
Expect(nils).ShouldNot(m, "should fail with an uninitialized slice")
m = MatchAllElementsWithIndex(IndexIdentity, Elements{
"0": Equal("a"),
"1": Equal("fail"),
})
Expect(allElements).ShouldNot(m, "should run nested matchers")
m = MatchAllElementsWithIndex(IndexIdentity, Elements{})
Expect(empty).Should(m, "should handle empty slices")
Expect(allElements).ShouldNot(m, "should handle only empty slices")
Expect(nils).Should(m, "should handle nil slices")
})
})
})
func id(element interface{}) string {
return element.(string)
}
golang-gomega-1.27.10/gstruct/errors/ 0000775 0000000 0000000 00000000000 14462163431 0017401 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/gstruct/errors/nested_types.go 0000664 0000000 0000000 00000003072 14462163431 0022440 0 ustar 00root root 0000000 0000000 package errors
import (
"fmt"
"strings"
"github.com/onsi/gomega/types"
)
// A stateful matcher that nests other matchers within it and preserves the error types of the
// nested matcher failures.
type NestingMatcher interface {
types.GomegaMatcher
// Returns the failures of nested matchers.
Failures() []error
}
// An error type for labeling errors on deeply nested matchers.
type NestedError struct {
Path string
Err error
}
func (e *NestedError) Error() string {
// Indent Errors.
indented := strings.Replace(e.Err.Error(), "\n", "\n\t", -1)
return fmt.Sprintf("%s:\n\t%v", e.Path, indented)
}
// Create a NestedError with the given path.
// If err is a NestedError, prepend the path to it.
// If err is an AggregateError, recursively Nest each error.
func Nest(path string, err error) error {
if ag, ok := err.(AggregateError); ok {
var errs AggregateError
for _, e := range ag {
errs = append(errs, Nest(path, e))
}
return errs
}
if ne, ok := err.(*NestedError); ok {
return &NestedError{
Path: path + ne.Path,
Err: ne.Err,
}
}
return &NestedError{
Path: path,
Err: err,
}
}
// An error type for treating multiple errors as a single error.
type AggregateError []error
// Error is part of the error interface.
func (err AggregateError) Error() string {
if len(err) == 0 {
// This should never happen, really.
return ""
}
if len(err) == 1 {
return err[0].Error()
}
result := fmt.Sprintf("[%s", err[0].Error())
for i := 1; i < len(err); i++ {
result += fmt.Sprintf(", %s", err[i].Error())
}
result += "]"
return result
}
golang-gomega-1.27.10/gstruct/fields.go 0000664 0000000 0000000 00000010052 14462163431 0017660 0 ustar 00root root 0000000 0000000 // untested sections: 6
package gstruct
import (
"errors"
"fmt"
"reflect"
"runtime/debug"
"strings"
"github.com/onsi/gomega/format"
errorsutil "github.com/onsi/gomega/gstruct/errors"
"github.com/onsi/gomega/types"
)
//MatchAllFields succeeds if every field of a struct matches the field matcher associated with
//it, and every element matcher is matched.
// actual := struct{
// A int
// B []bool
// C string
// }{
// A: 5,
// B: []bool{true, false},
// C: "foo",
// }
//
// Expect(actual).To(MatchAllFields(Fields{
// "A": Equal(5),
// "B": ConsistOf(true, false),
// "C": Equal("foo"),
// }))
func MatchAllFields(fields Fields) types.GomegaMatcher {
return &FieldsMatcher{
Fields: fields,
}
}
//MatchFields succeeds if each element of a struct matches the field matcher associated with
//it. It can ignore extra fields and/or missing fields.
// actual := struct{
// A int
// B []bool
// C string
// }{
// A: 5,
// B: []bool{true, false},
// C: "foo",
// }
//
// Expect(actual).To(MatchFields(IgnoreExtras, Fields{
// "A": Equal(5),
// "B": ConsistOf(true, false),
// }))
// Expect(actual).To(MatchFields(IgnoreMissing, Fields{
// "A": Equal(5),
// "B": ConsistOf(true, false),
// "C": Equal("foo"),
// "D": Equal("extra"),
// }))
func MatchFields(options Options, fields Fields) types.GomegaMatcher {
return &FieldsMatcher{
Fields: fields,
IgnoreExtras: options&IgnoreExtras != 0,
IgnoreMissing: options&IgnoreMissing != 0,
}
}
type FieldsMatcher struct {
// Matchers for each field.
Fields Fields
// Whether to ignore extra elements or consider it an error.
IgnoreExtras bool
// Whether to ignore missing elements or consider it an error.
IgnoreMissing bool
// State.
failures []error
}
// Field name to matcher.
type Fields map[string]types.GomegaMatcher
func (m *FieldsMatcher) Match(actual interface{}) (success bool, err error) {
if reflect.TypeOf(actual).Kind() != reflect.Struct {
return false, fmt.Errorf("%v is type %T, expected struct", actual, actual)
}
m.failures = m.matchFields(actual)
if len(m.failures) > 0 {
return false, nil
}
return true, nil
}
func (m *FieldsMatcher) matchFields(actual interface{}) (errs []error) {
val := reflect.ValueOf(actual)
typ := val.Type()
fields := map[string]bool{}
for i := 0; i < val.NumField(); i++ {
fieldName := typ.Field(i).Name
fields[fieldName] = true
err := func() (err error) {
// This test relies heavily on reflect, which tends to panic.
// Recover here to provide more useful error messages in that case.
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic checking %+v: %v\n%s", actual, r, debug.Stack())
}
}()
matcher, expected := m.Fields[fieldName]
if !expected {
if !m.IgnoreExtras {
return fmt.Errorf("unexpected field %s: %+v", fieldName, actual)
}
return nil
}
field := val.Field(i).Interface()
match, err := matcher.Match(field)
if err != nil {
return err
} else if !match {
if nesting, ok := matcher.(errorsutil.NestingMatcher); ok {
return errorsutil.AggregateError(nesting.Failures())
}
return errors.New(matcher.FailureMessage(field))
}
return nil
}()
if err != nil {
errs = append(errs, errorsutil.Nest("."+fieldName, err))
}
}
for field := range m.Fields {
if !fields[field] && !m.IgnoreMissing {
errs = append(errs, fmt.Errorf("missing expected field %s", field))
}
}
return errs
}
func (m *FieldsMatcher) FailureMessage(actual interface{}) (message string) {
failures := make([]string, len(m.failures))
for i := range m.failures {
failures[i] = m.failures[i].Error()
}
return format.Message(reflect.TypeOf(actual).Name(),
fmt.Sprintf("to match fields: {\n%v\n}\n", strings.Join(failures, "\n")))
}
func (m *FieldsMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, "not to match fields")
}
func (m *FieldsMatcher) Failures() []error {
return m.failures
}
golang-gomega-1.27.10/gstruct/fields_test.go 0000664 0000000 0000000 00000006266 14462163431 0020733 0 ustar 00root root 0000000 0000000 package gstruct_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/gstruct"
)
var _ = Describe("Struct", func() {
allFields := struct{ A, B string }{"a", "b"}
missingFields := struct{ A string }{"a"}
extraFields := struct{ A, B, C string }{"a", "b", "c"}
emptyFields := struct{ A, B string }{}
It("should strictly match all fields", func() {
m := MatchAllFields(Fields{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allFields).Should(m, "should match all fields")
Expect(missingFields).ShouldNot(m, "should fail with missing fields")
Expect(extraFields).ShouldNot(m, "should fail with extra fields")
Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
m = MatchAllFields(Fields{
"A": Equal("a"),
"B": Equal("fail"),
})
Expect(allFields).ShouldNot(m, "should run nested matchers")
})
It("should handle empty structs", func() {
m := MatchAllFields(Fields{})
Expect(struct{}{}).Should(m, "should handle empty structs")
Expect(allFields).ShouldNot(m, "should fail with extra fields")
})
It("should ignore missing fields", func() {
m := MatchFields(IgnoreMissing, Fields{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allFields).Should(m, "should match all fields")
Expect(missingFields).Should(m, "should ignore missing fields")
Expect(extraFields).ShouldNot(m, "should fail with extra fields")
Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
})
It("should ignore extra fields", func() {
m := MatchFields(IgnoreExtras, Fields{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allFields).Should(m, "should match all fields")
Expect(missingFields).ShouldNot(m, "should fail with missing fields")
Expect(extraFields).Should(m, "should ignore extra fields")
Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
})
It("should ignore missing and extra fields", func() {
m := MatchFields(IgnoreMissing|IgnoreExtras, Fields{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allFields).Should(m, "should match all fields")
Expect(missingFields).Should(m, "should ignore missing fields")
Expect(extraFields).Should(m, "should ignore extra fields")
Expect(emptyFields).ShouldNot(m, "should fail with empty fields")
m = MatchFields(IgnoreMissing|IgnoreExtras, Fields{
"A": Equal("a"),
"B": Equal("fail"),
})
Expect(allFields).ShouldNot(m, "should run nested matchers")
})
It("should produce sensible error messages", func() {
m := MatchAllFields(Fields{
"B": Equal("b"),
"A": Equal("a"),
})
actual := struct{ A, C string }{A: "b", C: "c"}
//Because the order of the constituent errors can't be guaranteed,
//we do a number of checks to make sure everything's included
m.Match(actual)
Expect(m.FailureMessage(actual)).Should(HavePrefix(
"Expected\n : \nto match fields: {\n",
))
Expect(m.FailureMessage(actual)).Should(ContainSubstring(
".A:\n Expected\n : b\n to equal\n : a\n",
))
Expect(m.FailureMessage(actual)).Should(ContainSubstring(
"missing expected field B\n",
))
Expect(m.FailureMessage(actual)).Should(ContainSubstring(
".C:\n unexpected field C: {A:b C:c}",
))
})
})
golang-gomega-1.27.10/gstruct/gstruct_tests_suite_test.go 0000664 0000000 0000000 00000000276 14462163431 0023606 0 ustar 00root root 0000000 0000000 package gstruct_test
import (
"testing"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
func Test(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Gstruct Suite")
}
golang-gomega-1.27.10/gstruct/ignore.go 0000664 0000000 0000000 00000001731 14462163431 0017701 0 ustar 00root root 0000000 0000000 // untested sections: 2
package gstruct
import (
"github.com/onsi/gomega/types"
)
//Ignore ignores the actual value and always succeeds.
// Expect(nil).To(Ignore())
// Expect(true).To(Ignore())
func Ignore() types.GomegaMatcher {
return &IgnoreMatcher{true}
}
//Reject ignores the actual value and always fails. It can be used in conjunction with IgnoreMissing
//to catch problematic elements, or to verify tests are running.
// Expect(nil).NotTo(Reject())
// Expect(true).NotTo(Reject())
func Reject() types.GomegaMatcher {
return &IgnoreMatcher{false}
}
// A matcher that either always succeeds or always fails.
type IgnoreMatcher struct {
Succeed bool
}
func (m *IgnoreMatcher) Match(actual interface{}) (bool, error) {
return m.Succeed, nil
}
func (m *IgnoreMatcher) FailureMessage(_ interface{}) (message string) {
return "Unconditional failure"
}
func (m *IgnoreMatcher) NegatedFailureMessage(_ interface{}) (message string) {
return "Unconditional success"
}
golang-gomega-1.27.10/gstruct/ignore_test.go 0000664 0000000 0000000 00000001013 14462163431 0020731 0 ustar 00root root 0000000 0000000 package gstruct_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/gstruct"
)
var _ = Describe("Ignore", func() {
It("should always succeed", func() {
Expect(nil).Should(Ignore())
Expect(struct{}{}).Should(Ignore())
Expect(0).Should(Ignore())
Expect(false).Should(Ignore())
})
It("should always fail", func() {
Expect(nil).ShouldNot(Reject())
Expect(struct{}{}).ShouldNot(Reject())
Expect(1).ShouldNot(Reject())
Expect(true).ShouldNot(Reject())
})
})
golang-gomega-1.27.10/gstruct/keys.go 0000664 0000000 0000000 00000005665 14462163431 0017403 0 ustar 00root root 0000000 0000000 // untested sections: 6
package gstruct
import (
"errors"
"fmt"
"reflect"
"runtime/debug"
"strings"
"github.com/onsi/gomega/format"
errorsutil "github.com/onsi/gomega/gstruct/errors"
"github.com/onsi/gomega/types"
)
func MatchAllKeys(keys Keys) types.GomegaMatcher {
return &KeysMatcher{
Keys: keys,
}
}
func MatchKeys(options Options, keys Keys) types.GomegaMatcher {
return &KeysMatcher{
Keys: keys,
IgnoreExtras: options&IgnoreExtras != 0,
IgnoreMissing: options&IgnoreMissing != 0,
}
}
type KeysMatcher struct {
// Matchers for each key.
Keys Keys
// Whether to ignore extra keys or consider it an error.
IgnoreExtras bool
// Whether to ignore missing keys or consider it an error.
IgnoreMissing bool
// State.
failures []error
}
type Keys map[interface{}]types.GomegaMatcher
func (m *KeysMatcher) Match(actual interface{}) (success bool, err error) {
if reflect.TypeOf(actual).Kind() != reflect.Map {
return false, fmt.Errorf("%v is type %T, expected map", actual, actual)
}
m.failures = m.matchKeys(actual)
if len(m.failures) > 0 {
return false, nil
}
return true, nil
}
func (m *KeysMatcher) matchKeys(actual interface{}) (errs []error) {
actualValue := reflect.ValueOf(actual)
keys := map[interface{}]bool{}
for _, keyValue := range actualValue.MapKeys() {
key := keyValue.Interface()
keys[key] = true
err := func() (err error) {
// This test relies heavily on reflect, which tends to panic.
// Recover here to provide more useful error messages in that case.
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("panic checking %+v: %v\n%s", actual, r, debug.Stack())
}
}()
matcher, ok := m.Keys[key]
if !ok {
if !m.IgnoreExtras {
return fmt.Errorf("unexpected key %s: %+v", key, actual)
}
return nil
}
valInterface := actualValue.MapIndex(keyValue).Interface()
match, err := matcher.Match(valInterface)
if err != nil {
return err
}
if !match {
if nesting, ok := matcher.(errorsutil.NestingMatcher); ok {
return errorsutil.AggregateError(nesting.Failures())
}
return errors.New(matcher.FailureMessage(valInterface))
}
return nil
}()
if err != nil {
errs = append(errs, errorsutil.Nest(fmt.Sprintf(".%#v", key), err))
}
}
for key := range m.Keys {
if !keys[key] && !m.IgnoreMissing {
errs = append(errs, fmt.Errorf("missing expected key %s", key))
}
}
return errs
}
func (m *KeysMatcher) FailureMessage(actual interface{}) (message string) {
failures := make([]string, len(m.failures))
for i := range m.failures {
failures[i] = m.failures[i].Error()
}
return format.Message(reflect.TypeOf(actual).Name(),
fmt.Sprintf("to match keys: {\n%v\n}\n", strings.Join(failures, "\n")))
}
func (m *KeysMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return format.Message(actual, "not to match keys")
}
func (m *KeysMatcher) Failures() []error {
return m.failures
}
golang-gomega-1.27.10/gstruct/keys_test.go 0000664 0000000 0000000 00000006073 14462163431 0020434 0 ustar 00root root 0000000 0000000 package gstruct_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/gstruct"
)
var _ = Describe("Map", func() {
allKeys := map[string]string{"A": "a", "B": "b"}
missingKeys := map[string]string{"A": "a"}
extraKeys := map[string]string{"A": "a", "B": "b", "C": "c"}
emptyKeys := map[string]string{}
It("should strictly match all keys", func() {
m := MatchAllKeys(Keys{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allKeys).Should(m, "should match all keys")
Expect(missingKeys).ShouldNot(m, "should fail with missing keys")
Expect(extraKeys).ShouldNot(m, "should fail with extra keys")
Expect(emptyKeys).ShouldNot(m, "should fail with empty keys")
m = MatchAllKeys(Keys{
"A": Equal("a"),
"B": Equal("fail"),
})
Expect(allKeys).ShouldNot(m, "should run nested matchers")
})
It("should handle empty maps", func() {
m := MatchAllKeys(Keys{})
Expect(map[string]string{}).Should(m, "should handle empty maps")
Expect(allKeys).ShouldNot(m, "should fail with extra keys")
})
It("should ignore missing keys", func() {
m := MatchKeys(IgnoreMissing, Keys{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allKeys).Should(m, "should match all keys")
Expect(missingKeys).Should(m, "should ignore missing keys")
Expect(extraKeys).ShouldNot(m, "should fail with extra keys")
Expect(emptyKeys).Should(m, "should match empty keys")
})
It("should ignore extra keys", func() {
m := MatchKeys(IgnoreExtras, Keys{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allKeys).Should(m, "should match all keys")
Expect(missingKeys).ShouldNot(m, "should fail with missing keys")
Expect(extraKeys).Should(m, "should ignore extra keys")
Expect(emptyKeys).ShouldNot(m, "should fail with empty keys")
})
It("should ignore missing and extra keys", func() {
m := MatchKeys(IgnoreMissing|IgnoreExtras, Keys{
"B": Equal("b"),
"A": Equal("a"),
})
Expect(allKeys).Should(m, "should match all keys")
Expect(missingKeys).Should(m, "should ignore missing keys")
Expect(extraKeys).Should(m, "should ignore extra keys")
Expect(emptyKeys).Should(m, "should match empty keys")
m = MatchKeys(IgnoreMissing|IgnoreExtras, Keys{
"A": Equal("a"),
"B": Equal("fail"),
})
Expect(allKeys).ShouldNot(m, "should run nested matchers")
})
It("should produce sensible error messages", func() {
m := MatchAllKeys(Keys{
"B": Equal("b"),
"A": Equal("a"),
})
actual := map[string]string{"A": "b", "C": "c"}
//Because the order of the constituent errors can't be guaranteed,
//we do a number of checks to make sure everything's included
m.Match(actual)
Expect(m.FailureMessage(actual)).Should(HavePrefix(
"Expected\n : \nto match keys: {\n",
))
Expect(m.FailureMessage(actual)).Should(ContainSubstring(
".\"A\":\n Expected\n : b\n to equal\n : a\n",
))
Expect(m.FailureMessage(actual)).Should(ContainSubstring(
"missing expected key B\n",
))
Expect(m.FailureMessage(actual)).Should(ContainSubstring(
".\"C\":\n unexpected key C: map[",
))
})
})
golang-gomega-1.27.10/gstruct/pointer.go 0000664 0000000 0000000 00000002442 14462163431 0020076 0 ustar 00root root 0000000 0000000 // untested sections: 3
package gstruct
import (
"fmt"
"reflect"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
//PointTo applies the given matcher to the value pointed to by actual. It fails if the pointer is
//nil.
// actual := 5
// Expect(&actual).To(PointTo(Equal(5)))
func PointTo(matcher types.GomegaMatcher) types.GomegaMatcher {
return &PointerMatcher{
Matcher: matcher,
}
}
type PointerMatcher struct {
Matcher types.GomegaMatcher
// Failure message.
failure string
}
func (m *PointerMatcher) Match(actual interface{}) (bool, error) {
val := reflect.ValueOf(actual)
// return error if actual type is not a pointer
if val.Kind() != reflect.Ptr {
return false, fmt.Errorf("PointerMatcher expects a pointer but we have '%s'", val.Kind())
}
if !val.IsValid() || val.IsNil() {
m.failure = format.Message(actual, "not to be ")
return false, nil
}
// Forward the value.
elem := val.Elem().Interface()
match, err := m.Matcher.Match(elem)
if !match {
m.failure = m.Matcher.FailureMessage(elem)
}
return match, err
}
func (m *PointerMatcher) FailureMessage(_ interface{}) (message string) {
return m.failure
}
func (m *PointerMatcher) NegatedFailureMessage(actual interface{}) (message string) {
return m.Matcher.NegatedFailureMessage(actual)
}
golang-gomega-1.27.10/gstruct/pointer_test.go 0000664 0000000 0000000 00000001312 14462163431 0021130 0 ustar 00root root 0000000 0000000 package gstruct_test
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
. "github.com/onsi/gomega/gstruct"
)
var _ = Describe("PointTo", func() {
It("should fail when passed nil", func() {
var p *struct{}
Expect(p).Should(BeNil())
})
It("should succeed when passed non-nil pointer", func() {
var s struct{}
Expect(&s).Should(PointTo(Ignore()))
})
It("should unwrap the pointee value", func() {
i := 1
Expect(&i).Should(PointTo(Equal(1)))
Expect(&i).ShouldNot(PointTo(Equal(2)))
})
It("should work with nested pointers", func() {
i := 1
ip := &i
ipp := &ip
Expect(ipp).Should(PointTo(PointTo(Equal(1))))
Expect(ipp).ShouldNot(PointTo(PointTo(Equal(2))))
})
})
golang-gomega-1.27.10/gstruct/types.go 0000664 0000000 0000000 00000001206 14462163431 0017557 0 ustar 00root root 0000000 0000000 package gstruct
//Options is the type for options passed to some matchers.
type Options int
const (
//IgnoreExtras tells the matcher to ignore extra elements or fields, rather than triggering a failure.
IgnoreExtras Options = 1 << iota
//IgnoreMissing tells the matcher to ignore missing elements or fields, rather than triggering a failure.
IgnoreMissing
//AllowDuplicates tells the matcher to permit multiple members of the slice to produce the same ID when
//considered by the indentifier function. All members that map to a given key must still match successfully
//with the matcher that is provided for that key.
AllowDuplicates
)
golang-gomega-1.27.10/internal/ 0000775 0000000 0000000 00000000000 14462163431 0016206 5 ustar 00root root 0000000 0000000 golang-gomega-1.27.10/internal/assertion.go 0000664 0000000 0000000 00000013134 14462163431 0020546 0 ustar 00root root 0000000 0000000 package internal
import (
"fmt"
"reflect"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
type Assertion struct {
actuals []interface{} // actual value plus all extra values
actualIndex int // value to pass to the matcher
vet vetinari // the vet to call before calling Gomega matcher
offset int
g *Gomega
}
// ...obligatory discworld reference, as "vetineer" doesn't sound ... quite right.
type vetinari func(assertion *Assertion, optionalDescription ...interface{}) bool
func NewAssertion(actualInput interface{}, g *Gomega, offset int, extra ...interface{}) *Assertion {
return &Assertion{
actuals: append([]interface{}{actualInput}, extra...),
actualIndex: 0,
vet: (*Assertion).vetActuals,
offset: offset,
g: g,
}
}
func (assertion *Assertion) WithOffset(offset int) types.Assertion {
assertion.offset = offset
return assertion
}
func (assertion *Assertion) Error() types.Assertion {
return &Assertion{
actuals: assertion.actuals,
actualIndex: len(assertion.actuals) - 1,
vet: (*Assertion).vetError,
offset: assertion.offset,
g: assertion.g,
}
}
func (assertion *Assertion) Should(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Assertion", optionalDescription...)
return assertion.vet(assertion, optionalDescription...) && assertion.match(matcher, true, optionalDescription...)
}
func (assertion *Assertion) ShouldNot(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Assertion", optionalDescription...)
return assertion.vet(assertion, optionalDescription...) && assertion.match(matcher, false, optionalDescription...)
}
func (assertion *Assertion) To(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Assertion", optionalDescription...)
return assertion.vet(assertion, optionalDescription...) && assertion.match(matcher, true, optionalDescription...)
}
func (assertion *Assertion) ToNot(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Assertion", optionalDescription...)
return assertion.vet(assertion, optionalDescription...) && assertion.match(matcher, false, optionalDescription...)
}
func (assertion *Assertion) NotTo(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Assertion", optionalDescription...)
return assertion.vet(assertion, optionalDescription...) && assertion.match(matcher, false, optionalDescription...)
}
func (assertion *Assertion) buildDescription(optionalDescription ...interface{}) string {
switch len(optionalDescription) {
case 0:
return ""
case 1:
if describe, ok := optionalDescription[0].(func() string); ok {
return describe() + "\n"
}
}
return fmt.Sprintf(optionalDescription[0].(string), optionalDescription[1:]...) + "\n"
}
func (assertion *Assertion) match(matcher types.GomegaMatcher, desiredMatch bool, optionalDescription ...interface{}) bool {
actualInput := assertion.actuals[assertion.actualIndex]
matches, err := matcher.Match(actualInput)
assertion.g.THelper()
if err != nil {
description := assertion.buildDescription(optionalDescription...)
assertion.g.Fail(description+err.Error(), 2+assertion.offset)
return false
}
if matches != desiredMatch {
var message string
if desiredMatch {
message = matcher.FailureMessage(actualInput)
} else {
message = matcher.NegatedFailureMessage(actualInput)
}
description := assertion.buildDescription(optionalDescription...)
assertion.g.Fail(description+message, 2+assertion.offset)
return false
}
return true
}
// vetActuals vets the actual values, with the (optional) exception of a
// specific value, such as the first value in case non-error assertions, or the
// last value in case of Error()-based assertions.
func (assertion *Assertion) vetActuals(optionalDescription ...interface{}) bool {
success, message := vetActuals(assertion.actuals, assertion.actualIndex)
if success {
return true
}
description := assertion.buildDescription(optionalDescription...)
assertion.g.THelper()
assertion.g.Fail(description+message, 2+assertion.offset)
return false
}
// vetError vets the actual values, except for the final error value, in case
// the final error value is non-zero. Otherwise, it doesn't vet the actual
// values, as these are allowed to take on any values unless there is a non-zero
// error value.
func (assertion *Assertion) vetError(optionalDescription ...interface{}) bool {
if err := assertion.actuals[assertion.actualIndex]; err != nil {
// Go error result idiom: all other actual values must be zero values.
return assertion.vetActuals(optionalDescription...)
}
return true
}
// vetActuals vets a slice of actual values, optionally skipping a particular
// value slice element, such as the first or last value slice element.
func vetActuals(actuals []interface{}, skipIndex int) (bool, string) {
for i, actual := range actuals {
if i == skipIndex {
continue
}
if actual != nil {
zeroValue := reflect.Zero(reflect.TypeOf(actual)).Interface()
if !reflect.DeepEqual(zeroValue, actual) {
var message string
if err, ok := actual.(error); ok {
message = fmt.Sprintf("Unexpected error: %s\n%s", err, format.Object(err, 1))
} else {
message = fmt.Sprintf("Unexpected non-nil/non-zero argument at index %d:\n\t<%T>: %#v", i, actual, actual)
}
return false, message
}
}
}
return true, ""
}
golang-gomega-1.27.10/internal/assertion_test.go 0000664 0000000 0000000 00000020326 14462163431 0021606 0 ustar 00root root 0000000 0000000 package internal_test
import (
"errors"
"reflect"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
)
var _ = Describe("Making Synchronous Assertions", func() {
var SHOULD_MATCH = true
var SHOULD_NOT_MATCH = false
var IT_PASSES = true
var IT_FAILS = false
Extras := func(extras ...interface{}) []interface{} {
return extras
}
OptionalDescription := func(optionalDescription ...interface{}) []interface{} {
return optionalDescription
}
DescribeTable(
"the various cases",
func(actual interface{}, extras []interface{}, optionalDescription []interface{}, isPositiveAssertion bool, expectedFailureMessage string, expectedReturnValue bool) {
if isPositiveAssertion {
ig := NewInstrumentedGomega()
returnValue := ig.G.Expect(actual, extras...).To(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{2}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).To"))
ig = NewInstrumentedGomega()
returnValue = ig.G.ExpectWithOffset(3, actual, extras...).To(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{5}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).To"))
ig = NewInstrumentedGomega()
returnValue = ig.G.Ω(actual, extras...).Should(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{2}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).Should"))
} else {
ig := NewInstrumentedGomega()
returnValue := ig.G.Expect(actual, extras...).ToNot(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{2}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).ToNot"))
ig = NewInstrumentedGomega()
returnValue = ig.G.Expect(actual, extras...).NotTo(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{2}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).NotTo"))
ig = NewInstrumentedGomega()
returnValue = ig.G.ExpectWithOffset(3, actual, extras...).NotTo(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{5}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).NotTo"))
ig = NewInstrumentedGomega()
returnValue = ig.G.Ω(actual, extras...).ShouldNot(SpecMatch(), optionalDescription...)
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(ContainSubstring(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{2}))
}
Expect(ig.RegisteredHelpers).To(ContainElement("(*Assertion).ShouldNot"))
}
},
Entry(
"when the matcher matches and a positive assertion is being made",
MATCH, Extras(), OptionalDescription(),
SHOULD_MATCH, "", IT_PASSES,
),
Entry(
"when the matcher matches and a negative assertion is being made",
MATCH, Extras(), OptionalDescription(),
SHOULD_NOT_MATCH, "negative: match", IT_FAILS,
),
Entry(
"when the matcher does not match and a positive assertion is being made",
NO_MATCH, Extras(), OptionalDescription(),
SHOULD_MATCH, "positive: no match", IT_FAILS,
),
Entry(
"when the matcher does not match and a negative assertion is being made",
NO_MATCH, Extras(), OptionalDescription(),
SHOULD_NOT_MATCH, "", IT_PASSES,
),
Entry(
"when the matcher returns an error and a positive assertion is being made",
ERR_MATCH, Extras(), OptionalDescription(),
SHOULD_MATCH, "spec matcher error", IT_FAILS,
),
Entry(
"when the matcher returns an error and a negative assertion is being made",
ERR_MATCH, Extras(), OptionalDescription(),
SHOULD_NOT_MATCH, "spec matcher error", IT_FAILS,
),
Entry(
"when a failure occurs and there is a single optional description",
NO_MATCH, Extras(), OptionalDescription("a description"),
SHOULD_MATCH, "a description\npositive: no match", IT_FAILS,
),
Entry(
"when a failure occurs and there are multiple optional descriptions",
NO_MATCH, Extras(), OptionalDescription("a description of [%d]", 3),
SHOULD_MATCH, "a description of [3]\npositive: no match", IT_FAILS,
),
Entry(
"when a failure occurs and the optional description is a function",
NO_MATCH, Extras(), OptionalDescription(func() string { return "a description" }),
SHOULD_MATCH, "a description\npositive: no match", IT_FAILS,
),
Entry(
"when the matcher matches and zero-valued extra parameters are included, it passes",
MATCH, Extras(0, "", struct{ Foo string }{}, nil), OptionalDescription(),
SHOULD_MATCH, "", IT_PASSES,
),
Entry(
"when the matcher matches but a non-zero-valued extra parameter is included, it fails",
MATCH, Extras(1, "bam", struct{ Foo string }{Foo: "foo"}, nil), OptionalDescription(),
SHOULD_MATCH, "Unexpected non-nil/non-zero argument at index 1:\n\t: 1", IT_FAILS,
),
Entry(
"when the matcher matches but an error is included, it fails",
MATCH, Extras(0, "", errors.New("welp!")), OptionalDescription(),
SHOULD_MATCH, "Unexpected error: welp!", IT_FAILS,
),
)
var SHOULD_OCCUR = true
var SHOULD_NOT_OCCUR = false
DescribeTable("error expectations",
func(a, b int, e error, isPositiveAssertion bool, expectedFailureMessage string, expectedReturnValue bool) {
abe := func(a, b int, e error) (int, int, error) {
return a, b, e
}
ig := NewInstrumentedGomega()
var returnValue bool
if isPositiveAssertion {
returnValue = ig.G.Expect(abe(a, b, e)).Error().To(HaveOccurred())
} else {
returnValue = ig.G.Expect(abe(a, b, e)).Error().NotTo(HaveOccurred())
}
Expect(returnValue).To(Equal(expectedReturnValue))
Expect(ig.FailureMessage).To(Equal(expectedFailureMessage))
if expectedFailureMessage != "" {
Expect(ig.FailureSkip).To(Equal([]int{2}))
}
},
Entry(
"when non-zero results without error",
1, 2, nil,
SHOULD_NOT_OCCUR, "", IT_PASSES,
),
Entry(
"when non-zero results with error",
1, 2, errors.New("D'oh!"),
SHOULD_NOT_OCCUR, "Unexpected non-nil/non-zero argument at index 0:\n\t: 1", IT_FAILS,
),
Entry(
"when non-zero results without error",
0, 0, errors.New("D'oh!"),
SHOULD_OCCUR, "", IT_PASSES,
),
Entry(
"when non-zero results with error",
1, 2, errors.New("D'oh!"),
SHOULD_OCCUR, "Unexpected non-nil/non-zero argument at index 0:\n\t: 1", IT_FAILS,
),
)
When("vetting optional description parameters", func() {
It("panics when Gomega matcher is at the beginning of optional description parameters", func() {
ig := NewInstrumentedGomega()
for _, expectator := range []string{
"To", "NotTo", "ToNot",
"Should", "ShouldNot",
} {
Expect(func() {
expect := ig.G.Expect(42) // sic!
meth := reflect.ValueOf(expect).MethodByName(expectator)
Expect(meth.IsValid()).To(BeTrue())
meth.Call([]reflect.Value{
reflect.ValueOf(HaveLen(1)),
reflect.ValueOf(ContainElement(42)),
})
}).To(PanicWith(MatchRegexp("Assertion has a GomegaMatcher as the first element of optionalDescription")))
}
})
It("accepts Gomega matchers in optional description parameters after the first", func() {
Expect(func() {
ig := NewInstrumentedGomega()
ig.G.Expect(42).To(HaveLen(1), "foo", ContainElement(42))
}).NotTo(Panic())
})
})
})
golang-gomega-1.27.10/internal/async_assertion.go 0000664 0000000 0000000 00000042051 14462163431 0021743 0 ustar 00root root 0000000 0000000 package internal
import (
"context"
"errors"
"fmt"
"reflect"
"runtime"
"sync"
"time"
"github.com/onsi/gomega/format"
"github.com/onsi/gomega/types"
)
var errInterface = reflect.TypeOf((*error)(nil)).Elem()
var gomegaType = reflect.TypeOf((*types.Gomega)(nil)).Elem()
var contextType = reflect.TypeOf(new(context.Context)).Elem()
type formattedGomegaError interface {
FormattedGomegaError() string
}
type asyncPolledActualError struct {
message string
}
func (err *asyncPolledActualError) Error() string {
return err.message
}
func (err *asyncPolledActualError) FormattedGomegaError() string {
return err.message
}
type contextWithAttachProgressReporter interface {
AttachProgressReporter(func() string) func()
}
type asyncGomegaHaltExecutionError struct{}
func (a asyncGomegaHaltExecutionError) GinkgoRecoverShouldIgnoreThisPanic() {}
func (a asyncGomegaHaltExecutionError) Error() string {
return `An assertion has failed in a goroutine. You should call
defer GinkgoRecover()
at the top of the goroutine that caused this panic. This will allow Ginkgo and Gomega to correctly capture and manage this panic.`
}
type AsyncAssertionType uint
const (
AsyncAssertionTypeEventually AsyncAssertionType = iota
AsyncAssertionTypeConsistently
)
func (at AsyncAssertionType) String() string {
switch at {
case AsyncAssertionTypeEventually:
return "Eventually"
case AsyncAssertionTypeConsistently:
return "Consistently"
}
return "INVALID ASYNC ASSERTION TYPE"
}
type AsyncAssertion struct {
asyncType AsyncAssertionType
actualIsFunc bool
actual interface{}
argsToForward []interface{}
timeoutInterval time.Duration
pollingInterval time.Duration
mustPassRepeatedly int
ctx context.Context
offset int
g *Gomega
}
func NewAsyncAssertion(asyncType AsyncAssertionType, actualInput interface{}, g *Gomega, timeoutInterval time.Duration, pollingInterval time.Duration, mustPassRepeatedly int, ctx context.Context, offset int) *AsyncAssertion {
out := &AsyncAssertion{
asyncType: asyncType,
timeoutInterval: timeoutInterval,
pollingInterval: pollingInterval,
mustPassRepeatedly: mustPassRepeatedly,
offset: offset,
ctx: ctx,
g: g,
}
out.actual = actualInput
if actualInput != nil && reflect.TypeOf(actualInput).Kind() == reflect.Func {
out.actualIsFunc = true
}
return out
}
func (assertion *AsyncAssertion) WithOffset(offset int) types.AsyncAssertion {
assertion.offset = offset
return assertion
}
func (assertion *AsyncAssertion) WithTimeout(interval time.Duration) types.AsyncAssertion {
assertion.timeoutInterval = interval
return assertion
}
func (assertion *AsyncAssertion) WithPolling(interval time.Duration) types.AsyncAssertion {
assertion.pollingInterval = interval
return assertion
}
func (assertion *AsyncAssertion) Within(timeout time.Duration) types.AsyncAssertion {
assertion.timeoutInterval = timeout
return assertion
}
func (assertion *AsyncAssertion) ProbeEvery(interval time.Duration) types.AsyncAssertion {
assertion.pollingInterval = interval
return assertion
}
func (assertion *AsyncAssertion) WithContext(ctx context.Context) types.AsyncAssertion {
assertion.ctx = ctx
return assertion
}
func (assertion *AsyncAssertion) WithArguments(argsToForward ...interface{}) types.AsyncAssertion {
assertion.argsToForward = argsToForward
return assertion
}
func (assertion *AsyncAssertion) MustPassRepeatedly(count int) types.AsyncAssertion {
assertion.mustPassRepeatedly = count
return assertion
}
func (assertion *AsyncAssertion) Should(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Asynchronous assertion", optionalDescription...)
return assertion.match(matcher, true, optionalDescription...)
}
func (assertion *AsyncAssertion) ShouldNot(matcher types.GomegaMatcher, optionalDescription ...interface{}) bool {
assertion.g.THelper()
vetOptionalDescription("Asynchronous assertion", optionalDescription...)
return assertion.match(matcher, false, optionalDescription...)
}
func (assertion *AsyncAssertion) buildDescription(optionalDescription ...interface{}) string {
switch len(optionalDescription) {
case 0:
return ""
case 1:
if describe, ok := optionalDescription[0].(func() string); ok {
return describe() + "\n"
}
}
return fmt.Sprintf(optionalDescription[0].(string), optionalDescription[1:]...) + "\n"
}
func (assertion *AsyncAssertion) processReturnValues(values []reflect.Value) (interface{}, error) {
if len(values) == 0 {
return nil, &asyncPolledActualError{
message: fmt.Sprintf("The function passed to %s did not return any values", assertion.asyncType),
}
}
actual := values[0].Interface()
if _, ok := AsPollingSignalError(actual); ok {
return actual, actual.(error)
}
var err error
for i, extraValue := range values[1:] {
extra := extraValue.Interface()
if extra == nil {
continue
}
if _, ok := AsPollingSignalError(extra); ok {
return actual, extra.(error)
}
extraType := reflect.TypeOf(extra)
zero := reflect.Zero(extraType).Interface()
if reflect.DeepEqual(extra, zero) {
continue
}
if i == len(values)-2 && extraType.Implements(errInterface) {
err = extra.(error)
}
if err == nil {
err = &asyncPolledActualError{
message: fmt.Sprintf("The function passed to %s had an unexpected non-nil/non-zero return value at index %d:\n%s", assertion.asyncType, i+1, format.Object(extra, 1)),
}
}
}
return actual, err
}
func (assertion *AsyncAssertion) invalidFunctionError(t reflect.Type) error {
return fmt.Errorf(`The function passed to %s had an invalid signature of %s. Functions passed to %s must either:
(a) have return values or
(b) take a Gomega interface as their first argument and use that Gomega instance to make assertions.
You can learn more at https://onsi.github.io/gomega/#eventually
`, assertion.asyncType, t, assertion.asyncType)
}
func (assertion *AsyncAssertion) noConfiguredContextForFunctionError() error {
return fmt.Errorf(`The function passed to %s requested a context.Context, but no context has been provided. Please pass one in using %s().WithContext().
You can learn more at https://onsi.github.io/gomega/#eventually
`, assertion.asyncType, assertion.asyncType)
}
func (assertion *AsyncAssertion) argumentMismatchError(t reflect.Type, numProvided int) error {
have := "have"
if numProvided == 1 {
have = "has"
}
return fmt.Errorf(`The function passed to %s has signature %s takes %d arguments but %d %s been provided. Please use %s().WithArguments() to pass the corect set of arguments.
You can learn more at https://onsi.github.io/gomega/#eventually
`, assertion.asyncType, t, t.NumIn(), numProvided, have, assertion.asyncType)
}
func (assertion *AsyncAssertion) invalidMustPassRepeatedlyError(reason string) error {
return fmt.Errorf(`Invalid use of MustPassRepeatedly with %s %s
You can learn more at https://onsi.github.io/gomega/#eventually
`, assertion.asyncType, reason)
}
func (assertion *AsyncAssertion) buildActualPoller() (func() (interface{}, error), error) {
if !assertion.actualIsFunc {
return func() (interface{}, error) { return assertion.actual, nil }, nil
}
actualValue := reflect.ValueOf(assertion.actual)
actualType := reflect.TypeOf(assertion.actual)
numIn, numOut, isVariadic := actualType.NumIn(), actualType.NumOut(), actualType.IsVariadic()
if numIn == 0 && numOut == 0 {
return nil, assertion.invalidFunctionError(actualType)
}
takesGomega, takesContext := false, false
if numIn > 0 {
takesGomega, takesContext = actualType.In(0).Implements(gomegaType), actualType.In(0).Implements(contextType)
}
if takesGomega && numIn > 1 && actualType.In(1).Implements(contextType) {
takesContext = true
}
if takesContext && len(assertion.argsToForward) > 0 && reflect.TypeOf(assertion.argsToForward[0]).Implements(contextType) {
takesContext = false
}
if !takesGomega && numOut == 0 {
return nil, assertion.invalidFunctionError(actualType)
}
if takesContext && assertion.ctx == nil {
return nil, assertion.noConfiguredContextForFunctionError()
}
var assertionFailure error
inValues := []reflect.Value{}
if takesGomega {
inValues = append(inValues, reflect.ValueOf(NewGomega(assertion.g.DurationBundle).ConfigureWithFailHandler(func(message string, callerSkip ...int) {
skip := 0
if len(callerSkip) > 0 {
skip = callerSkip[0]
}
_, file, line, _ := runtime.Caller(skip + 1)
assertionFailure = &asyncPolledActualError{
message: fmt.Sprintf("The function passed to %s failed at %s:%d with:\n%s", assertion.asyncType, file, line, message),
}
// we throw an asyncGomegaHaltExecutionError so that defer GinkgoRecover() can catch this error if the user makes an assertion in a goroutine
panic(asyncGomegaHaltExecutionError{})
})))
}
if takesContext {
inValues = append(inValues, reflect.ValueOf(assertion.ctx))
}
for _, arg := range assertion.argsToForward {
inValues = append(inValues, reflect.ValueOf(arg))
}
if !isVariadic && numIn != len(inValues) {
return nil, assertion.argumentMismatchError(actualType, len(inValues))
} else if isVariadic && len(inValues) < numIn-1 {
return nil, assertion.argumentMismatchError(actualType, len(inValues))
}
if assertion.mustPassRepeatedly != 1 && assertion.asyncType != AsyncAssertionTypeEventually {
return nil, assertion.invalidMustPassRepeatedlyError("it can only be used with Eventually")
}
if assertion.mustPassRepeatedly < 1 {
return nil, assertion.invalidMustPassRepeatedlyError("parameter can't be < 1")
}
return func() (actual interface{}, err error) {
var values []reflect.Value
assertionFailure = nil
defer func() {
if numOut == 0 && takesGomega {
actual = assertionFailure
} else {
actual, err = assertion.processReturnValues(values)
_, isAsyncError := AsPollingSignalError(err)
if assertionFailure != nil && !isAsyncError {
err = assertionFailure
}
}
if e := recover(); e != nil {
if _, isAsyncError := AsPollingSignalError(e); isAsyncError {
err = e.(error)
} else if assertionFailure == nil {
panic(e)
}
}
}()
values = actualValue.Call(inValues)
return
}, nil
}
func (assertion *AsyncAssertion) afterTimeout() <-chan time.Time {
if assertion.timeoutInterval >= 0 {
return time.After(assertion.timeoutInterval)
}
if assertion.asyncType == AsyncAssertionTypeConsistently {
return time.After(assertion.g.DurationBundle.ConsistentlyDuration)
} else {
if assertion.ctx == nil {
return time.After(assertion.g.DurationBundle.EventuallyTimeout)
} else {
return nil
}
}
}
func (assertion *AsyncAssertion) afterPolling() <-chan time.Time {
if assertion.pollingInterval >= 0 {
return time.After(assertion.pollingInterval)
}
if assertion.asyncType == AsyncAssertionTypeConsistently {
return time.After(assertion.g.DurationBundle.ConsistentlyPollingInterval)
} else {
return time.After(assertion.g.DurationBundle.EventuallyPollingInterval)
}
}
func (assertion *AsyncAssertion) matcherSaysStopTrying(matcher types.GomegaMatcher, value interface{}) bool {
if assertion.actualIsFunc || types.MatchMayChangeInTheFuture(matcher, value) {
return false
}
return true
}
func (assertion *AsyncAssertion) pollMatcher(matcher types.GomegaMatcher, value interface{}) (matches bool, err error) {
defer func() {
if e := recover(); e != nil {
if _, isAsyncError := AsPollingSignalError(e); isAsyncError {
err = e.(error)
} else {
panic(e)
}
}
}()
matches, err = matcher.Match(value)
return
}
func (assertion *AsyncAssertion) match(matcher types.GomegaMatcher, desiredMatch bool, optionalDescription ...interface{}) bool {
timer := time.Now()
timeout := assertion.afterTimeout()
lock := sync.Mutex{}
var matches, hasLastValidActual bool
var actual, lastValidActual interface{}
var actualErr, matcherErr error
var oracleMatcherSaysStop bool
assertion.g.THelper()
pollActual, buildActualPollerErr := assertion.buildActualPoller()
if buildActualPollerErr != nil {
assertion.g.Fail(buildActualPollerErr.Error(), 2+assertion.offset)
return false
}
actual, actualErr = pollActual()
if actualErr == nil {
lastValidActual = actual
hasLastValidActual = true
oracleMatcherSaysStop = assertion.matcherSaysStopTrying(matcher, actual)
matches, matcherErr = assertion.pollMatcher(matcher, actual)
}
renderError := func(preamble string, err error) string {
message := ""
if pollingSignalErr, ok := AsPollingSignalError(err); ok {
message = err.Error()
for _, attachment := range pollingSignalErr.Attachments {
message += fmt.Sprintf("\n%s:\n", attachment.Description)
message += format.Object(attachment.Object, 1)
}
} else {
message = preamble + "\n" + format.Object(err, 1)
}
return message
}
messageGenerator := func() string {
// can be called out of band by Ginkgo if the user requests a progress report
lock.Lock()
defer lock.Unlock()
message := ""
if actualErr == nil {
if matcherErr == nil {
if desiredMatch != matches {
if desiredMatch {
message += matcher.FailureMessage(actual)
} else {
message += matcher.NegatedFailureMessage(actual)
}
} else {
if assertion.asyncType == AsyncAssertionTypeConsistently {
message += "There is no failure as the matcher passed to Consistently has not yet failed"
} else {
message += "There is no failure as the matcher passed to Eventually succeeded on its most recent iteration"
}
}
} else {
var fgErr formattedGomegaError
if errors.As(actualErr, &fgErr) {
message += fgErr.FormattedGomegaError() + "\n"
} else {
message += renderError(fmt.Sprintf("The matcher passed to %s returned the following error:", assertion.asyncType), matcherErr)
}
}
} else {
var fgErr formattedGomegaError
if errors.As(actualErr, &fgErr) {
message += fgErr.FormattedGomegaError() + "\n"
} else {
message += renderError(fmt.Sprintf("The function passed to %s returned the following error:", assertion.asyncType), actualErr)
}
if hasLastValidActual {
message += fmt.Sprintf("\nAt one point, however, the function did return successfully.\nYet, %s failed because", assertion.asyncType)
_, e := matcher.Match(lastValidActual)
if e != nil {
message += renderError(" the matcher returned the following error:", e)
} else {
message += " the matcher was not satisfied:\n"
if desiredMatch {
message += matcher.FailureMessage(lastValidActual)
} else {
message += matcher.NegatedFailureMessage(lastValidActual)
}
}
}
}
description := assertion.buildDescription(optionalDescription...)
return fmt.Sprintf("%s%s", description, message)
}
fail := func(preamble string) {
assertion.g.THelper()
assertion.g.Fail(fmt.Sprintf("%s after %.3fs.\n%s", preamble, time.Since(timer).Seconds(), messageGenerator()), 3+assertion.offset)
}
var contextDone <-chan struct{}
if assertion.ctx != nil {
contextDone = assertion.ctx.Done()
if v, ok := assertion.ctx.Value("GINKGO_SPEC_CONTEXT").(contextWithAttachProgressReporter); ok {
detach := v.AttachProgressReporter(messageGenerator)
defer detach()
}
}
// Used to count the number of times in a row a step passed
passedRepeatedlyCount := 0
for {
var nextPoll <-chan time.Time = nil
var isTryAgainAfterError = false
for _, err := range []error{actualErr, matcherErr} {
if pollingSignalErr, ok := AsPollingSignalError(err); ok {
if pollingSignalErr.IsStopTrying() {
fail("Told to stop trying")
return false
}
if pollingSignalErr.IsTryAgainAfter() {
nextPoll = time.After(pollingSignalErr.TryAgainDuration())
isTryAgainAfterError = true
}
}
}
if actualErr == nil && matcherErr == nil && matches == desiredMatch {
if assertion.asyncType == AsyncAssertionTypeEventually {
passedRepeatedlyCount += 1
if passedRepeatedlyCount == assertion.mustPassRepeatedly {
return true
}
}
} else if !isTryAgainAfterError {
if assertion.asyncType == AsyncAssertionTypeConsistently {
fail("Failed")
return false
}
// Reset the consecutive pass count
passedRepeatedlyCount = 0
}
if oracleMatcherSaysStop {
if assertion.asyncType == AsyncAssertionTypeEventually {
fail("No future change is possible. Bailing out early")
return false
} else {
return true
}
}
if nextPoll == nil {
nextPoll = assertion.afterPolling()
}
select {
case <-nextPoll:
a, e := pollActual()
lock.Lock()
actual, actualErr = a, e
lock.Unlock()
if actualErr == nil {
lock.Lock()
lastValidActual = actual
hasLastValidActual = true
lock.Unlock()
oracleMatcherSaysStop = assertion.matcherSaysStopTrying(matcher, actual)
m, e := assertion.pollMatcher(matcher, actual)
lock.Lock()
matches, matcherErr = m, e
lock.Unlock()
}
case <-contextDone:
fail("Context was cancelled")
return false
case <-timeout:
if assertion.asyncType == AsyncAssertionTypeEventually {
fail("Timed out")
return false
} else {
if isTryAgainAfterError {
fail("Timed out while waiting on TryAgainAfter")
return false
}
return true
}
}
}
}
golang-gomega-1.27.10/internal/async_assertion_test.go 0000664 0000000 0000000 00000203445 14462163431 0023010 0 ustar 00root root 0000000 0000000 package internal_test
import (
"errors"
"fmt"
"reflect"
"runtime"
"strings"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"golang.org/x/net/context"
)
type quickMatcher struct {
matchFunc func(actual any) (bool, error)
oracleFunc func(actual any) bool
}
func (q quickMatcher) Match(actual any) (bool, error) {
return q.matchFunc(actual)
}
func (q quickMatcher) FailureMessage(actual any) (message string) {
return fmt.Sprintf("QM failure message: %v", actual)
}
func (q quickMatcher) NegatedFailureMessage(actual any) (message string) {
return fmt.Sprintf("QM negated failure message: %v", actual)
}
func (q quickMatcher) MatchMayChangeInTheFuture(actual interface{}) bool {
if q.oracleFunc == nil {
return true
}
return q.oracleFunc(actual)
}
func QuickMatcher(matchFunc func(actual any) (bool, error)) OmegaMatcher {
return quickMatcher{matchFunc, nil}
}
func QuickMatcherWithOracle(matchFunc func(actual any) (bool, error), oracleFunc func(actual any) bool) OmegaMatcher {
return quickMatcher{matchFunc, oracleFunc}
}
type FakeGinkgoSpecContext struct {
Attached func() string
Cancelled bool
}
func (f *FakeGinkgoSpecContext) AttachProgressReporter(v func() string) func() {
f.Attached = v
return func() { f.Cancelled = true }
}
var _ = Describe("Asynchronous Assertions", func() {
var ig *InstrumentedGomega
BeforeEach(func() {
ig = NewInstrumentedGomega()
})
Describe("Basic Eventually support", func() {
Context("the positive case", func() {
It("polls the function and matcher until a match occurs", func() {
counter := 0
ig.G.Eventually(func() string {
counter++
if counter > 5 {
return MATCH
}
return NO_MATCH
}).Should(SpecMatch())
Ω(counter).Should(Equal(6))
Ω(ig.FailureMessage).Should(BeZero())
})
It("continues polling even if the matcher errors", func() {
counter := 0
ig.G.Eventually(func() string {
counter++
if counter > 5 {
return MATCH
}
return ERR_MATCH
}).Should(SpecMatch())
Ω(counter).Should(Equal(6))
Ω(ig.FailureMessage).Should(BeZero())
})
It("times out eventually if the assertion doesn't match in time", func() {
counter := 0
ig.G.Eventually(func() string {
counter++
if counter > 100 {
return MATCH
}
return NO_MATCH
}).WithTimeout(200 * time.Millisecond).WithPolling(20 * time.Millisecond).Should(SpecMatch())
Ω(counter).Should(BeNumerically(">", 2))
Ω(counter).Should(BeNumerically("<", 20))
Ω(ig.FailureMessage).Should(ContainSubstring("Timed out after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
Ω(ig.FailureSkip).Should(Equal([]int{3}))
})
It("maps Within() correctly to timeout and polling intervals", func() {
counter := 0
ig.G.Eventually(func() bool {
counter++
return false
}).WithTimeout(0).WithPolling(20 * time.Millisecond).Within(200 * time.Millisecond).Should(BeTrue())
Ω(counter).Should(BeNumerically(">", 2))
Ω(counter).Should(BeNumerically("<", 20))
counter = 0
ig.G.Eventually(func() bool {
counter++
return false
}).WithTimeout(0).WithPolling(0). // first zero intervals, then set them
Within(200 * time.Millisecond).ProbeEvery(20 * time.Millisecond).
Should(BeTrue())
Ω(counter).Should(BeNumerically(">", 2))
Ω(counter).Should(BeNumerically("<", 20))
})
})
Context("the negative case", func() {
It("polls the function and matcher until a match does not occur", func() {
counter := 0
ig.G.Eventually(func() string {
counter++
if counter > 5 {
return NO_MATCH
}
return MATCH
}).ShouldNot(SpecMatch())
Ω(counter).Should(Equal(6))
Ω(ig.FailureMessage).Should(BeZero())
})
It("continues polling when the matcher errors - an error does not count as a successful non-match", func() {
counter := 0
ig.G.Eventually(func() string {
counter++
if counter > 5 {
return NO_MATCH
}
return ERR_MATCH
}).ShouldNot(SpecMatch())
Ω(counter).Should(Equal(6))
Ω(ig.FailureMessage).Should(BeZero())
})
It("times out eventually if the assertion doesn't match in time", func() {
counter := 0
ig.G.Eventually(func() string {
counter++
if counter > 100 {
return NO_MATCH
}
return MATCH
}).WithTimeout(200 * time.Millisecond).WithPolling(20 * time.Millisecond).ShouldNot(SpecMatch())
Ω(counter).Should(BeNumerically(">", 2))
Ω(counter).Should(BeNumerically("<", 20))
Ω(ig.FailureMessage).Should(ContainSubstring("Timed out after"))
Ω(ig.FailureMessage).Should(ContainSubstring("negative: match"))
Ω(ig.FailureSkip).Should(Equal([]int{3}))
})
})
Context("when a failure occurs", func() {
It("registers the appropriate helper functions", func() {
ig.G.Eventually(NO_MATCH).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Timed out after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
Ω(ig.FailureSkip).Should(Equal([]int{3}))
Ω(ig.RegisteredHelpers).Should(ContainElement("(*AsyncAssertion).Should"))
Ω(ig.RegisteredHelpers).Should(ContainElement("(*AsyncAssertion).match"))
})
It("renders the matcher's error if an error occured", func() {
ig.G.Eventually(ERR_MATCH).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Timed out after"))
Ω(ig.FailureMessage).Should(ContainSubstring("The matcher passed to Eventually returned the following error:"))
Ω(ig.FailureMessage).Should(ContainSubstring("spec matcher error"))
})
It("renders the optional description", func() {
ig.G.Eventually(NO_MATCH).WithTimeout(50*time.Millisecond).WithPolling(10*time.Millisecond).Should(SpecMatch(), "boop")
Ω(ig.FailureMessage).Should(ContainSubstring("boop"))
})
It("formats and renders the optional description when there are multiple arguments", func() {
ig.G.Eventually(NO_MATCH).WithTimeout(50*time.Millisecond).WithPolling(10*time.Millisecond).Should(SpecMatch(), "boop %d", 17)
Ω(ig.FailureMessage).Should(ContainSubstring("boop 17"))
})
It("calls the optional description if it is a function", func() {
ig.G.Eventually(NO_MATCH).WithTimeout(50*time.Millisecond).WithPolling(10*time.Millisecond).Should(SpecMatch(), func() string { return "boop" })
Ω(ig.FailureMessage).Should(ContainSubstring("boop"))
})
})
Context("with a passed-in context", func() {
Context("when the passed-in context is cancelled", func() {
It("stops and returns a failure", func() {
ctx, cancel := context.WithCancel(context.Background())
counter := 0
ig.G.Eventually(func() string {
counter++
if counter == 2 {
cancel()
} else if counter == 10 {
return MATCH
}
return NO_MATCH
}, time.Hour, ctx).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Context was cancelled after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
})
It("can also be configured via WithContext()", func() {
ctx, cancel := context.WithCancel(context.Background())
counter := 0
ig.G.Eventually(func() string {
counter++
if counter == 2 {
cancel()
} else if counter == 10 {
return MATCH
}
return NO_MATCH
}, time.Hour).WithContext(ctx).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Context was cancelled after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
})
It("can also be configured with the context up front", func() {
ctx, cancel := context.WithCancel(context.Background())
counter := 0
ig.G.Eventually(ctx, func() string {
counter++
if counter == 2 {
cancel()
} else if counter == 10 {
return MATCH
}
return NO_MATCH
}, time.Hour).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Context was cancelled after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
})
It("treats a leading context as an actual, even if valid durations are passed in", func() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
Eventually(ctx).Should(Equal(ctx))
Eventually(ctx, 0.1).Should(Equal(ctx))
})
It("counts as a failure for Consistently", func() {
ctx, cancel := context.WithCancel(context.Background())
counter := 0
ig.G.Consistently(func() string {
counter++
if counter == 2 {
cancel()
} else if counter == 10 {
return NO_MATCH
}
return MATCH
}, time.Hour).WithContext(ctx).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Context was cancelled after"))
Ω(ig.FailureMessage).Should(ContainSubstring("There is no failure as the matcher passed to Consistently has not yet failed"))
})
})
Context("when the passed-in context is a Ginkgo SpecContext that can take a progress reporter attachment", func() {
It("attaches a progress reporter context that allows it to report on demand", func() {
fakeSpecContext := &FakeGinkgoSpecContext{}
var message string
ctx := context.WithValue(context.Background(), "GINKGO_SPEC_CONTEXT", fakeSpecContext)
ig.G.Eventually(func() string {
if fakeSpecContext.Attached != nil {
message = fakeSpecContext.Attached()
}
return NO_MATCH
}).WithTimeout(time.Millisecond * 20).WithContext(ctx).Should(Equal(MATCH))
Ω(message).Should(Equal("Expected\n : no match\nto equal\n : match"))
Ω(fakeSpecContext.Cancelled).Should(BeTrue())
})
Context("when used with consistently", func() {
It("returns a useful message that does not invoke the matcher's failure handlers", func() {
fakeSpecContext := &FakeGinkgoSpecContext{}
var message string
ctx := context.WithValue(context.Background(), "GINKGO_SPEC_CONTEXT", fakeSpecContext)
ig.G.Consistently(func() error {
if fakeSpecContext.Attached != nil {
message = fakeSpecContext.Attached()
}
return nil
}).WithTimeout(time.Millisecond * 20).WithContext(ctx).ShouldNot(HaveOccurred())
Ω(message).Should(Equal("There is no failure as the matcher passed to Consistently has not yet failed"))
Ω(fakeSpecContext.Cancelled).Should(BeTrue())
})
})
})
Describe("the interaction between the context and the timeout", func() {
It("only relies on context cancellation when no explicit timeout is specified", func() {
ig.G.SetDefaultEventuallyTimeout(time.Millisecond * 10)
ig.G.SetDefaultEventuallyPollingInterval(time.Millisecond * 40)
t := time.Now()
ctx, cancel := context.WithCancel(context.Background())
iterations := 0
ig.G.Eventually(func() string {
iterations += 1
if time.Since(t) > time.Millisecond*200 {
cancel()
}
return "A"
}).WithContext(ctx).Should(Equal("B"))
Ω(time.Since(t)).Should(BeNumerically("~", time.Millisecond*200, time.Millisecond*100))
Ω(iterations).Should(BeNumerically("~", 200/40, 2))
Ω(ig.FailureMessage).Should(ContainSubstring("Context was cancelled after"))
})
It("uses the explicit timeout when it is provided", func() {
t := time.Now()
ctx, cancel := context.WithCancel(context.Background())
iterations := 0
ig.G.Eventually(func() string {
iterations += 1
if time.Since(t) > time.Millisecond*200 {
cancel()
}
return "A"
}).WithContext(ctx).WithTimeout(time.Millisecond * 80).ProbeEvery(time.Millisecond * 40).Should(Equal("B"))
Ω(time.Since(t)).Should(BeNumerically("~", time.Millisecond*80, time.Millisecond*40))
Ω(iterations).Should(BeNumerically("~", 80/40, 2))
Ω(ig.FailureMessage).Should(ContainSubstring("Timed out after"))
})
})
})
})
Describe("Basic Consistently support", func() {
Context("the positive case", func() {
It("polls the function and matcher ensuring a match occurs consistently", func() {
counter := 0
ig.G.Consistently(func() string {
counter++
return MATCH
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(SpecMatch())
Ω(counter).Should(BeNumerically(">", 1))
Ω(counter).Should(BeNumerically("<", 7))
Ω(ig.FailureMessage).Should(BeZero())
})
It("fails if the matcher ever errors", func() {
counter := 0
ig.G.Consistently(func() string {
counter++
if counter == 3 {
return ERR_MATCH
}
return MATCH
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(SpecMatch())
Ω(counter).Should(Equal(3))
Ω(ig.FailureMessage).Should(ContainSubstring("Failed after"))
Ω(ig.FailureMessage).Should(ContainSubstring("The matcher passed to Consistently returned the following error:"))
Ω(ig.FailureMessage).Should(ContainSubstring("spec matcher error"))
})
It("fails if the matcher doesn't match at any point", func() {
counter := 0
ig.G.Consistently(func() string {
counter++
if counter == 3 {
return NO_MATCH
}
return MATCH
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(SpecMatch())
Ω(counter).Should(Equal(3))
Ω(ig.FailureMessage).Should(ContainSubstring("Failed after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
})
})
Context("the negative case", func() {
It("polls the function and matcher ensuring a match never occurs", func() {
counter := 0
ig.G.Consistently(func() string {
counter++
return NO_MATCH
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).ShouldNot(SpecMatch())
Ω(counter).Should(BeNumerically(">", 1))
Ω(counter).Should(BeNumerically("<", 7))
Ω(ig.FailureMessage).Should(BeZero())
})
It("fails if the matcher ever errors", func() {
counter := 0
ig.G.Consistently(func() string {
counter++
if counter == 3 {
return ERR_MATCH
}
return NO_MATCH
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).ShouldNot(SpecMatch())
Ω(counter).Should(Equal(3))
Ω(ig.FailureMessage).Should(ContainSubstring("Failed after"))
Ω(ig.FailureMessage).Should(ContainSubstring("spec matcher error"))
})
It("fails if the matcher matches at any point", func() {
counter := 0
ig.G.Consistently(func() string {
counter++
if counter == 3 {
return MATCH
}
return NO_MATCH
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).ShouldNot(SpecMatch())
Ω(counter).Should(Equal(3))
Ω(ig.FailureMessage).Should(ContainSubstring("Failed after"))
Ω(ig.FailureMessage).Should(ContainSubstring("negative: match"))
})
})
Context("when a failure occurs", func() {
It("registers the appropriate helper functions", func() {
ig.G.Consistently(NO_MATCH).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Failed after"))
Ω(ig.FailureMessage).Should(ContainSubstring("positive: no match"))
Ω(ig.FailureSkip).Should(Equal([]int{3}))
Ω(ig.RegisteredHelpers).Should(ContainElement("(*AsyncAssertion).Should"))
Ω(ig.RegisteredHelpers).Should(ContainElement("(*AsyncAssertion).match"))
})
It("renders the matcher's error if an error occured", func() {
ig.G.Consistently(ERR_MATCH).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Failed after"))
Ω(ig.FailureMessage).Should(ContainSubstring("The matcher passed to Consistently returned the following error:"))
Ω(ig.FailureMessage).Should(ContainSubstring("spec matcher error"))
})
It("renders the optional description", func() {
ig.G.Consistently(NO_MATCH).Should(SpecMatch(), "boop")
Ω(ig.FailureMessage).Should(ContainSubstring("boop"))
})
It("formats and renders the optional description when there are multiple arguments", func() {
ig.G.Consistently(NO_MATCH).Should(SpecMatch(), "boop %d", 17)
Ω(ig.FailureMessage).Should(ContainSubstring("boop 17"))
})
It("calls the optional description if it is a function", func() {
ig.G.Consistently(NO_MATCH).Should(SpecMatch(), func() string { return "boop" })
Ω(ig.FailureMessage).Should(ContainSubstring("boop"))
})
})
Context("with a passed-in context", func() {
Context("when the passed-in context is cancelled", func() {
It("counts as a failure for Consistently", func() {
ctx, cancel := context.WithCancel(context.Background())
counter := 0
ig.G.Consistently(func() string {
counter++
if counter == 2 {
cancel()
} else if counter == 10 {
return NO_MATCH
}
return MATCH
}, time.Hour).WithContext(ctx).Should(SpecMatch())
Ω(ig.FailureMessage).Should(ContainSubstring("Context was cancelled after"))
Ω(ig.FailureMessage).Should(ContainSubstring("There is no failure as the matcher passed to Consistently has not yet failed"))
})
})
Describe("the interaction between the context and the timeout", func() {
It("only always uses the default interval even if not explicit duration is provided", func() {
ig.G.SetDefaultConsistentlyDuration(time.Millisecond * 200)
ig.G.SetDefaultConsistentlyPollingInterval(time.Millisecond * 40)
t := time.Now()
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
iterations := 0
ig.G.Consistently(func() string {
iterations += 1
return "A"
}).WithContext(ctx).Should(Equal("A"))
Ω(time.Since(t)).Should(BeNumerically("~", time.Millisecond*200, time.Millisecond*100))
Ω(iterations).Should(BeNumerically("~", 200/40, 2))
Ω(ig.FailureMessage).Should(BeZero())
})
})
})
})
Describe("the passed-in actual", func() {
type Foo struct{ Bar string }
Context("when passed a value", func() {
It("(eventually) continuously checks on the value until a match occurs", func() {
c := make(chan bool)
go func() {
time.Sleep(100 * time.Millisecond)
close(c)
}()
ig.G.Eventually(c).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).Should(BeClosed())
Ω(ig.FailureMessage).Should(BeZero())
})
It("(consistently) continuously checks on the value ensuring a match always occurs", func() {
c := make(chan bool)
close(c)
ig.G.Consistently(c).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(BeClosed())
Ω(ig.FailureMessage).Should(BeZero())
})
})
Context("when passed a function that takes no arguments and returns one value", func() {
It("(eventually) polls the function until the returned value satisfies the matcher", func() {
counter := 0
ig.G.Eventually(func() int {
counter += 1
return counter
}).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).Should(BeNumerically(">", 5))
Ω(ig.FailureMessage).Should(BeZero())
})
It("(consistently) polls the function ensuring the returned value satisfies the matcher", func() {
counter := 0
ig.G.Consistently(func() int {
counter += 1
return counter
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 20))
Ω(counter).Should(BeNumerically(">", 2))
Ω(ig.FailureMessage).Should(BeZero())
})
It("works when the function returns nil", func() {
counter := 0
ig.G.Eventually(func() error {
counter += 1
if counter > 5 {
return nil
}
return errors.New("oops")
}).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).Should(BeNil())
Ω(ig.FailureMessage).Should(BeZero())
})
})
Context("when passed a function that takes no arguments and returns multiple values", func() {
Context("with Eventually", func() {
It("polls the function until the first returned value satisfies the matcher _and_ all additional values are zero", func() {
counter, s, f, err := 0, "hi", Foo{Bar: "hi"}, errors.New("hi")
ig.G.Eventually(func() (int, string, Foo, error) {
switch counter += 1; counter {
case 2:
s = ""
case 3:
f = Foo{}
case 4:
err = nil
}
return counter, s, f, err
}).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 100))
Ω(ig.FailureMessage).Should(BeZero())
Ω(counter).Should(Equal(4))
})
It("reports on the non-zero value if it times out", func() {
ig.G.Eventually(func() (int, string, Foo, error) {
return 1, "", Foo{Bar: "hi"}, nil
}).WithTimeout(30 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 100))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Eventually had an unexpected non-nil/non-zero return value at index 2:"))
Ω(ig.FailureMessage).Should(ContainSubstring(`: {Bar: "hi"}`))
})
It("has a meaningful message if all the return values are zero except the final return value, and it is an error", func() {
ig.G.Eventually(func() (int, string, Foo, error) {
return 1, "", Foo{}, errors.New("welp!")
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 100))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Eventually returned the following error:"))
Ω(ig.FailureMessage).Should(ContainSubstring("welp!"))
})
Context("when making a ShouldNot assertion", func() {
It("doesn't succeed until the matcher is (not) satisfied with the first returned value _and_ all additional values are zero", func() {
counter, s, f, err := 0, "hi", Foo{Bar: "hi"}, errors.New("hi")
ig.G.Eventually(func() (int, string, Foo, error) {
switch counter += 1; counter {
case 2:
s = ""
case 3:
f = Foo{}
case 4:
err = nil
}
return counter, s, f, err
}).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).ShouldNot(BeNumerically("<", 0))
Ω(ig.FailureMessage).Should(BeZero())
Ω(counter).Should(Equal(4))
})
})
})
Context("with Consistently", func() {
It("polls the function and succeeds if all the values are zero and the matcher is consistently satisfied", func() {
var err error
counter, s, f := 0, "", Foo{}
ig.G.Consistently(func() (int, string, Foo, error) {
counter += 1
return counter, s, f, err
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 100))
Ω(ig.FailureMessage).Should(BeZero())
Ω(counter).Should(BeNumerically(">", 2))
})
It("polls the function and fails any of the values are non-zero", func() {
var err error
counter, s, f := 0, "", Foo{}
ig.G.Consistently(func() (int, string, Foo, error) {
counter += 1
if counter == 3 {
f = Foo{Bar: "welp"}
}
return counter, s, f, err
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 100))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Consistently had an unexpected non-nil/non-zero return value at index 2:"))
Ω(ig.FailureMessage).Should(ContainSubstring(`: {Bar: "welp"}`))
Ω(counter).Should(Equal(3))
})
Context("when making a ShouldNot assertion", func() {
It("succeeds if all additional values are zero", func() {
var err error
counter, s, f := 0, "", Foo{}
ig.G.Consistently(func() (int, string, Foo, error) {
counter += 1
return counter, s, f, err
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).ShouldNot(BeNumerically(">", 100))
Ω(ig.FailureMessage).Should(BeZero())
Ω(counter).Should(BeNumerically(">", 2))
})
It("fails if any additional values are ever non-zero", func() {
var err error
counter, s, f := 0, "", Foo{}
ig.G.Consistently(func() (int, string, Foo, error) {
counter += 1
if counter == 3 {
s = "welp"
}
return counter, s, f, err
}).WithTimeout(50 * time.Millisecond).WithPolling(10 * time.Millisecond).ShouldNot(BeNumerically(">", 100))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Consistently had an unexpected non-nil/non-zero return value at index 1:"))
Ω(ig.FailureMessage).Should(ContainSubstring(`: welp`))
Ω(counter).Should(Equal(3))
})
})
})
})
Context("when passed a function that takes a Gomega argument and returns values", func() {
Context("with Eventually", func() {
It("passes in a Gomega and passes if the matcher matches, all extra values are zero, and there are no failed assertions", func() {
counter, s, f, err := 0, "hi", Foo{Bar: "hi"}, errors.New("hi")
ig.G.Eventually(func(g Gomega) (int, string, Foo, error) {
switch counter += 1; counter {
case 2:
s = ""
case 3:
f = Foo{}
case 4:
err = nil
}
if counter == 5 {
g.Expect(true).To(BeTrue())
} else {
g.Expect(false).To(BeTrue())
panic("boom") //never see since the expectation stops execution
}
return counter, s, f, err
}).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).Should(BeNumerically("<", 100))
Ω(ig.FailureMessage).Should(BeZero())
Ω(counter).Should(Equal(5))
})
It("times out if assertions in the function never succeed and reports on the error", func() {
_, file, line, _ := runtime.Caller(0)
ig.G.Eventually(func(g Gomega) int {
g.Expect(false).To(BeTrue())
return 10
}).WithTimeout(30 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(Equal(10))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Eventually failed at %s:%d with:", file, line+2))
Ω(ig.FailureMessage).Should(ContainSubstring("Expected\n : false\nto be true"))
})
It("forwards panics", func() {
Ω(func() {
ig.G.Eventually(func(g Gomega) int {
g.Expect(true).To(BeTrue())
panic("boom")
}).WithTimeout(30 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(Equal(10))
}).Should(PanicWith("boom"))
Ω(ig.FailureMessage).Should(BeEmpty())
})
It("correctly handles the case (in concert with Ginkgo) when an assertion fails in a goroutine", func() {
count := 0
ig.G.Eventually(func(g Gomega) {
c := make(chan interface{})
go func() {
defer GinkgoRecover()
defer close(c)
count += 1
g.Expect(count).To(Equal(3)) //panics!
}()
<-c
}).WithTimeout(30 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(Succeed())
Ω(count).Should(Equal(3))
})
Context("when making a ShouldNot assertion", func() {
It("doesn't succeed until all extra values are zero, there are no failed assertions, and the matcher is (not) satisfied", func() {
counter, s, f, err := 0, "hi", Foo{Bar: "hi"}, errors.New("hi")
ig.G.Eventually(func(g Gomega) (int, string, Foo, error) {
switch counter += 1; counter {
case 2:
s = ""
case 3:
f = Foo{}
case 4:
err = nil
}
if counter == 5 {
g.Expect(true).To(BeTrue())
} else {
g.Expect(false).To(BeTrue())
panic("boom") //never see since the expectation stops execution
}
return counter, s, f, err
}).WithTimeout(1 * time.Second).WithPolling(10 * time.Millisecond).ShouldNot(BeNumerically("<", 0))
Ω(ig.FailureMessage).Should(BeZero())
Ω(counter).Should(Equal(5))
})
})
It("fails if an assertion is never satisfied", func() {
_, file, line, _ := runtime.Caller(0)
ig.G.Eventually(func(g Gomega) int {
g.Expect(false).To(BeTrue())
return 9
}).WithTimeout(30 * time.Millisecond).WithPolling(10 * time.Millisecond).ShouldNot(Equal(10))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Eventually failed at %s:%d with:", file, line+2))
Ω(ig.FailureMessage).Should(ContainSubstring("Expected\n : false\nto be true"))
})
It("shows the state of the last match if there was a non-failing funciton at some point", func() {
counter := 0
_, file, line, _ := runtime.Caller(0)
ig.G.Eventually(func(g Gomega) int {
counter += 1
g.Expect(counter).To(BeNumerically("<", 3))
return counter
}).WithTimeout(100 * time.Millisecond).WithPolling(10 * time.Millisecond).Should(Equal(10))
Ω(ig.FailureMessage).Should(ContainSubstring("The function passed to Eventually failed at %s:%d with:\nExpected\n : ", file, line+3))
Ω(ig.FailureMessage).Should(ContainSubstring("to be <\n 
