googleapis · IlyaFaer · Sep 17, 2021 · Apr 19, 2021 · Apr 20, 2021 · Apr 21, 2021
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -26,3 +26,29 @@ information on using pull requests.
 
 This project follows [Google's Open Source Community
 Guidelines](https://opensource.google/conduct/).
+
+## Running tests
+
+SQLAlchemy Spanner dialect includes a test suite, which can be executed both on a live service and Spanner emulator.
+
+**Using pytest**
+To execute the test suite with standard `pytest` package you only need to checkout to the package folder and run:
+```
+pytest -v
+```
+
+**Using nox**
+The package includes a configuration file for `nox` package, which allows to execute the dialect test suite in an isolated virtual environment. To execute all the `nox` sessions checkout to the dialect folder and then run command:
+```
+nox
+```
+To execute only the dialect compliance test suite execute command:
+```
+nox -s compliance_test
+```
+
+**Live service**
+To run the test suite on a live service use [setup.cfg](https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy/blob/main/setup.cfg) `db.default` attribute to set URI of the project, instance and database, where the tests should be executed.
+
+**Emulator**
+As the dialect is built on top of the Spanner DB API, it also supports running on Spanner emulator. To make it happen you need to set an environment variable, pointing to the emulator service, for example `SPANNER_EMULATOR_HOST=localhost:9010`
diff --git a/noxfile.py b/noxfile.py
@@ -64,7 +64,7 @@ class = StreamHandler
 
 
 BLACK_VERSION = "black==19.10b0"
-BLACK_PATHS = ["google", "test", "noxfile.py", "setup.py"]
+BLACK_PATHS = ["google", "test", "noxfile.py", "setup.py", "samples"]
 DEFAULT_PYTHON_VERSION = "3.8"
 
 
@@ -178,3 +178,26 @@ def migration_test(session):
     session.run("python", "migration_test_cleanup.py")
     if os.path.exists("test.cfg"):
         os.remove("test.cfg")
+
+
+@nox.session(python=DEFAULT_PYTHON_VERSION)
+def snippets(session):
+    """Run the documentation example snippets."""
+    # Sanity check: Only run snippets system tests if the environment variable
+    # is set.
+    if not os.environ.get("GOOGLE_APPLICATION_CREDENTIALS", ""):
+        session.skip("Credentials must be set via environment variable.")
+
+    session.install("pytest")
+    session.install("sqlalchemy")
+    session.install(
+        "git+https://github.com/googleapis/python-spanner.git#egg=google-cloud-spanner"
+    )
+    session.install("-e", ".")
+    session.run("python", "create_test_database.py")
+    session.run(
+        "py.test",
+        "--quiet",
+        os.path.join("samples", "snippets_test.py"),
+        *session.posargs,
+    )
diff --git a/samples/__init__.py b/samples/__init__.py
diff --git a/samples/conftest.py b/samples/conftest.py
@@ -0,0 +1,92 @@
+# Copyright 2021 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
+#
+#     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.
+
+import datetime
+import uuid
+
+import pytest
+
+from sqlalchemy import (
+    Column,
+    Integer,
+    MetaData,
+    String,
+    Table,
+    create_engine,
+    ForeignKey,
+)
+
+
+@pytest.fixture
+def db_url():
+    return (
+        "spanner:///projects/appdev-soda-spanner-staging/instances/"
+        "sqlalchemy-dialect-test/databases/compliance-test"
+    )
+
+
+@pytest.fixture
+def table_id():
+    now = datetime.datetime.now()
+    table_id = "example_table_{}_{}".format(
+        now.strftime("%Y%m%d%H%M%S"), uuid.uuid4().hex[:8]
+    )
+    return table_id
+
+
+@pytest.fixture
+def table(db_url, table_id):
+    engine = create_engine(db_url)
+    metadata = MetaData(bind=engine)
+
+    table = Table(
+        table_id,
+        metadata,
+        Column("user_id", Integer, primary_key=True),
+        Column("user_name", String(16), nullable=False),
+    )
+    table.create()
+    yield table
+    table.drop()
+
+
+@pytest.fixture
+def table_w_foreign_key(db_url, table):
+    engine = create_engine(db_url)
+    metadata = MetaData(bind=engine)
+
+    table_fk = Table(
+        "table_fk",
+        metadata,
+        Column("id", Integer, primary_key=True),
+        Column("name", String(16), nullable=False),
+        Column(
+            table.name + "_user_id",
+            Integer,
+            ForeignKey(table.c.user_id, name=table.name + "user_id"),
+        ),
+    )
+    table_fk.create()
+    yield table_fk
+    table_fk.drop()
+
+
+@pytest.fixture
+def connection(db_url):
+    engine = create_engine(db_url)
+    return engine.connect()
+
+
+def insert_data(conn, table, data):
+    conn.execute(table.insert(), data)