feat: add golden testing (#262)

* test: add initial test data and update gitignore

* test: add missing file

* test: add goldens

* test: add golden test

* test: update gapic-combo to pubsub from bigquery

* test: update goldens

* test: remove unused tests

* chore: remove further unused files

* test: update golden test logic for repo

* test: update goldens with new repo

test: omit gapic-combo

test: include gapic-combo again in goldens

* fix: sort TOC alphabetically by href

* test: restrict to 3.9

* test: address review comments for test_goldens

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* chore: update presubmit name

* fix: address review comment

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

.github/workflows/ci.yaml

@@ -1,4 +1,4 @@
-name: ci
+name: Presubmit tests
 
 on: [push]
 
@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: [3.9]
 
     steps:
       - uses: actions/checkout@v3
@@ -21,11 +21,5 @@ jobs:
           pip install tox
       - name: Run tests
         run: |
-          tox -e docs
-      - name: Run unittest
-        run: |
-          tox -e unittest
-      - name: Run librarytest
-        run: |
-          tox -e librarytest
+          tox -e tests
 

.gitignore

@@ -46,6 +46,7 @@ pip-log.txt
 
 # Built documentation
 docs/_build
+tests/testdata/*/docs/_build
 bigquery/docs/generated
 docs.metadata
 

docfx_yaml/markdown_utils.py

@@ -259,6 +259,9 @@ def move_markdown_pages(app: sphinx.application, outdir: Path) -> None:
         print("There's no markdown file to move.")
         return
 
+    # Used to keep track of the index page entry to insert later.
+    index_page_entry = None
+
     # For each file, if it is a markdown file move to the top level pages.
     for mdfile in markdown_dir.iterdir():
         if mdfile.is_file() and mdfile.name.lower() not in files_to_ignore:
@@ -291,11 +294,11 @@ def move_markdown_pages(app: sphinx.application, outdir: Path) -> None:
 
             # Use Overview as the name for index file.
             if mdfile_name_to_use == 'index.md':
-                # Place the Overview page at the top of the list.
-                app.env.markdown_pages.insert(
-                    0,
-                    {'name':'Overview', 'href': 'index.md'}
-                )
+                # Save the index page entry.
+                index_page_entry = {
+                    'name': 'Overview',
+                    'href': 'index.md'
+                }
                 continue
 
             # Add the file to the TOC later.
@@ -304,6 +307,22 @@ def move_markdown_pages(app: sphinx.application, outdir: Path) -> None:
                 'href': mdfile_name_to_use,
             })
 
+    if app.env.markdown_pages:
+        # Sort the TOC alphabetically based on href entry.
+        app.env.markdown_pages = sorted(
+            app.env.markdown_pages,
+            key=lambda entry: entry['href'],
+        )
+
+        if index_page_entry is None:
+            return
+
+        # Place the Overview page at the top of the list.
+        app.env.markdown_pages.insert(
+            0,
+            index_page_entry,
+        )
+
 
 def run_sphinx_markdown() -> None:
     """Runs sphinx-build with Markdown builder in the plugin."""

requirements.txt

@@ -1,7 +1,15 @@
+# Install Sphinx plugin
+-e .
+
+# Tox specific dependencies
+tox
+mock
+pytest
+
+# Other dependencies
 black==22.10.0
 parameterized==0.8.1
 # google-resumable-media-python requires manual update as this repo isn't templated.
 # python-api-core also requires manual update as it is not templated.
 sphinx==4.5.0
 -e .
-tox

readthedocs.yml → tests/conftest.py

@@ -1,22 +1,24 @@
-# Copyright 2021 Google LLC
+# Copyright 2022 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#      http://www.apache.org/licenses/LICENSE-2.0
+#     https://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Don't build any extra formats
+import pytest
 
-formats:
-    - none
-python:
-   version: 3
-   setup_py_install: true
 
+def pytest_addoption(parser):
+    parser.addoption("--update-goldens", action="store", default=False)
+
+
+@pytest.fixture
+def update_goldens(request):
+    return request.config.getoption("--update-goldens")