Detailed explanation of testable example function (Example Function) in Golang

Golang testable example with function (Example Function)

Example functions are similar to unit test functions, but without parameters of type *testing . It's also easy to write example functions:

1. Create the corresponding test file: Create a new file (in the same package as the tested code file) under the source code directory of the Go project, with the suffix _test.go. For example, to test the method in dial.go in the net package, create a file named dial_test.go or net_test.go or example_test.go in the net package, which is the same as the unit test file.
2. Write an example function: In the test file, write a function prefixed with Example, followed by one or more characters or character combinations to identify the name of the test case (generally use the name of the object under test, such as package name, function name, structure name, etc., may also be followed by no characters), without any parameters.
3. Write the usage method in the method body, and output the content to standard output. At the end of the method body, you can add "Output:" or "Unordered output:" comments, or you don't need to add them. If an "Output:" annotation is added, the output will be compared exactly to the annotation. If an "Unordered output:" annotation is added, the output is also compared to the annotation, but line order is ignored. Without adding any output annotations, the example function is compiled but not executed.

Testable example with function example

Take the json format verification tool https://github.com/luduoxin/json-validator-go as an example, the key function Valid in the scanner.go file in the validator package is used to verify whether a given string is in json format, corresponding to The test file is scanner_test.go, the example function inside is ExampleValid, the code is as follows:

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	// output: true
}

Run to see the effect:

=== RUN   ExampleValid
--- PASS: ExampleValid (0.00s)
PASS

See an example with multiple output results:

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	fmt.Println(Valid([]byte(`a:b`)))
	// output: true
	// false
}

Run to see the effect:

=== RUN   ExampleValid
--- PASS: ExampleValid (0.00s)
PASS

See an example of an "Unordered output:" annotation:

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	fmt.Println(Valid([]byte(`{"a":"b"}`)))
	// Unordered output: true
	// true
}

Run to see the effect:

=== RUN   ExampleValid
--- PASS: ExampleValid (0.00s)
PASS

Look at an example that fails the test:

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
	fmt.Println(Valid([]byte(`{"a":"b"}`)))
	// Unordered output: true
	// false
}

Run to see the effect:

=== RUN   ExampleValid
--- FAIL: ExampleValid (0.00s)
got:
true
true

See an example without the output annotation:

func ExampleValid() {
	fmt.Println(Valid([]byte("{}")))
}

Run the go test command, this function will not be executed.

What does it mean to pass the above test example (the example whose running result is PASS)? It is when the example is executed that the test framework captures the data written to standard output, and compares it with the result in the "output:" annotation, if it matches, the test passes, otherwise the test fails (result is FAIL).

Presentation in Godoc

The example function will be used as an example of the corresponding function in Godoc, see a screenshot of the official Golang:

 

Godoc uses a naming convention to associate example functions with package-level identifiers. The agreed rules are as follows:

func ExampleFoo()     // documents the Foo function or type
func ExampleBar_Qux() // documents the Qux method of type Bar
func Example()        // documents the package as a whole

Following this convention, Godoc will display the ExampleReverse example alongside the documentation for the Reverse function. Multiple instances can be given for a given function (or package, struct, method, etc.) by using a suffix starting with an underscore followed by a lowercase letter. as follows:

func ExampleReverse()
func ExampleReverse_second()
func ExampleReverse_third()

summary

This article explains in detail the testable example functions in Golang, which can be easily converted into highly readable documents in Godoc. This is also a best practice of code as documentation advocated by Golang. If you haven't used it yet, hurry up Let's use it.