test

gox test discovers, compiles and runs the tests and benchmarks of a GOX application.

This page documents the command and its options. Testing explains how to write requests, expectations and pipelines into the test files.

Use

bash
gox test [files] [options]
OptionDescription
-run Run tests that match the pattern.
-bench Run benchmarks that match the pattern.
--vPrint each detailed result.
-out. Write the overall result on JSON.

Discovery

bash
gox test

No arguments, GOX walks tests/ and discovers all files with extension .gox. The files are processed in alphabetical order.

Within each file, the runner performs in alphabetical order the normal functions, without parameters and finished in Test.

The project configuration is compiled before creating the testing runtime in memory.

Select Files

It is possible to provide files or folders:

bash
gox test tests/index.gox
gox test tests/session

The folders are run recursively. Relative routes can be written from the root of the project with or without the initial prefix tests/.

Only files are included .goxA non-existing route or file with another extension produces an error.

Select Tests

-run accepts a regular expression applied to the name of the functions:

bash
gox test -run IndexTest
gox test -run 'Session.*Test'

It can also be combined with files or folders. If the pattern is invalid or no function matches, the command ends with an error.

After selecting a file or folder, GOX also supports one or more test names as positional selectors:

bash
gox test tests/index.gox IndexTest
gox test tests/session SessionTest SessionPipelineTest

Positional names are combined as exact coincidences. They cannot be combined with -run.

Benchmarks

-bench changes the execution mode and uses a regular expression to select functions:

bash
gox test -bench IndexTest
gox test tests/http.gox -bench 'Route.*Test'

-run and -bench cannot be used together. Benchmarks are shown with the tag BENCH and may include global metrics and by step.

See the documentation for Benchmarks to set up iterations, warmove and sampling of allocations.

Output

Functional tests use:

text
PASS tests/index.gox::IndexTest
FAIL tests/session.gox::SessionTest

The messages recorded by test.Pass(), test.Fail() and test.Explain() appear below the corresponding function. The command ends with error if at least one test or Benchmark fails.

Detailed output

bash
gox test --v

--v print on JSON each result recorded by test.Execute(). If a function performs several executions, each result is shown separately.

Global report

bash
gox test -out report.json

-out write a JSON report with the files, functions, results, duration and totals of the execution.

A relative route is resolved within tests/An absolute route can also be provided.

Options not available

The runner recognizes the following options, but are not yet implemented:

text
-race
-cpuprofile <file>
-memprofile <file>

Its use produces an error and does not run the tests. They do not appear yet in the public support of the command.

Request logs

During gox test, the normal log of each HTTP request is temporarily deactivated to keep output readable. The messages and diagnoses of the testing system remain available.

Best practices

  • Run all tests before integrating changes.
  • Use -run to isolate a case during development.
  • Use specific and easy-to-play regular expressions.
  • Do not combine functional tests and benchmarks in the same invocation.
  • Use -out when you need to keep or process a global report.
  • Do not depend on options that are not yet implemented.

See also

Next step

Continue with Testing to learn how to write tests, define expectations and run pipelines against a GOX application.

Testing