diff --git a/.gitignore b/.gitignore index 9aca50cb9..5f96b19ab 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ user.bazelrc # docs build artifacts /_build* docs/ubproject.toml +/ubproject.toml # Vale - editorial style guide .vale.ini diff --git a/bzl/basics.bzl b/bzl/basics.bzl new file mode 100644 index 000000000..102071f2c --- /dev/null +++ b/bzl/basics.bzl @@ -0,0 +1,49 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +def join_path(prefix, rest): + """Compose two docname segments with `/`. + + Args: + prefix: Leading docname segment, possibly empty. + rest: Trailing docname segment, possibly empty. + + Returns: + The combined docname. + """ + if not prefix or prefix == ".": + return rest + if not rest: + return prefix + return prefix + "/" + rest + +def dirname(path): + """ + Return the leading docname segment of a docname, + e.g. the directory portion of a filepath. + """ + + idx = path.rfind("/") + return "" if idx < 0 else path[:idx] + +def doc_source_globs(source_dir): + """Return glob for documentation sources below ``source_dir``.""" + + extensions = [ + "png", "svg", "md", "rst", "html", "css", + "puml", "need", "yaml", "json", "csv", "inc", + ] + return native.glob( + [join_path(source_dir, "**/*." + ext) for ext in extensions], + allow_empty = True + ) diff --git a/docs.bzl b/docs.bzl index d89a1ac4c..da0ea4ab0 100644 --- a/docs.bzl +++ b/docs.bzl @@ -45,6 +45,8 @@ load("@aspect_rules_py//py:defs.bzl", "py_binary", "py_venv") load("@docs_as_code_hub_env//:requirements.bzl", "all_requirements") load("@sphinxdocs//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs") +load("@score_docs_as_code//:bzl/basics.bzl", "join_path", "dirname", "doc_source_globs") + def _rewrite_needs_json_to_docs_sources(labels): """Replace '@repo//:needs_json' -> '@repo//:docs_sources' for every item.""" out = [] @@ -71,8 +73,9 @@ def _merge_sourcelinks(name, sourcelinks, known_good = None): """Merge multiple sourcelinks JSON files into a single file. Args: - name: Name for the merged sourcelinks target - sourcelinks: List of sourcelinks JSON file targets + name: Name for the merged sourcelinks target. + sourcelinks: Sourcelinks JSON file targets. + known_good: Optional known-good sourcelinks JSON target. """ extra_srcs = [] @@ -96,24 +99,31 @@ def _merge_sourcelinks(name, sourcelinks, known_good = None): tools = [merge_sourcelinks_tool], ) +def _requirement_package_name(target): + """Extract the package name represented by a requirement target. + + Args: + target: Requirement label or label-like value. + + Returns: + The package-name portion used for dependency comparison. + """ + return str(target).split("/")[-1].split(":")[0] + + def _missing_requirements(deps): - """Add Python hub dependencies if they are missing.""" - found = [] - missing = [] - def _target_to_packagename(target): - return str(target).split("/")[-1].split(":")[0] - all_packages = [_target_to_packagename(pkg) for pkg in all_requirements] - def _find(pkg): - for dep in deps: - dep_pkg = _target_to_packagename(dep) - if dep_pkg == pkg: - return True - return False - for pkg in all_packages: - if _find(pkg): - found.append(pkg) - else: - missing.append(pkg) + """Return missing Python hub dependencies or reject partial inclusion. + + Args: + deps: User-provided Python dependency labels. + + Returns: + All hub requirements when none are present, otherwise an empty list. + """ + requested_packages = [_requirement_package_name(dep) for dep in deps] + all_packages = [_requirement_package_name(pkg) for pkg in all_requirements] + found = [pkg for pkg in all_packages if pkg in requested_packages] + missing = [pkg for pkg in all_packages if pkg not in requested_packages] if len(missing) == len(all_requirements): #print("All docs-as-code dependencies are missing, adding all of them.") return all_requirements @@ -142,11 +152,6 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good = file instead of the default metamodel shipped with score_metamodel. """ - call_path = native.package_name() - - if call_path != "": - fail("docs() must be called from the root package. Current package: " + call_path) - metamodel_data = [] metamodel_env = {} metamodel_opts = [] @@ -171,30 +176,10 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good = deps = deps, ) - # If the source directory is the root (".") we must omit it, otherwise: - # > invalid glob pattern './**/*.png': segment '.' not permitted - if source_dir == ".": - source_prefix = "" - else: - source_prefix = source_dir + "/" native.filegroup( name = "docs_sources", - srcs = native.glob([ - source_prefix + "**/*.png", - source_prefix + "**/*.svg", - source_prefix + "**/*.md", - source_prefix + "**/*.rst", - source_prefix + "**/*.html", - source_prefix + "**/*.css", - source_prefix + "**/*.puml", - source_prefix + "**/*.need", - source_prefix + "**/*.yaml", - source_prefix + "**/*.json", - source_prefix + "**/*.csv", - source_prefix + "**/*.inc", - ], allow_empty = True), - visibility = ["//visibility:public"], + srcs = doc_source_globs(source_dir), ) _sourcelinks_json(name = "sourcelinks_json", srcs = scan_code) @@ -301,7 +286,7 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good = sphinx_docs( name = "needs_json", srcs = [":docs_sources"], - config = ":" + source_prefix + "conf.py", + config = ":" + join_path(source_dir, "conf.py"), extra_opts = [ "-W", "--keep-going", @@ -342,8 +327,8 @@ def _sourcelinks_json(name, srcs): See https://eclipse-score.github.io/docs-as-code/main/how-to/source_to_doc_links.html Args: - name: Name of the target - srcs: Source files to scan for traceability tags + name: Name of the target. + srcs: Source files to scan for traceability tags. """ output_file = name + ".json" diff --git a/docs/how-to/faq.md b/docs/how-to/faq.md deleted file mode 100644 index dbfc5bdb0..000000000 --- a/docs/how-to/faq.md +++ /dev/null @@ -1,106 +0,0 @@ - - -# FAQ - -*docs-as-code is the S-CORE tool for building documentation, defining requirements and -verifying compliance.* - -In this document you will find answers to frequently asked questions regarding -docs-as-code and its usage. - - -## Why is docs-as-code so slow? - -The performance of docs-as-code has significantly improved in version 1.0.0 and later. - -## IDE support (auto completion, metamodel checks, preview, LSP capabilities) - -Since 1.0.0 IDE support works via esbonio. You'll need to install the esbonio extension -for your IDE (e.g., VSCode, PyCharm, etc.). Your repository must also be configured for -esbonio (settings.json). - -If this does not work, please use the live preview feature: `bazel run //:live_preview`. -This provides immediate metamodel feedback (although only on the console) and -IDE-agnostic preview capabilities. - -Another option is to use the [ubCode](https://ubcode.useblocks.com) extension for -VS Code. It provides lightning-fast linting, formatting, previewing, navigation and -analytical features for large Sphinx and Sphinx-Needs projects. -The `ubproject.toml` configuration file gets generated automatically when a Sphinx -build is running once. The file can safely be committed to the repository to enable -IDE support without requiring a Sphinx build first. - -### Esbonio - -Known issues: -* Python is required at startup, which is a problem for any Python-based LSP. We are - working to improve this by providing a devcontainer with Python preinstalled. - Additionally, we have submitted a feature request for Esbonio to handle Python - installation. - - For now please run `bazel run //:ide_support` and restart VS Code. - - -### ubc - -Currently, ubc is not aware of our metamodel. As a result, checks and auto-completion -features are not available. - -We plan to explore improvements in this area in the future together with useblocks. -These features are on the immediate roadmap. - - -## Do we need to write custom Python code for every Metamodel check? -With our current approach, allowed attributes and links for Needs are defined within the -`metamodel.yml` file. If the check can be fully described there (e.g., process -requirements are only allowed to link to stakeholder requirements), no custom code is -needed. It is also not necessary to write individual tests for every single check -performed by the metamodel. - -Only a few very specific checks require custom Python code beyond the generic metamodel -capabilities. These are cases that cannot be addressed by generic metamodel approaches -in any tool. For example: "the middle part of certain IDs must match the directory name -of the file." - - -## How can I be sure that the Metamodel does what I want it to do? -We use *examples* written in reStructuredText (rst) to verify that the metamodel has -been configured as intended. - -Metamodel checks are verified through standard testing practices, like any other code. -The examples mentioned above are helpful, but they are only examples. They are not -mandatory for verification of the metamodel checks. - - - -## Sphinx and safety -It is important to distinguish between metamodel checks and HTML rendering. - -Metamodel checks can be verified / qualified without Sphinx. - -If the renderer is safety-relevant, then qualification of Sphinx (and Sphinx Needs) is -required. This is currently under evaluation by the process team (@aschemmel-tech). - - -## What about versioning of requirements? -We are currently discussing possible implementations to enable linking to specific -versions of requirements (e.g. `implements: req-5@v3.0.0`). - - -## Sphinx traceability -It is possible to link requirements from other requirements, from source code, or from -tests (tests within the next days). - -### What about bazel targets? -Bazel targets are not involved in traceability (currently not required by process). diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 7cae52036..cb2d38a29 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -25,7 +25,6 @@ Here you find practical guides on how to use docs-as-code. get_started setup write_docs - faq other_modules dashboards_and_quality_gates source_to_doc_links diff --git a/src/tests/README.md b/src/tests/README.md index 66dcfaab1..03d77f341 100644 --- a/src/tests/README.md +++ b/src/tests/README.md @@ -1,104 +1,27 @@ -# Docs-As-Code Consumer Tests + -## Use in CI +# `docs()` end-to-end tests -If you want to start the consumer tests on a PR inside `docs-as-code`, then all you have to do is comment -`/consumer-test` on the PR and this should trigger them. +*Also known as system, product, or black-box tests.* -## Quick Start +This directory contains end-to-end tests for the public `docs()` macro. They exercise documentation builds through the public interface, rather than testing implementation details. -```bash -# Create the virtual environment -bazel run //:ide_support - -# Run with std. configuration -.venv_docs/bin/python -m pytest -s src/tests - -# Run with more verbose output (up to -vvv) -.venv_docs/bin/python -m pytest -s -v src/tests - -# Run specific repositories only -.venv_docs/bin/python -m pytest -s src/tests --repo=score - -# Disable the persistent cache -.venv_docs/bin/python -m pytest -s src/tests --disable-cache - -# Or combine both options -.venv_docs/bin/python -m pytest -s src/tests --disable-cache --repo=score -``` +It contains: -## Verbosity Levels +- `docs_e2e`: A reusable baseline for end-to-end tests of the public `docs()` macro. It defines a minimal documentation project using `docs()`. The test starts the generated `:docs` binary, waits for Sphinx to produce the HTML output, and verifies that `_build/index.html` exists. -The test suite supports different levels of output detail: +- `downstream_compatibility`: *(formerly consumer tests)* Tests local changes and Git-based overrides against real consumer repositories. This provides broad, intentionally less-controlled coverage and helps detect breaking changes in the docs-as-code system before they affect downstream consumers. -- **No flags**: Basic test results and summary table -- **`-v`**: Shows detailed warnings breakdown by logger type -- **`-vv`**: Adds full stdout/stderr output from build commands -- **`-vvv`**: Streams build output in real-time (useful for debugging hanging builds) +## Targets -## Command Line Options +You can query targets in this directory with: -### `--disable-cache` -Disabled persistent caching for clean testing cycle. - -**What the test normaly do:** -- Uses `~/.cache/docs_as_code_consumer_tests` instead of temporary directories -- Reuses cloned repositories between runs (with git updates) -- Significantly speeds up subsequent test runs - -**This option disables the above mentioned behaviour and clones the repositories fresh** - -**When to use:** During development when you need to ensure testing is done on a fresh env. - -### `--repo` -Filters which repositories to test. - -**Usage:** ```bash -# Test only the 'score' repository -.venv_docs/bin/python -m pytest -s src/tests --repo=score - -# Test multiple repositories -.venv_docs/bin/python -m pytest -s src/tests --repo=score,module_template - -# Invalid repo names fall back to testing all repositories -.venv_docs/bin/python -m pytest -s src/tests --repo=nonexistent -``` - -**Available repositories:** Check `REPOS_TO_TEST` in the test file for current list. - -## Currently tested repositories - -- [score](https://github.com/eclipse-score/score) -- [process_description](https://github.com/eclipse-score/process_description) -- [module_template](https://github.com/eclipse-score/module_template) - -## What Gets Tested - -For each repository, the test: -1. Clones the consumer repository -2. Tests with **local override** (your current changes) -3. Tests with **git override** (current commit from remote) -4. Runs build commands and test commands -5. Analyzes warnings and build success - -## Example Development Workflow - -```bash -# Create the virtual environment -bazel run //:ide_support - -# First run - clones everything fresh -.venv_docs/bin/python -m pytest -s -v src/tests --repo=score - -# Make changes to docs-as-code... - -# Subsequent runs - much faster due to caching -.venv_docs/bin/python -m pytest -s -v src/tests --repo=score - -# Final validation - test all repos without cache -.venv_docs/bin/python -m pytest -s -v src/tests --disable-cache +bazel query 'kind(".*_test", //src/tests/...)' ``` diff --git a/src/tests/downstream_compatibility/BUILD b/src/tests/downstream_compatibility/BUILD new file mode 100644 index 000000000..85796f4be --- /dev/null +++ b/src/tests/downstream_compatibility/BUILD @@ -0,0 +1,30 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +load("@aspect_rules_py//py:defs.bzl", "py_library") +load("//:docs.bzl", "docs") +load("//:score_pytest.bzl", "score_pytest") + +score_pytest( + name = "test", + size = "large", + srcs = ["test_consumer.py"], + data = [], + deps = [], + env = {}, +) diff --git a/src/tests/downstream_compatibility/README.md b/src/tests/downstream_compatibility/README.md new file mode 100644 index 000000000..66dcfaab1 --- /dev/null +++ b/src/tests/downstream_compatibility/README.md @@ -0,0 +1,104 @@ +# Docs-As-Code Consumer Tests + +This test validates that changes to the docs-as-code system don't break downstream consumers. +It tests both local changes and git-based overrides against real consumer repositories. + +## Use in CI + +If you want to start the consumer tests on a PR inside `docs-as-code`, then all you have to do is comment +`/consumer-test` on the PR and this should trigger them. + +## Quick Start + +```bash +# Create the virtual environment +bazel run //:ide_support + +# Run with std. configuration +.venv_docs/bin/python -m pytest -s src/tests + +# Run with more verbose output (up to -vvv) +.venv_docs/bin/python -m pytest -s -v src/tests + +# Run specific repositories only +.venv_docs/bin/python -m pytest -s src/tests --repo=score + +# Disable the persistent cache +.venv_docs/bin/python -m pytest -s src/tests --disable-cache + +# Or combine both options +.venv_docs/bin/python -m pytest -s src/tests --disable-cache --repo=score +``` + +## Verbosity Levels + +The test suite supports different levels of output detail: + +- **No flags**: Basic test results and summary table +- **`-v`**: Shows detailed warnings breakdown by logger type +- **`-vv`**: Adds full stdout/stderr output from build commands +- **`-vvv`**: Streams build output in real-time (useful for debugging hanging builds) + +## Command Line Options + +### `--disable-cache` +Disabled persistent caching for clean testing cycle. + +**What the test normaly do:** +- Uses `~/.cache/docs_as_code_consumer_tests` instead of temporary directories +- Reuses cloned repositories between runs (with git updates) +- Significantly speeds up subsequent test runs + +**This option disables the above mentioned behaviour and clones the repositories fresh** + +**When to use:** During development when you need to ensure testing is done on a fresh env. + +### `--repo` +Filters which repositories to test. + +**Usage:** +```bash +# Test only the 'score' repository +.venv_docs/bin/python -m pytest -s src/tests --repo=score + +# Test multiple repositories +.venv_docs/bin/python -m pytest -s src/tests --repo=score,module_template + +# Invalid repo names fall back to testing all repositories +.venv_docs/bin/python -m pytest -s src/tests --repo=nonexistent +``` + +**Available repositories:** Check `REPOS_TO_TEST` in the test file for current list. + +## Currently tested repositories + +- [score](https://github.com/eclipse-score/score) +- [process_description](https://github.com/eclipse-score/process_description) +- [module_template](https://github.com/eclipse-score/module_template) + +## What Gets Tested + +For each repository, the test: +1. Clones the consumer repository +2. Tests with **local override** (your current changes) +3. Tests with **git override** (current commit from remote) +4. Runs build commands and test commands +5. Analyzes warnings and build success + +## Example Development Workflow + +```bash +# Create the virtual environment +bazel run //:ide_support + +# First run - clones everything fresh +.venv_docs/bin/python -m pytest -s -v src/tests --repo=score + +# Make changes to docs-as-code... + +# Subsequent runs - much faster due to caching +.venv_docs/bin/python -m pytest -s -v src/tests --repo=score + +# Final validation - test all repos without cache +.venv_docs/bin/python -m pytest -s -v src/tests --disable-cache +``` diff --git a/src/tests/conftest.py b/src/tests/downstream_compatibility/conftest.py similarity index 100% rename from src/tests/conftest.py rename to src/tests/downstream_compatibility/conftest.py diff --git a/src/tests/test_consumer.py b/src/tests/downstream_compatibility/test_consumer.py similarity index 98% rename from src/tests/test_consumer.py rename to src/tests/downstream_compatibility/test_consumer.py index 046c35c67..651003052 100644 --- a/src/tests/test_consumer.py +++ b/src/tests/downstream_compatibility/test_consumer.py @@ -222,6 +222,8 @@ def _ensure_repo(repo_path: Path, git_url: str, use_cache: bool) -> None: def _cleanup_before_cmd(cwd: Path, cmd: str) -> None: # ubproject.toml is created by :docs + # Delete in cwd (repo root) and any subdir to avoid stale config from previous runs + (cwd / "ubproject.toml").unlink(missing_ok=True) for p in cwd.glob("*/ubproject.toml"): p.unlink() diff --git a/src/tests/e2e/BUILD b/src/tests/e2e/BUILD new file mode 100644 index 000000000..8215eef36 --- /dev/null +++ b/src/tests/e2e/BUILD @@ -0,0 +1,27 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +load("@aspect_rules_py//py:defs.bzl", "py_library") +load("//:docs.bzl", "docs") + +py_library( + name = "e2e_support", + srcs = ["support.py"], + imports = ["."], + visibility = ["//visibility:public"], +) diff --git a/src/tests/e2e/README.md b/src/tests/e2e/README.md new file mode 100644 index 000000000..b5cbf5f0e --- /dev/null +++ b/src/tests/e2e/README.md @@ -0,0 +1,26 @@ + + +# Generic docs() end-to-end test + +This package is the reusable baseline for end-to-end tests of the public +docs() macro. + +Run: + + bazel test //src/tests/docs_e2e:basics + +The fixture defines a minimal documentation project with docs(). The test +starts the resulting :docs binary, waits for Sphinx to build HTML, and checks +that _build/index.html exists. + +support.py contains the common runner. It creates an isolated writable +workspace for the docs binary, copies the fixture source tree, supplies the +runtime environment, and preserves the runfiles layout required by Bazel. +Feature-specific tests should reuse this runner and add only their fixture data +and user-visible assertions. diff --git a/src/tests/e2e/basic/BUILD b/src/tests/e2e/basic/BUILD new file mode 100644 index 000000000..7beb6d2f5 --- /dev/null +++ b/src/tests/e2e/basic/BUILD @@ -0,0 +1,30 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +load("@score_docs_as_code//:docs.bzl", "docs") +load("@score_docs_as_code//src/tests/e2e:support.bzl", "e2e_test") + +docs( + source_dir = "docs", +) + +e2e_test( + name = "test", + srcs = ["test.py"], + + # source_dir must be passed redundantly here, so that the test can access the docs source files. + source_dir = "docs", + + # docs must be passed redundantly here as a data dependency. + data = glob(["docs/**/*"]), +) diff --git a/src/tests/e2e/basic/docs/conf.py b/src/tests/e2e/basic/docs/conf.py new file mode 100644 index 000000000..9b0fd6e88 --- /dev/null +++ b/src/tests/e2e/basic/docs/conf.py @@ -0,0 +1,16 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +project = "Basic Test" +project_url = "https://github.com/eclipse-score/docs-as-code" +extensions = ["score_sphinx_bundle"] diff --git a/src/tests/e2e/basic/docs/index.rst b/src/tests/e2e/basic/docs/index.rst new file mode 100644 index 000000000..cc8afd54b --- /dev/null +++ b/src/tests/e2e/basic/docs/index.rst @@ -0,0 +1,16 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Basic Test +========== diff --git a/src/tests/e2e/basic/test.py b/src/tests/e2e/basic/test.py new file mode 100644 index 000000000..7de0c0603 --- /dev/null +++ b/src/tests/e2e/basic/test.py @@ -0,0 +1,36 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +"""End-to-end test for a minimal docs() project without mounts.""" + +from pathlib import Path + +import pytest +from support import run_docs_build, runfile + + +def test_docs_builds_html(tmp_path: Path, pytestconfig: pytest.Config): + """docs() builds the host documentation without a mount configuration.""" + + result = run_docs_build( + tmp_path, + docs_binary=runfile("DOCS_BINARY"), + source_dir=runfile("SOURCE_DIR"), + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert (tmp_path / "_build" / "index.html").is_file() diff --git a/src/tests/e2e/host_docs/conf.py b/src/tests/e2e/host_docs/conf.py new file mode 100644 index 000000000..aa1a04fed --- /dev/null +++ b/src/tests/e2e/host_docs/conf.py @@ -0,0 +1,21 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +project = "Docs E2E fixture" +project_url = "https://example.invalid/docs-e2e" +extensions = ["score_sphinx_bundle"] diff --git a/src/tests/e2e/host_docs/index.rst b/src/tests/e2e/host_docs/index.rst new file mode 100644 index 000000000..3634bf390 --- /dev/null +++ b/src/tests/e2e/host_docs/index.rst @@ -0,0 +1,15 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* +Docs E2E fixture +================ diff --git a/src/tests/e2e/support.bzl b/src/tests/e2e/support.bzl new file mode 100644 index 000000000..4a04f5ef9 --- /dev/null +++ b/src/tests/e2e/support.bzl @@ -0,0 +1,44 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +load("//:score_pytest.bzl", "score_pytest") + +def e2e_test(name, srcs, source_dir, data, deps = [], env = {}): + """Helper function to define an end-to-end test for docs(). + + Args: + name: The name of the test target. + srcs: The source files for the test (python files). + source_dir: The source directory for the docs. + data: The data dependencies for the test. + deps: The dependencies for the test. + env: The environment variables for the test. + """ + score_pytest( + name = name, + size = "medium", + srcs = srcs, + data = data + [ + # provide the actual target to pytest for execution, + # since `bazel test` would have created it, but not executed it. + # pytest will run it directly. + ":docs", + + # provide generated artifacts to pytest, so that they can be verified. + ":sourcelinks_json", + ], + deps = deps + ["//src/tests/e2e:e2e_support"], + env = { + "DOCS_BINARY": "$(rootpath :docs)", + "SOURCE_DIR": source_dir, + }, + ) diff --git a/src/tests/e2e/support.py b/src/tests/e2e/support.py new file mode 100644 index 000000000..f690a46b9 --- /dev/null +++ b/src/tests/e2e/support.py @@ -0,0 +1,99 @@ +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +# ******************************************************************************* +# Copyright (c) 2026 Contributors to the Eclipse Foundation +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* +"""Shared runner for end-to-end tests of docs() binaries.""" + +import os +import shutil +import subprocess +from pathlib import Path + + +def test_dir() -> Path: + """ + Return the path to the test directory. + e.g. /home/alex/git/etas-contrib/eclipse-score_docs-as-code/src/tests/docs_e2e + + WARNING: Using this will make the test non-hermetic, as it will depend on the source tree being present. + """ + return Path(__file__).resolve().parent + + +def runfiles_dir() -> Path: + """ + Return the path to bazel runfiles (content as provided via `data` in the BUILD file). + + e.g. /home/alex/.cache/bazel/_bazel_alex/ec58ecca617edd0b2864120a40405cd7/sandbox/linux-sandbox/2190/execroot/_main/bazel-out/k8-fastbuild/bin/src/tests/docs_e2e/basic.runfiles/_main + + Note: this should be used for accessing runfiles, not test_dir(), as it is hermetic + and will work even with remote execution. The test_dir() is only useful for + debugging and development. + """ + return Path(os.environ["TEST_SRCDIR"]) / os.environ["TEST_WORKSPACE"] + + +def list_runfiles_dir() -> None: + """List all content of runfiles_dir for debugging purposes.""" + + print("----") + for item in runfiles_dir().iterdir(): + print(f"runfiles_dir: {item.relative_to(runfiles_dir())}") + print("----") + + +def runfile(path_env: str) -> Path: + """Resolve a runfiles-relative path passed through a test environment variable.""" + + return runfiles_dir() / os.environ[path_env] + + +def run_docs_build( + tmp_path: Path, + *, + docs_binary: Path, + source_dir: Path, +) -> subprocess.CompletedProcess[str]: + """Run prepared docs() in an isolated writable workspace. + + The binary normally runs from a developer's workspace. This helper provides + the small writable equivalent needed by a Bazel test while preserving the + runfiles layout used to resolve in-tree mount sources. + """ + + (tmp_path / "src").symlink_to(runfiles_dir() / "src", target_is_directory=True) + + source_dir = tmp_path / "docs" + shutil.copytree(source_dir, tmp_path / "docs") + for name in ["MODULE.bazel", "MODULE.bazel.lock", "BUILD"]: + (tmp_path / name).touch() + + # env preparation normally happens in the docs() binary, + # but since we need to execute it ourselfes, + # we need to prepare the environment manually. + env = os.environ.copy() + env["SOURCE_DIRECTORY"] = str(source_dir) + env["DATA"] = "[]" + env["ACTION"] = "incremental" + + return subprocess.run( + [str(docs_binary)], + cwd=tmp_path, + env=env, + capture_output=True, + text=True, + check=True, + )