DEV Community: Maxime Soulé

[ANN] go-testdeep v1.13.0 is available

Maxime Soulé — Mon, 20 Mar 2023 22:04:43 +0000

A new release of go-testdeep has just been published.

As a remainder, go-testdeep is a powerful golang tests framework, using a comparison engine of its own and providing 67 operators to compare anything, in any situation, at any nested level.

Major features in this release follow:

5 new operators are available, allowing to test wrapped errors (ErrorIs), channels content (Recv) and only some elements of slices/arrays (First, Grep & Last);
JSON operator reaches an unmatched level so far, making it definitely the best solution to do JSON comparisons in golang world;
unique anchoring feature is now available using a new generic way, a must! ;)
others details can be found on the release page.

Enjoy!

Home: https://go-testdeep.zetta.rocks
Repo: https://github.com/maxatome/go-testdeep
Godoc: https://pkg.go.dev/github.com/maxatome/go-testdeep/td

PS: don't mistake go-testdeep for go-test/deep, both are a tests framework, but go-testdeep is much more powerful in every situations.

Large repo switched to new go1.19 doc comments

Maxime Soulé — Sun, 07 Aug 2022 19:08:33 +0000

go 1.19 introduces new doc comments formatting features, allowing to easily insert links and lists.

Details are described here → https://go.dev/doc/comment

Links & lists

Links are probably the most interesting feature as they permit to enhance the documentation by providing users hints without inserting full URL as one needs before:

// The allowed shortcut operators follow:
//   - [Empty]    → $^Empty
//   - [Ignore]   → $^Ignore
//   - [NaN]      → $^NaN
//   - [Nil]      → $^Nil
//   - [NotEmpty] → $^NotEmpty
//   - [NotNaN]   → $^NotNaN
//   - [NotNil]   → $^NotNil
//   - [NotZero]  → $^NotZero
//   - [Zero]     → $^Zero
//
// TypeBehind method returns the [reflect.Type] of the expectedJSON
// once JSON unmarshaled. So it can be bool, string, float64, []any,
// map[string]any or any in case expectedJSON is "null".
//
// See also [JSONPointer], [SubJSONOf] and [SuperJSONOf].

produces:

The listing feature is also used above. Before go 1.19, indented bullets were detected as a simple code block and were displayed with a monospaced font.

Links can reference local exported identifiers (like JSONPointer or SubJSONOf) as well as identifiers in other packages (like reflect.Type).

To produce links to other resources, one can now define links using the Markdown shortcut reference link format (without the optional title text) as in:

// MultipartBody is a body of a multipart/form-data HTTP request (by
// default, or any other multipart/… body, see MediaType field) as
// defined in [RFC 2046] to be used as a [io.Reader] body of
// [http.Request] and so compliant with [RFC 2388]. It implements
// [io.Reader] and can only be read once. See [PostMultipartFormData]
// and [TestAPI.PostMultipartFormData] for examples of use.
//
// [RFC 2046]: https://tools.ietf.org/html/rfc2046
// [RFC 2388]: https://tools.ietf.org/html/rfc2388

producing:

Note that these shortcuts are scoped to the comment they are declared in.

Full example

To see the result on a large repository, I adapted the comments of go-testdeep to fully take advantage of these new features.

You can see the result for each impacted package:

A few remarks

It seems that pkg.go.dev hasn't handled [links] in lists yet. I say "yet", because the last version of godoc handles them properly. So I suppose it will be fixed soon.

Struct fields links work for standard packages, but not for local/current one. For example [http.Cookie.Raw] produces a link to the Raw field of Cookie in net/http package (example), but in go-testdeep td package [ContextConfig.RootName] remains intact and so is not changed into a link, even when using the last version of godoc.

Links are not handled in var or const comments when a single keyword groups several declarations:

// DefaultContextConfig is the default configuration used to render
// tests failures. If overridden, new settings will impact all Cmp*
// functions and [*T] methods (if not specifically configured.)
var DefaultContextConfig = ContextConfig{…}

is OK, but:

var (
  // DefaultContextConfig is the default configuration used to render
  // tests failures. If overridden, new settings will impact all Cmp*
  // functions and [*T] methods (if not specifically configured.)
  DefaultContextConfig = ContextConfig{
)

does not work, [*T] remains intact in generated godoc. It is too bad.

Some ideas

[x] could be a builtin pointing to https://pkg.go.dev/builtin#x, like error for example, for all native types, as we see them in signatures.

It could be cool to have shortcut reference links global to the package, perhaps in the package doc itself. It would avoid to declare in each comment the same shortcut again and again.

It can be interesting that the shortcut reference links accept indirect URLs. For example, in td I often talk about Cmp* functions. Each time, I would like to reference Cmp function (the first one of the Cmp* serie). To do it, I have to set the full URL in the shortcut:

// [Cmp*]: https://pkg.go.dev/github.com/maxatome/go-testdeep/td#Cmp

while simply using:

// [Cmp*]: Cmp

would avoid referencing pkg.go.dev as [Cmp] does elsewhere.

Conclusion

The result of using these new features is pretty cool. Let's hope that package authors will enhance their docs to help their users to easily discover their APIs, in a more friendly way.

Install ImageMagick6 and ImageMagick7 on FreeBSD

Maxime Soulé — Fri, 01 May 2020 21:28:15 +0000

On FreeBSD, ImageMagick6 and ImageMagick7 packages cannot be installed at the same time as they have several files in common.

It becomes a problem when some packages depend on ImageMagick6 (as inkscape for example) and some others on ImageMagick7 (as emacs for example).

To circumvent this problem, we can "patch" the ImageMagick6 package to delete the files installed by ImageMagick7.

So ImageMagick7 is installed:

$ pkg info ImageMagick\*                              
ImageMagick7-7.0.10.6

First download the ImageMagick6 package:

$ pkg=$(pkg rquery %q/%n-%v ImageMagick6)
$ fetch https://pkg.freebsd.org/${pkg%%/*}/latest/All/${pkg#*/}.txz

Then download the "package-patcher" script:

$ fetch https://gist.githubusercontent.com/maxatome/dcd48de511f087c10f02a59405f134b6/raw/9e9843d87dace00e506ea848c69cf29ad09dbf6a/patch-ImageMagick6.pl

Do not forget to look at its content before executing it!

L27 it creates a temporary directory that it automatically cleaned up at end;
L29-31 it extracts the package it it
L33-34 it reads the +MANIFEST to get the list of package files;
L36-57 it deletes unneeded files from +MANIFEST and from disk
L59-63 it rewrites the +MANIFEST
L65-75 it creates a new package adding -libonly to the original package name.

Then (no need to be root at this step), patch the package:

$ perl patch-ImageMagick6.pl ${pkg#*/}.txz
Extracting /usr/home/max/tmp/ImageMagick6-6.9.11.6,1.txz
tar: Removing leading '/' from member names
Patching
Creating new /usr/home/max/tmp/ImageMagick6-libonly-6.9.11.6,1.txz
/usr/home/max/tmp/ImageMagick6-libonly-6.9.11.6,1.txz produced.

Just install the produced package using pkg install as root:

# pkg install ImageMagick6-libonly-6.9.11.6,1.txz
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
Checking integrity... done (0 conflicting)
The following 1 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
    ImageMagick6: 6.9.11.6,1

Number of packages to be installed: 1

The process will require 27 MiB more space.

Proceed with this action? [y/N]: y
[1/1] Installing ImageMagick6-6.9.11.6,1...
Extracting ImageMagick6-6.9.11.6,1: 100%

inkscape package can now be installed without any conflict with emacs, as both versions of ImageMagick are installed:

> pkg info ImageMagick\*                          
ImageMagick6-6.9.11.6,1
ImageMagick7-7.0.10.6

It is a good idea to lock the ImageMagick6 package to avoid that the next pkg upgrade raise a conflict:

# pkg lock ImageMagick6-6.9.11.6,1 
ImageMagick6-6.9.11.6,1: lock this package? [y/N]: y
Locking ImageMagick6-6.9.11.6,1

go-testdeep v1.4.0 released

Maxime Soulé — Sun, 19 Apr 2020 14:43:11 +0000

As a powerful and two-year-old testing framework, go-testdeep allows you to deeply test any golang data structure. It is fully integrated with testing standard package.

import (
  "testing"
  "github.com/maxatome/go-testdeep/td"
)

func TestLoadPerson(t *testing.T) {
  // LoadPerson() (Person, error)
  person, err := LoadPerson()
  if td.CmpNoError(t, err) {
    // person has to match exactly
    td.Cmp(t, person, Person{Name: "Bob", Age: 24})
  }
}

But many testing frameworks allow you to do this kind of comparison, no need for a new one!

As go-testdeep uses its own function to deeply compare structures, it allows you to use 60 operators for more flexibility.

Take the Bag operator as an example:

import (
  "testing"
  "github.com/maxatome/go-testdeep/td"
)

func TestLoadPersons(t *testing.T) {
  // LoadPersons(string) ([]Person, error)
  persons, err := LoadPersons("B*")
  if td.CmpNoError(t, err) {
    // persons slice has to contains these 4 persons
    // in whatever order
    td.Cmp(t, persons,
      td.Bag(
        Person{Name: "Bob", Age: 24},
        Person{Name: "Britt", Age: 29},
        Person{Name: "Barbara", Age: 35},
        Person{Name: "Brian", Age: 21},
      ))
  }
}

It is just an example, as the tests can be much more complex. See:

the synopsis;
an example from classic approach to the go-testdeep ones;
the FAQ, it contains some examples too.

The tdhttp helper package allows you to easily test your HTTP API using these operators.
See the example of a simple JSON/XML HTTP API tested using go-testdeep and its tdhttp package under the Go Play Space: https://goplay.space/#xrGKu2cNQFr

It reports colored error messages when something goes wrong, here used with another operator, Between:

All the functions and methods are fully documented, each operator comes with its examples, and last but not least the test code coverage is close to 100%.

Do not hesitate to comment, file an issue or a PR. I would be happy to help you or simply discuss.

Enjoy!

home — godoc

maxatome / go-testdeep

Extremely flexible golang deep comparison, extends the go testing package and tests HTTP APIs

go-testdeep

Extremely flexible golang deep comparison, extends the go testing package.

Latest news

2020/04/11
- tdhttp helper (the HTTP API tester) enhanced and fully documented;
2020/04/06
- new Delay operator;
2020/02/29
- github.com/maxatome/go-testdeep deprecated (but still usable), use github.com/maxatome/go-testdeep/td instead. See the FAQ point for details about migration;
2020/02/13:
- new operator anchoring feature, see the corresponding FAQ section and the new anchoring methods;
- new SStruct operator (and its friends CmpSStruct & T.SStruct),
see commits history for other/older changes.

Synopsis

Make golang tests easy, from simplest usage:

import (
  "testing"

  "github.com/maxatome/go-testdeep/td"
)

func TestMyFunc(t *testing.T) {
  td.Cmp(t, MyFunc(), &Info{Name: "Alice", Age: 42})
}

To a bit more complex one, allowing…

View on GitHub