github.com/stackb/rules_proto@v0.0.0-20240221195024-5428336c51f1/example/golden/README.md (about)

     1  # golden example tests
     2  
     3  The tests in this package are used to:
     4  
     5  1. that gazelle runs properly (generates correct output from BUILD.in to
     6     BUILD.out)
     7  2. that the build artifacts can actually be built (bazel build //...).
     8  3. Generate documentation.
     9  
    10  `//example/golden:golden_test` runs the gazelle tests.  Each subdirectory of
    11  `testdata/*` represents a separate test.  The `BUILD.in` file is used as the
    12  base, and `BUILD.out` is expected to be generated.  If there is a diff against
    13  the actual `BUILD.out`, the test fails.
    14  
    15  The individual `gazelle_testdata_example` tests package up specific examples and
    16  generate a `go_bazel_test` for the example.  So for `//example/golden:java`, a
    17  `//example/golden:java_test` will run a test that actually tries to build
    18  everything within the workspace based on the contents of `BUILD.out`.
    19  
    20  # debugging golden example tests
    21  
    22  Have any `BUILD.bazel` files crept into the `vendor/` tree?  These are globbed
    23  in `//:all_files` and the presence of one will elide files in that package from
    24  the glob.  You might not see them because they are .gitignored.
    25  
    26  ```
    27  bazel query //:all_files --output build > all_files.BUILD
    28  ```
    29  
    30  Try and build from the main test workspace.  To do that, open up rules_go in the
    31  external tree and disable the cleanup function.  For example:
    32  
    33  ```
    34  $ (cd $(bazel info output_base)/external/io_bazel_rules_go && code .)
    35  $ code go/tools/bazel_testing/bazel_testing.go
    36  ```
    37  
    38  ```diff
    39      workspaceDir, cleanup, err := setupWorkspace(args, files)
    40      defer func() {
    41  +       if err == nil {
    42  +           log.Println("NOTE: skipping cleanup")
    43  +           return
    44  +       }
    45          if err := cleanup(); err != nil {
    46              fmt.Fprintf(os.Stderr, "cleanup error: %v\n", err)
    47              // Don't fail the test on a cleanup error.
    48              // Some operating systems (windows, maybe also darwin) can't reliably
    49              // delete executable files after they're run.
    50          }
    51      }()
    52  ```
    53  
    54  Then, go into the directory that the `go_bazel_test` creates and run bazel there directly:
    55  
    56  ```sh
    57  $ pushd /private/var/tmp/_bazel_pcj/092d6dadaf86f07590903c45033f576e/bazel_testing/bazel_go_test/main
    58  $ bazel build ...
    59  ```