From 7098a0d3963c0bd67e7b65a5a601621d11d25e3b Mon Sep 17 00:00:00 2001
From: Chad Woolley <cwoolley@gitlab.com>
Date: Tue, 30 Aug 2022 18:46:19 +0000
Subject: [PATCH] DRY up and clean up GLFM fixtures
- Extract common fixture setup to new shared context
- Move shared contexts to common glfm directory
- Renaming files for consistency
- Clean up and improve some file reading and
other logic
MR: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96325
---
.../specification_guide/index.md | 79 ++++-
.../requests/api/markdown_snapshot_spec.rb | 10 +
.../example_snapshots/examples_index.yml | 18 ++
glfm_specification/example_snapshots/html.yml | 42 +++
.../example_snapshots/markdown.yml | 12 +
.../example_snapshots/prosemirror_json.yml | 12 +
.../glfm_canonical_examples.txt | 61 ++++
.../glfm_example_metadata.yml | 14 +
.../glfm_example_status.yml | 36 +++
glfm_specification/output/spec.txt | 61 ++++
scripts/glfm/run-snapshot-tests.sh | 6 +-
scripts/lib/glfm/constants.rb | 8 +-
scripts/lib/glfm/render_static_html.rb | 27 +-
scripts/lib/glfm/update_example_snapshots.rb | 54 ++--
spec/requests/api/markdown_snapshot_spec.rb | 4 +-
spec/scripts/lib/glfm/parse_examples_spec.rb | 8 +-
.../lib/glfm/update_example_snapshots_spec.rb | 306 ++++++++++++++++--
.../lib/glfm/update_specification_spec.rb | 21 +-
.../api_markdown_snapshot_shared_context.rb} | 34 +-
.../glfm/example_snapshot_fixtures.rb | 27 ++
20 files changed, 723 insertions(+), 117 deletions(-)
create mode 100644 ee/spec/requests/api/markdown_snapshot_spec.rb
create mode 100644 glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml
rename spec/support/shared_contexts/{markdown_snapshot_shared_examples.rb => glfm/api_markdown_snapshot_shared_context.rb} (66%)
create mode 100644 spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb
diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md
index f2d813cb993f8..c1227e5d33f4c 100644
--- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md
+++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md
@@ -345,8 +345,50 @@ For the [Markdown snapshot testing](#markdown-snapshot-testing) to work
properly, you must account for these differences in a way that ensures the tests are reliable,
and always behave the same across different test runs or environments.
-To account for these differences, there is a process called **_normalization_**. Normalization
-allows custom regular expressions with
+To account for these differences, there is a process called **_normalization_**. Several ways to approach normalization exist:
+
+1. Fixture-based normalization
+1. Environment-variable-based normalization
+1. Regex-based normalization
+
+#### Fixture-based normalization
+
+Fixture-based normalization should be used whenever possible, because it is simpler and easier to
+understand than regex-based normalization.
+
+The [Markdown snapshot testing](#markdown-snapshot-testing) uses RSpec to generate the
+[example snapshot files](#example-snapshot-files). RSpec enables you to:
+
+- Use the same powerful fixture support and helpers as all the rest of the GitLab RSpec suite.
+- Use fixtures to control the state of the database when the example snapshots are generated.
+- Extract this fixture setup to an RSpec shared context. This shared context is used to ensure
+ the same database state exists wherever the snapshot tests are run, either by the CI suite, or
+ locally via [`run-snapshot-tests.sh`](#run-snapshot-testssh-script).
+
+You can see the RSpec shared context containing these fixtures in
+[`spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb).
+
+#### Environment-variable-based normalization
+
+In some cases, fixtures may not be usable, because they do not provide control over the varying
+values. In these cases, we can introduce support for a environment variable into the production
+code, which allows us to override the randommness in our test environment when we are
+generating the HTML for footnote examples. Even though it is in the production code path, it has
+no effect unless it is explicitly set, therefore it is innocuous. It allows us to avoid
+the more-complex regex-based normalization described below.
+
+The current example of this is when normally random footnote IDs are overridden to be deterministic
+by setting `GITLAB_TEST_FOOTNOTE_ID`. It is set along with the fixtures setup in the
+[`spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb)
+shared context.
+
+#### Regex-based normalization
+
+If neither fixture-based nor environment-variable-based normalization can be used, use regex-based
+normalization. It is powerful, but more complex, and requires more maintenance.
+It requires referring to specific examples by name, and crafting the proper regexes.
+
+Regex-based normalization allows custom regular expressions with
[_capturing groups_](https://ruby-doc.org/core-3.1.2/Regexp.html#class-Regexp-label-Capturing)
to be applied to two different versions of HTML or JSON for a given Markdown example,
and the contents of the captured groups can be replaced with the same fixed values.
@@ -813,6 +855,39 @@ to be specified for a Markdown example.
07_01_00_id: *07_01_00_id
```
+##### `glfm_example_metadata.yml`
+
+[`glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml)
+allows control over other aspects of the snapshot example generation process.
+
+- It is manually updated.
+- The `ee` fields determine whether the example is an EE-only example. If the `ee` field is `true`,
+ the example will only be run by `ee/spec/requests/api/markdown_snapshot_spec.rb`, not by
+ `spec/requests/api/markdown_snapshot_spec.rb`.
+- The `api_request_override_path` field overrides the API endpoint path which is used to
+ generate the `static` HTML for the specifed example. Different endpoints can generate different
+ HTML in some cases, so we want to be able to exercise different API endpoints for the same
+ Markdown. By default, the `/markdown` endpoint is used.
+
+`glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml` sample entries:
+
+```yaml
+---
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001:
+ api_request_override_path: /groups/glfm_group/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002:
+ api_request_override_path: /glfm_group/glfm_project/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003:
+ api_request_override_path: /glfm_group/glfm_project/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004:
+ api_request_override_path: /-/snippets/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005:
+ api_request_override_path: /glfm_group/glfm_project/-/wikis/new_page/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006:
+ ee: true
+ api_request_override_path: /groups/glfm_group/-/wikis/new_page/preview_markdown
+```
+
#### Output specification files
The `glfm_specification/output` directory contains the CommonMark standard format
diff --git a/ee/spec/requests/api/markdown_snapshot_spec.rb b/ee/spec/requests/api/markdown_snapshot_spec.rb
new file mode 100644
index 0000000000000..66d3c60d6f619
--- /dev/null
+++ b/ee/spec/requests/api/markdown_snapshot_spec.rb
@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# See https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#markdown-snapshot-testing
+# for documentation on this spec.
+RSpec.describe API::Markdown, 'Snapshot' do
+ # noinspection RailsParamDefResolve (RubyMine can't find the shared context from this file location)
+ include_context 'with API::Markdown Snapshot shared context', ee_only: true
+end
diff --git a/glfm_specification/example_snapshots/examples_index.yml b/glfm_specification/example_snapshots/examples_index.yml
index bd295baaad0bb..3d4efcfbd7a90 100644
--- a/glfm_specification/example_snapshots/examples_index.yml
+++ b/glfm_specification/example_snapshots/examples_index.yml
@@ -2054,3 +2054,21 @@
07_05_00__gitlab_specific_markdown__video__002:
spec_txt_example_position: 687
source_specification: gitlab
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001:
+ spec_txt_example_position: 688
+ source_specification: gitlab
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002:
+ spec_txt_example_position: 689
+ source_specification: gitlab
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003:
+ spec_txt_example_position: 690
+ source_specification: gitlab
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004:
+ spec_txt_example_position: 691
+ source_specification: gitlab
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005:
+ spec_txt_example_position: 692
+ source_specification: gitlab
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006:
+ spec_txt_example_position: 693
+ source_specification: gitlab
diff --git a/glfm_specification/example_snapshots/html.yml b/glfm_specification/example_snapshots/html.yml
index 196cd4f748dbc..1df9354822a9b 100644
--- a/glfm_specification/example_snapshots/html.yml
+++ b/glfm_specification/example_snapshots/html.yml
@@ -7850,3 +7850,45 @@
wysiwyg: |-
<pre>[video]: video.mov "video title"</pre>
<p><span class="media-container video-container"><video src="video.mov" controls="true" data-setup="{}" data-title="video"></video><a href="video.mov">video</a></span></p>
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001:
+ canonical: |
+ <p><a href="groups-test-file">groups-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:45" dir="auto"><a href="/groups/glfm_group/-/uploads/groups-test-file" data-canonical-src="/uploads/groups-test-file" data-link="true" class="gfm">groups-test-file</a></p>
+ wysiwyg: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002:
+ canonical: |
+ <p><a href="projects-test-file">projects-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:40" dir="auto"><a href="/glfm_group/glfm_project/-/blob/master/projects-test-file">projects-test-file</a></p>
+ wysiwyg: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003:
+ canonical: |
+ <p>This project snippet ID reference IS filtered: $88888</p>
+ static: |-
+ <p data-sourcepos="1:1-1:53" dir="auto">This project snippet ID reference IS filtered: <a href="/glfm_group/glfm_project/-/snippets/88888" data-reference-type="snippet" data-original="$88888" data-link="false" data-link-reference="false" data-project="77777" data-snippet="88888" data-container="body" data-placement="top" title="glfm_project_snippet" class="gfm gfm-snippet has-tooltip">$88888</a></p>
+ wysiwyg: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004:
+ canonical: |
+ <p>This personal snippet ID reference is not filtered: $99999</p>
+ static: |-
+ <p data-sourcepos="1:1-1:58" dir="auto">This personal snippet ID reference is not filtered: $99999</p>
+ wysiwyg: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005:
+ canonical: |
+ <p><a href="project-wikis-test-file">project-wikis-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:50" dir="auto"><a href="/glfm_group/glfm_project/-/wikis/project-wikis-test-file" data-canonical-src="project-wikis-test-file">project-wikis-test-file</a></p>
+ wysiwyg: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006:
+ canonical: |
+ <p><a href="group-wikis-test-file">group-wikis-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:46" dir="auto"><a href="/groups/glfm_group/-/wikis/group-wikis-test-file" data-canonical-src="group-wikis-test-file">group-wikis-test-file</a></p>
+ wysiwyg: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
diff --git a/glfm_specification/example_snapshots/markdown.yml b/glfm_specification/example_snapshots/markdown.yml
index c2b2caacb5bdb..e928c5a977e07 100644
--- a/glfm_specification/example_snapshots/markdown.yml
+++ b/glfm_specification/example_snapshots/markdown.yml
@@ -2239,3 +2239,15 @@
[video]: video.mov "video title"
![video][video]
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001: |
+ [groups-test-file](/uploads/groups-test-file)
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002: |
+ [projects-test-file](projects-test-file)
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003: |
+ This project snippet ID reference IS filtered: $88888
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004: |
+ This personal snippet ID reference is not filtered: $99999
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005: |
+ [project-wikis-test-file](project-wikis-test-file)
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006: |
+ [group-wikis-test-file](group-wikis-test-file)
diff --git a/glfm_specification/example_snapshots/prosemirror_json.yml b/glfm_specification/example_snapshots/prosemirror_json.yml
index 02330019a8d8a..7928d50ae961c 100644
--- a/glfm_specification/example_snapshots/prosemirror_json.yml
+++ b/glfm_specification/example_snapshots/prosemirror_json.yml
@@ -20890,3 +20890,15 @@
}
]
}
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006: |-
+ Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
diff --git a/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt b/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt
index fd540a905bd67..d27f809aaf350 100644
--- a/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt
+++ b/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt
@@ -250,3 +250,64 @@ Reference definitions work video as well:
.
<p><video src="video.mov" title="video title"></video></p>
````````````````````````````````
+
+# Examples Using Internal Extensions
+
+## Markdown Preview API Request Overrides
+
+This section contains examples of all controllers which use `PreviewMarkdown` module
+and use different `markdown_context_params`. They exercise the various `preview_markdown`
+endpoints via `glfm_example_metadata.yml`.
+
+
+`preview_markdown` exercising `groups` API endpoint and `UploadLinkFilter`:
+
+```````````````````````````````` example gitlab
+[groups-test-file](/uploads/groups-test-file)
+.
+<p><a href="groups-test-file">groups-test-file</a></p>
+````````````````````````````````
+
+`preview_markdown` exercising `projects` API endpoint and `RepositoryLinkFilter`:
+
+```````````````````````````````` example gitlab
+[projects-test-file](projects-test-file)
+.
+<p><a href="projects-test-file">projects-test-file</a></p>
+````````````````````````````````
+
+`preview_markdown` exercising `projects` API endpoint and `SnippetReferenceFilter`:
+
+```````````````````````````````` example gitlab
+This project snippet ID reference IS filtered: $88888
+.
+<p>This project snippet ID reference IS filtered: $88888</p>
+````````````````````````````````
+
+`preview_markdown` exercising personal (non-project) `snippets` API endpoint. This is
+only used by the comment field on personal snippets. It has no unique custom markdown
+extension behavior, and specifically does not render snippet references via
+`SnippetReferenceFilter`, even if the ID is valid.
+
+```````````````````````````````` example gitlab
+This personal snippet ID reference is not filtered: $99999
+.
+<p>This personal snippet ID reference is not filtered: $99999</p>
+````````````````````````````````
+
+`preview_markdown` exercising project `wikis` API endpoint and `WikiLinkFilter`:
+
+```````````````````````````````` example gitlab
+[project-wikis-test-file](project-wikis-test-file)
+.
+<p><a href="project-wikis-test-file">project-wikis-test-file</a></p>
+````````````````````````````````
+
+`preview_markdown` exercising group `wikis` API endpoint and `WikiLinkFilter`. This example
+also requires an EE license enabling the `group_wikis` feature:
+
+```````````````````````````````` example gitlab
+[group-wikis-test-file](group-wikis-test-file)
+.
+<p><a href="group-wikis-test-file">group-wikis-test-file</a></p>
+````````````````````````````````
diff --git a/glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml b/glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml
new file mode 100644
index 0000000000000..3c043f5fba117
--- /dev/null
+++ b/glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml
@@ -0,0 +1,14 @@
+---
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001:
+ api_request_override_path: /groups/glfm_group/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002:
+ api_request_override_path: /glfm_group/glfm_project/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003:
+ api_request_override_path: /glfm_group/glfm_project/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004:
+ api_request_override_path: /-/snippets/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005:
+ api_request_override_path: /glfm_group/glfm_project/-/wikis/new_page/preview_markdown
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006:
+ ee: true
+ api_request_override_path: /groups/glfm_group/-/wikis/new_page/preview_markdown
diff --git a/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml b/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml
index 512f197047f8f..a74c3492324e9 100644
--- a/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml
+++ b/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml
@@ -24,3 +24,39 @@
skip_running_conformance_wysiwyg_tests: Inapplicable task list items not yet implemented for WYSYWIG
skip_running_snapshot_wysiwyg_html_tests: Inapplicable task list items not yet implemented for WYSYWIG
skip_running_snapshot_prosemirror_json_tests: Inapplicable task list items not yet implemented for WYSYWIG
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001:
+ skip_update_example_snapshot_html_wysiwyg: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_update_example_snapshot_prosemirror_json: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_conformance_wysiwyg_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_wysiwyg_html_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_prosemirror_json_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002:
+ skip_update_example_snapshot_html_wysiwyg: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_update_example_snapshot_prosemirror_json: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_conformance_wysiwyg_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_wysiwyg_html_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_prosemirror_json_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003:
+ skip_update_example_snapshot_html_wysiwyg: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_update_example_snapshot_prosemirror_json: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_conformance_wysiwyg_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_wysiwyg_html_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_prosemirror_json_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004:
+ skip_update_example_snapshot_html_wysiwyg: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_update_example_snapshot_prosemirror_json: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_conformance_wysiwyg_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_wysiwyg_html_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_prosemirror_json_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005:
+ skip_update_example_snapshot_html_wysiwyg: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_update_example_snapshot_prosemirror_json: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_conformance_wysiwyg_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_wysiwyg_html_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_prosemirror_json_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006:
+ skip_update_example_snapshot_html_wysiwyg: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_update_example_snapshot_prosemirror_json: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_conformance_wysiwyg_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_wysiwyg_html_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
+ skip_running_snapshot_prosemirror_json_tests: Not yet implemented. See https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92507#note_1068159236
diff --git a/glfm_specification/output/spec.txt b/glfm_specification/output/spec.txt
index 2939e0d2fbde5..d79a8d6b6758a 100644
--- a/glfm_specification/output/spec.txt
+++ b/glfm_specification/output/spec.txt
@@ -9853,6 +9853,67 @@ Reference definitions work video as well:
<p><video src="video.mov" title="video title"></video></p>
````````````````````````````````
+# Examples Using Internal Extensions
+
+## Markdown Preview API Request Overrides
+
+This section contains examples of all controllers which use `PreviewMarkdown` module
+and use different `markdown_context_params`. They exercise the various `preview_markdown`
+endpoints via `glfm_example_metadata.yml`.
+
+
+`preview_markdown` exercising `groups` API endpoint and `UploadLinkFilter`:
+
+```````````````````````````````` example gitlab
+[groups-test-file](/uploads/groups-test-file)
+.
+<p><a href="groups-test-file">groups-test-file</a></p>
+````````````````````````````````
+
+`preview_markdown` exercising `projects` API endpoint and `RepositoryLinkFilter`:
+
+```````````````````````````````` example gitlab
+[projects-test-file](projects-test-file)
+.
+<p><a href="projects-test-file">projects-test-file</a></p>
+````````````````````````````````
+
+`preview_markdown` exercising `projects` API endpoint and `SnippetReferenceFilter`:
+
+```````````````````````````````` example gitlab
+This project snippet ID reference IS filtered: $88888
+.
+<p>This project snippet ID reference IS filtered: $88888</p>
+````````````````````````````````
+
+`preview_markdown` exercising personal (non-project) `snippets` API endpoint. This is
+only used by the comment field on personal snippets. It has no unique custom markdown
+extension behavior, and specifically does not render snippet references via
+`SnippetReferenceFilter`, even if the ID is valid.
+
+```````````````````````````````` example gitlab
+This personal snippet ID reference is not filtered: $99999
+.
+<p>This personal snippet ID reference is not filtered: $99999</p>
+````````````````````````````````
+
+`preview_markdown` exercising project `wikis` API endpoint and `WikiLinkFilter`:
+
+```````````````````````````````` example gitlab
+[project-wikis-test-file](project-wikis-test-file)
+.
+<p><a href="project-wikis-test-file">project-wikis-test-file</a></p>
+````````````````````````````````
+
+`preview_markdown` exercising group `wikis` API endpoint and `WikiLinkFilter`. This example
+also requires an EE license enabling the `group_wikis` feature:
+
+```````````````````````````````` example gitlab
+[group-wikis-test-file](group-wikis-test-file)
+.
+<p><a href="group-wikis-test-file">group-wikis-test-file</a></p>
+````````````````````````````````
+
<!-- END TESTS -->
# Appendix: A parsing strategy
diff --git a/scripts/glfm/run-snapshot-tests.sh b/scripts/glfm/run-snapshot-tests.sh
index 59a7c8f06b079..6a66d8fbd9a6a 100755
--- a/scripts/glfm/run-snapshot-tests.sh
+++ b/scripts/glfm/run-snapshot-tests.sh
@@ -28,8 +28,12 @@ printf "\n${BBlue}Running frontend 'yarn jest spec/frontend/content_editor/markd
yarn jest spec/frontend/content_editor/markdown_snapshot_spec.js
printf "\n${BBlue}'yarn jest spec/frontend/content_editor/markdown_snapshot_spec.js' passed!${Color_Off}\n\n"
-printf "\n${BBlue}Running backend 'bundle exec rspec spec/requests/api/markdown_snapshot_spec.rb'...${Color_Off}\n\n"
+printf "\n${BBlue}Running CE backend 'bundle exec rspec spec/requests/api/markdown_snapshot_spec.rb'...${Color_Off}\n\n"
bundle exec rspec spec/requests/api/markdown_snapshot_spec.rb
printf "\n${BBlue}'bundle exec rspec spec/requests/api/markdown_snapshot_spec.rb' passed!${Color_Off}\n\n"
+printf "\n${BBlue}Running EE backend 'bundle exec rspec ee/spec/requests/api/markdown_snapshot_spec.rb'...${Color_Off}\n\n"
+bundle exec rspec ee/spec/requests/api/markdown_snapshot_spec.rb
+printf "\n${BBlue}'bundle exec rspec ee/spec/requests/api/markdown_snapshot_spec.rb' passed!${Color_Off}\n\n"
+
printf "\n✅✅✅ ${BGreen}All GLFM snapshot example tests passed successfully!${Color_Off} ✅✅✅\n"
diff --git a/scripts/lib/glfm/constants.rb b/scripts/lib/glfm/constants.rb
index 42977248c0d7c..e5790bbdd8831 100644
--- a/scripts/lib/glfm/constants.rb
+++ b/scripts/lib/glfm/constants.rb
@@ -18,6 +18,9 @@ module Constants
GLFM_INTRO_TXT_PATH = specification_input_glfm_path.join('glfm_intro.txt')
GLFM_EXAMPLES_TXT_PATH = specification_input_glfm_path.join('glfm_canonical_examples.txt')
GLFM_EXAMPLE_STATUS_YML_PATH = specification_input_glfm_path.join('glfm_example_status.yml')
+ GLFM_EXAMPLE_METADATA_YML_PATH =
+ specification_input_glfm_path.join('glfm_example_metadata.yml')
+ GLFM_EXAMPLE_NORMALIZATIONS_YML_PATH = specification_input_glfm_path.join('glfm_example_normalizations.yml')
GLFM_SPEC_TXT_PATH = specification_path.join('output/spec.txt')
# Example Snapshot (ES) files
@@ -28,15 +31,16 @@ module Constants
ES_PROSEMIRROR_JSON_YML_PATH = File.join(es_fixtures_path, 'prosemirror_json.yml')
# Other constants used for processing files
- GLFM_SPEC_TXT_HEADER = <<~GLFM_SPEC_TXT_HEADER
+ GLFM_SPEC_TXT_HEADER = <<~MARKDOWN
---
title: GitLab Flavored Markdown (GLFM) Spec
version: alpha
...
- GLFM_SPEC_TXT_HEADER
+ MARKDOWN
INTRODUCTION_HEADER_LINE_TEXT = /\A# Introduction\Z/.freeze
END_TESTS_COMMENT_LINE_TEXT = /\A<!-- END TESTS -->\Z/.freeze
MARKDOWN_TEMPFILE_BASENAME = %w[MARKDOWN_TEMPFILE_ .yml].freeze
+ METADATA_TEMPFILE_BASENAME = %w[METADATA_TEMPFILE_ .yml].freeze
STATIC_HTML_TEMPFILE_BASENAME = %w[STATIC_HTML_TEMPFILE_ .yml].freeze
WYSIWYG_HTML_AND_JSON_TEMPFILE_BASENAME = %w[WYSIWYG_HTML_AND_JSON_TEMPFILE_ .yml].freeze
end
diff --git a/scripts/lib/glfm/render_static_html.rb b/scripts/lib/glfm/render_static_html.rb
index 25abc75e2709c..8d72aec7c3b88 100644
--- a/scripts/lib/glfm/render_static_html.rb
+++ b/scripts/lib/glfm/render_static_html.rb
@@ -29,34 +29,19 @@
include Glfm::Constants
include Glfm::Shared
- # TODO: Remove duplication of fixtures & logic with spec/support/shared_contexts/markdown_snapshot_shared_examples.rb
-
- let_it_be(:user) { create(:user) }
- let_it_be(:group) { create(:group, name: 'glfm_group').tap { |group| group.add_owner(user) } }
-
- let_it_be(:project) do
- # NOTE: We hardcode the IDs on all fixtures to prevent variability in the
- # rendered HTML/Prosemirror JSON, and to minimize the need for normalization:
- # https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#normalization
- create(:project, :repository, creator: user, group: group, name: 'glfm_project', id: 77777)
- end
-
- let_it_be(:project_snippet) { create(:project_snippet, id: 88888, project: project) }
- let_it_be(:personal_snippet) { create(:snippet, id: 99999) }
-
- before do
- stub_licensed_features(group_wikis: true)
- sign_in(user)
- end
+ # noinspection RailsParamDefResolve (RubyMine can't find the shared context from this file location)
+ include_context 'with GLFM example snapshot fixtures'
it 'can create a project dependency graph using factories' do
markdown_hash = YAML.safe_load(File.open(ENV.fetch('INPUT_MARKDOWN_YML_PATH')), symbolize_names: true)
+ metadata_hash = YAML.safe_load(File.open(ENV.fetch('INPUT_METADATA_YML_PATH')), symbolize_names: true)
# NOTE: We cannot parallelize this loop like the Javascript WYSIWYG example generation does,
# because the rspec `post` API cannot be parallized (it is not thread-safe, it can't find
# the controller).
- static_html_hash = markdown_hash.transform_values do |markdown|
- api_url = api "/markdown"
+ static_html_hash = markdown_hash.transform_values.with_index do |markdown, index|
+ name = markdown_hash.keys[index]
+ api_url = metadata_hash.dig(name, :api_request_override_path) || (api "/markdown")
post api_url, params: { text: markdown, gfm: true }
# noinspection RubyResolve
diff --git a/scripts/lib/glfm/update_example_snapshots.rb b/scripts/lib/glfm/update_example_snapshots.rb
index 6ff063c169087..7dc0d0f7c4bc2 100644
--- a/scripts/lib/glfm/update_example_snapshots.rb
+++ b/scripts/lib/glfm/update_example_snapshots.rb
@@ -29,8 +29,6 @@ class UpdateExampleSnapshots
def process(skip_static_and_wysiwyg: false)
output('Updating example snapshots...')
- setup_environment
-
output('(Skipping static HTML generation)') if skip_static_and_wysiwyg
output("Reading #{GLFM_SPEC_TXT_PATH}...")
@@ -49,14 +47,6 @@ def process(skip_static_and_wysiwyg: false)
private
- def setup_environment
- # Set 'GITLAB_TEST_FOOTNOTE_ID' in order to override random number generation in
- # Banzai::Filter::FootnoteFilter#random_number, and thus avoid the need to
- # perform normalization on the value. See:
- # https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#normalization
- ENV['GITLAB_TEST_FOOTNOTE_ID'] = '42'
- end
-
def add_example_names(all_examples)
# NOTE: This method and the parse_examples method assume:
# 1. Section 2 is the first section which contains examples
@@ -137,11 +127,11 @@ def write_snapshot_example_files(all_examples, skip_static_and_wysiwyg:)
return
end
- # NOTE: We pass the INPUT_MARKDOWN_YML_PATH via
- # environment variable to the static/wysiwyg HTML generation scripts. This is because it
- # is implemented as a subprocess which invokes rspec/jest scripts, and rspec/jest do not make
+ # NOTE: We pass the INPUT_MARKDOWN_YML_PATH and INPUT_METADATA_YML_PATH via
+ # environment variables to the static/wysiwyg HTML generation scripts. This is because they
+ # are implemented as subprocesses which invoke rspec/jest scripts, and rspec/jest do not make
# it straightforward to pass arguments via the command line.
- ENV['INPUT_MARKDOWN_YML_PATH'] = copy_tempfiles_for_subprocesses
+ ENV['INPUT_MARKDOWN_YML_PATH'], ENV['INPUT_METADATA_YML_PATH'] = copy_tempfiles_for_subprocesses
static_html_hash = generate_static_html
wysiwyg_html_and_json_hash = generate_wysiwyg_html_and_json
@@ -168,18 +158,31 @@ def write_examples_index_yml(all_examples)
name = example.fetch(:name).to_sym
hash[name] = {
'spec_txt_example_position' => example.fetch(:example),
- 'source_specification' =>
- if example[:extensions].empty?
- 'commonmark'
- elsif example[:extensions].include?('gitlab')
- 'gitlab'
- else
- 'github'
- end
+ 'source_specification' => source_specification_for_extensions(example.fetch(:extensions))
}
end
end
+ def source_specification_for_extensions(extensions)
+ unprocessed_extensions = extensions.map(&:to_sym)
+ unprocessed_extensions.delete(:disabled)
+
+ source_specification =
+ if unprocessed_extensions.empty?
+ 'commonmark'
+ elsif unprocessed_extensions.include?(:gitlab)
+ unprocessed_extensions.delete(:gitlab)
+ 'gitlab'
+ else
+ 'github'
+ end
+
+ # We should only be left with at most one extension, which is an optional name for the example
+ raise "Error: Invalid extension(s) found: #{unprocessed_extensions.join(', ')}" if unprocessed_extensions.size > 1
+
+ source_specification
+ end
+
def write_markdown_yml(all_examples)
generate_and_write_for_all_examples(all_examples, ES_MARKDOWN_YML_PATH) do |example, hash|
name = example.fetch(:name).to_sym
@@ -193,14 +196,17 @@ def copy_tempfiles_for_subprocesses
# the scripts to read them, because the scripts are run in
# separate subprocesses, and during unit testing we are unable to substitute the mock
# StringIO when reading the input files in the subprocess.
- { ES_MARKDOWN_YML_PATH => MARKDOWN_TEMPFILE_BASENAME }.map do |original_file_path, tempfile_basename|
+ {
+ ES_MARKDOWN_YML_PATH => MARKDOWN_TEMPFILE_BASENAME,
+ GLFM_EXAMPLE_METADATA_YML_PATH => METADATA_TEMPFILE_BASENAME
+ }.map do |original_file_path, tempfile_basename|
Dir::Tmpname.create(tempfile_basename) do |path|
io = File.open(original_file_path)
io.seek(0) # rewind the file. This is necessary when testing with a mock StringIO
contents = io.read
write_file(path, contents)
end
- end.first
+ end
end
def generate_static_html
diff --git a/spec/requests/api/markdown_snapshot_spec.rb b/spec/requests/api/markdown_snapshot_spec.rb
index 1270efdfd6fd3..f2019172a54fe 100644
--- a/spec/requests/api/markdown_snapshot_spec.rb
+++ b/spec/requests/api/markdown_snapshot_spec.rb
@@ -5,7 +5,5 @@
# See https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#markdown-snapshot-testing
# for documentation on this spec.
RSpec.describe API::Markdown, 'Snapshot' do
- # noinspection RubyMismatchedArgumentType (ignore RBS type warning: __dir__ can be nil, but 2nd argument can't be nil)
- glfm_specification_dir = File.expand_path('../../../glfm_specification', __dir__)
- include_context 'with API::Markdown Snapshot shared context', glfm_specification_dir
+ include_context 'with API::Markdown Snapshot shared context'
end
diff --git a/spec/scripts/lib/glfm/parse_examples_spec.rb b/spec/scripts/lib/glfm/parse_examples_spec.rb
index 6fe1149a3789d..a1ee6b3f440eb 100644
--- a/spec/scripts/lib/glfm/parse_examples_spec.rb
+++ b/spec/scripts/lib/glfm/parse_examples_spec.rb
@@ -9,7 +9,7 @@
end
let(:spec_txt_contents) do
- <<~SPEC_TXT_CONTENTS
+ <<~MARKDOWN
---
title: Spec
...
@@ -134,7 +134,7 @@
# Appendix
Appendix text.
- SPEC_TXT_CONTENTS
+ MARKDOWN
end
let(:spec_txt_lines) { spec_txt_contents.split("\n") }
@@ -311,7 +311,7 @@
describe "with incorrect header nesting" do
let(:spec_txt_contents) do
- <<~SPEC_TXT_CONTENTS
+ <<~MARKDOWN
---
title: Spec
...
@@ -320,7 +320,7 @@
### H3
- SPEC_TXT_CONTENTS
+ MARKDOWN
end
it "raises if H3 is nested directly in H1" do
diff --git a/spec/scripts/lib/glfm/update_example_snapshots_spec.rb b/spec/scripts/lib/glfm/update_example_snapshots_spec.rb
index 34af35a66f558..f96936c0a6f2c 100644
--- a/spec/scripts/lib/glfm/update_example_snapshots_spec.rb
+++ b/spec/scripts/lib/glfm/update_example_snapshots_spec.rb
@@ -35,6 +35,8 @@
let(:glfm_spec_txt_local_io) { StringIO.new(glfm_spec_txt_contents) }
let(:glfm_example_status_yml_path) { described_class::GLFM_EXAMPLE_STATUS_YML_PATH }
let(:glfm_example_status_yml_io) { StringIO.new(glfm_example_status_yml_contents) }
+ let(:glfm_example_metadata_yml_path) { described_class::GLFM_EXAMPLE_METADATA_YML_PATH }
+ let(:glfm_example_metadata_yml_io) { StringIO.new(glfm_example_metadata_yml_contents) }
# Example Snapshot (ES) output files
let(:es_examples_index_yml_path) { described_class::ES_EXAMPLES_INDEX_YML_PATH }
@@ -52,7 +54,7 @@
let(:static_html_tempfile_path) { Tempfile.new.path }
let(:glfm_spec_txt_contents) do
- <<~GLFM_SPEC_TXT_CONTENTS
+ <<~MARKDOWN
---
title: GitLab Flavored Markdown Spec
...
@@ -183,17 +185,75 @@
<p><strong>This example will have its manually modified static HTML, WYSIWYG HTML, and ProseMirror JSON preserved</strong></p>
````````````````````````````````
+ # API Request Overrides
+
+ This section contains examples which verify that all of the fixture models which are set up
+ in `render_static_html.rb` are correctly configured. They exercise various `preview_markdown`
+ endpoints via `glfm_example_metadata.yml`.
+
+ ## Group Upload Link
+
+ `preview_markdown` exercising `groups` API endpoint and `UploadLinkFilter`:
+
+ ```````````````````````````````` example gitlab
+ [groups-test-file](/uploads/groups-test-file)
+ .
+ <p><a href="groups-test-file">groups-test-file</a></p>
+ ````````````````````````````````
+
+ ## Project Repo Link
+
+ `preview_markdown` exercising `projects` API endpoint and `RepositoryLinkFilter`:
+
+ ```````````````````````````````` example gitlab
+ [projects-test-file](projects-test-file)
+ .
+ <p><a href="projects-test-file">projects-test-file</a></p>
+ ````````````````````````````````
+
+ ## Project Snippet Ref
+
+ `preview_markdown` exercising `projects` API endpoint and `SnippetReferenceFilter`:
+
+ ```````````````````````````````` example gitlab
+ This project snippet ID reference IS filtered: $88888
+ .
+ <p>This project snippet ID reference IS filtered: <a href="/glfm_group/glfm_project/-/snippets/88888">$88888</a>
+ ````````````````````````````````
+
+ ## Personal Snippet Ref
+
+ `preview_markdown` exercising personal (non-project) `snippets` API endpoint. This is
+ only used by the comment field on personal snippets. It has no unique custom markdown
+ extension behavior, and specifically does not render snippet references via
+ `SnippetReferenceFilter`, even if the ID is valid.
+
+ ```````````````````````````````` example gitlab
+ This personal snippet ID reference is NOT filtered: $99999
+ .
+ <p>This personal snippet ID reference is NOT filtered: $99999</p>
+ ````````````````````````````````
+
+ ## Project Wiki Link
+
+ `preview_markdown` exercising project `wikis` API endpoint and `WikiLinkFilter`:
+
+ ```````````````````````````````` example gitlab
+ [project-wikis-test-file](project-wikis-test-file)
+ .
+ <p><a href="project-wikis-test-file">project-wikis-test-file</a></p>
+ ````````````````````````````````
+
<!-- END TESTS -->
# Appendix
Appendix text.
- GLFM_SPEC_TXT_CONTENTS
+ MARKDOWN
end
let(:glfm_example_status_yml_contents) do
- # language=YAML
- <<~GLFM_EXAMPLE_STATUS_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__001:
# The skip_update_example_snapshots key is present, but false, so this example is not skipped
@@ -206,12 +266,27 @@
05_02_00__third_gitlab_specific_section_with_skipped_examples__strong_but_manually_modified_and_skipped__001:
# Always skip this example, but preserve the existing manual modifications
skip_update_example_snapshots: 'skipping this example because we have manually modified it'
- GLFM_EXAMPLE_STATUS_YML_CONTENTS
+ YAML
+ end
+
+ let(:glfm_example_metadata_yml_contents) do
+ <<~YAML
+ ---
+ 06_01_00__api_request_overrides__group_upload_link__001:
+ api_request_override_path: /groups/glfm_group/preview_markdown
+ 06_02_00__api_request_overrides__project_repo_link__001:
+ api_request_override_path: /glfm_group/glfm_project/preview_markdown
+ 06_03_00__api_request_overrides__project_snippet_ref__001:
+ api_request_override_path: /glfm_group/glfm_project/preview_markdown
+ 06_04_00__api_request_overrides__personal_snippet_ref__001:
+ api_request_override_path: /-/snippets/preview_markdown
+ 06_05_00__api_request_overrides__project_wiki_link__001:
+ api_request_override_path: /glfm_group/glfm_project/-/wikis/new_page/preview_markdown
+ YAML
end
let(:es_html_yml_io_existing_contents) do
- # language=YAML
- <<~ES_HTML_YML_IO_EXISTING_CONTENTS
+ <<~YAML
---
00_00_00__obsolete_entry_to_be_deleted__001:
canonical: |
@@ -234,12 +309,11 @@
<p>This is the manually modified static HTML which will be preserved</p>
wysiwyg: |-
<p>This is the manually modified WYSIWYG HTML which will be preserved</p>
- ES_HTML_YML_IO_EXISTING_CONTENTS
+ YAML
end
let(:es_prosemirror_json_yml_io_existing_contents) do
- # language=YAML
- <<~ES_PROSEMIRROR_JSON_YML_IO_EXISTING_CONTENTS
+ <<~YAML
---
00_00_00__obsolete_entry_to_be_deleted__001: |-
{
@@ -272,7 +346,7 @@
{
"existing": "This entry is manually modified and preserved because skip_update_example_snapshots will be truthy"
}
- ES_PROSEMIRROR_JSON_YML_IO_EXISTING_CONTENTS
+ YAML
end
before do
@@ -283,6 +357,9 @@
# input files
allow(File).to receive(:open).with(glfm_spec_txt_path) { glfm_spec_txt_local_io }
allow(File).to receive(:open).with(glfm_example_status_yml_path) { glfm_example_status_yml_io }
+ allow(File).to receive(:open).with(glfm_example_metadata_yml_path) do
+ glfm_example_metadata_yml_io
+ end
# output files
allow(File).to receive(:open).with(es_examples_index_yml_path, 'w') { es_examples_index_yml_io }
@@ -298,6 +375,7 @@
# Allow normal opening of Tempfile files created during script execution.
tempfile_basenames = [
described_class::MARKDOWN_TEMPFILE_BASENAME[0],
+ described_class::METADATA_TEMPFILE_BASENAME[0],
described_class::STATIC_HTML_TEMPFILE_BASENAME[0],
described_class::WYSIWYG_HTML_AND_JSON_TEMPFILE_BASENAME[0]
].join('|')
@@ -333,13 +411,12 @@
describe 'when any other skip_update_example_snapshot_* is also truthy' do
let(:glfm_example_status_yml_contents) do
- # language=YAML
- <<~GLFM_EXAMPLE_STATUS_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__001:
skip_update_example_snapshots: 'if the skip_update_example_snapshots key is truthy...'
skip_update_example_snapshot_html_static: '...then no other skip_update_example_* keys can be truthy'
- GLFM_EXAMPLE_STATUS_YML_CONTENTS
+ YAML
end
it 'raises an error' do
@@ -354,8 +431,7 @@
describe 'writing examples_index.yml' do
let(:es_examples_index_yml_contents) { reread_io(es_examples_index_yml_io) }
let(:expected_examples_index_yml_contents) do
- # language=YAML
- <<~ES_EXAMPLES_INDEX_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__001:
spec_txt_example_position: 1
@@ -381,7 +457,22 @@
05_02_00__third_gitlab_specific_section_with_skipped_examples__strong_but_manually_modified_and_skipped__001:
spec_txt_example_position: 9
source_specification: gitlab
- ES_EXAMPLES_INDEX_YML_CONTENTS
+ 06_01_00__api_request_overrides__group_upload_link__001:
+ spec_txt_example_position: 10
+ source_specification: gitlab
+ 06_02_00__api_request_overrides__project_repo_link__001:
+ spec_txt_example_position: 11
+ source_specification: gitlab
+ 06_03_00__api_request_overrides__project_snippet_ref__001:
+ spec_txt_example_position: 12
+ source_specification: gitlab
+ 06_04_00__api_request_overrides__personal_snippet_ref__001:
+ spec_txt_example_position: 13
+ source_specification: gitlab
+ 06_05_00__api_request_overrides__project_wiki_link__001:
+ spec_txt_example_position: 14
+ source_specification: gitlab
+ YAML
end
it 'writes the correct content' do
@@ -394,8 +485,7 @@
describe 'writing markdown.yml' do
let(:es_markdown_yml_contents) { reread_io(es_markdown_yml_io) }
let(:expected_markdown_yml_contents) do
- # language=YAML
- <<~ES_MARKDOWN_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__001: |
__bold__
@@ -415,7 +505,17 @@
**this example will be skipped**
05_02_00__third_gitlab_specific_section_with_skipped_examples__strong_but_manually_modified_and_skipped__001: |
**This example will have its manually modified static HTML, WYSIWYG HTML, and ProseMirror JSON preserved**
- ES_MARKDOWN_YML_CONTENTS
+ 06_01_00__api_request_overrides__group_upload_link__001: |
+ [groups-test-file](/uploads/groups-test-file)
+ 06_02_00__api_request_overrides__project_repo_link__001: |
+ [projects-test-file](projects-test-file)
+ 06_03_00__api_request_overrides__project_snippet_ref__001: |
+ This project snippet ID reference IS filtered: $88888
+ 06_04_00__api_request_overrides__personal_snippet_ref__001: |
+ This personal snippet ID reference is NOT filtered: $99999
+ 06_05_00__api_request_overrides__project_wiki_link__001: |
+ [project-wikis-test-file](project-wikis-test-file)
+ YAML
end
it 'writes the correct content' do
@@ -425,6 +525,7 @@
end
end
+ # rubocop:disable RSpec/MultipleMemoizedHelpers
describe 'writing html.yml and prosemirror_json.yml' do
let(:es_html_yml_contents) { reread_io(es_html_yml_io) }
let(:es_prosemirror_json_yml_contents) { reread_io(es_prosemirror_json_yml_io) }
@@ -432,8 +533,7 @@
# NOTE: This example_status.yml is crafted in conjunction with expected_html_yml_contents
# to test the behavior of the `skip_update_*` flags
let(:glfm_example_status_yml_contents) do
- # language=YAML
- <<~GLFM_EXAMPLE_STATUS_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__002:
# NOTE: 02_01_00__inlines__strong__002: is omitted from the existing prosemirror_json.yml file, and is also
@@ -451,12 +551,11 @@
skip_update_example_snapshots: 'skipping this example because it is very bad'
05_02_00__third_gitlab_specific_section_with_skipped_examples__strong_but_manually_modified_and_skipped__001:
skip_update_example_snapshots: 'skipping this example because we have manually modified it'
- GLFM_EXAMPLE_STATUS_YML_CONTENTS
+ YAML
end
let(:expected_html_yml_contents) do
- # language=YAML
- <<~ES_HTML_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__001:
canonical: |
@@ -507,12 +606,46 @@
<p>This is the manually modified static HTML which will be preserved</p>
wysiwyg: |-
<p>This is the manually modified WYSIWYG HTML which will be preserved</p>
- ES_HTML_YML_CONTENTS
+ 06_01_00__api_request_overrides__group_upload_link__001:
+ canonical: |
+ <p><a href="groups-test-file">groups-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:45" dir="auto"><a href="/groups/glfm_group/-/uploads/groups-test-file" data-canonical-src="/uploads/groups-test-file" data-link="true" class="gfm">groups-test-file</a></p>
+ wysiwyg: |-
+ <p><a target="_blank" rel="noopener noreferrer nofollow" href="/uploads/groups-test-file">groups-test-file</a></p>
+ 06_02_00__api_request_overrides__project_repo_link__001:
+ canonical: |
+ <p><a href="projects-test-file">projects-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:40" dir="auto"><a href="/glfm_group/glfm_project/-/blob/master/projects-test-file">projects-test-file</a></p>
+ wysiwyg: |-
+ <p><a target="_blank" rel="noopener noreferrer nofollow" href="projects-test-file">projects-test-file</a></p>
+ 06_03_00__api_request_overrides__project_snippet_ref__001:
+ canonical: |
+ <p>This project snippet ID reference IS filtered: <a href="/glfm_group/glfm_project/-/snippets/88888">$88888</a>
+ static: |-
+ <p data-sourcepos="1:1-1:53" dir="auto">This project snippet ID reference IS filtered: <a href="/glfm_group/glfm_project/-/snippets/88888" data-reference-type="snippet" data-original="$88888" data-link="false" data-link-reference="false" data-project="77777" data-snippet="88888" data-container="body" data-placement="top" title="glfm_project_snippet" class="gfm gfm-snippet has-tooltip">$88888</a></p>
+ wysiwyg: |-
+ <p>This project snippet ID reference IS filtered: $88888</p>
+ 06_04_00__api_request_overrides__personal_snippet_ref__001:
+ canonical: |
+ <p>This personal snippet ID reference is NOT filtered: $99999</p>
+ static: |-
+ <p data-sourcepos="1:1-1:58" dir="auto">This personal snippet ID reference is NOT filtered: $99999</p>
+ wysiwyg: |-
+ <p>This personal snippet ID reference is NOT filtered: $99999</p>
+ 06_05_00__api_request_overrides__project_wiki_link__001:
+ canonical: |
+ <p><a href="project-wikis-test-file">project-wikis-test-file</a></p>
+ static: |-
+ <p data-sourcepos="1:1-1:50" dir="auto"><a href="/glfm_group/glfm_project/-/wikis/project-wikis-test-file" data-canonical-src="project-wikis-test-file">project-wikis-test-file</a></p>
+ wysiwyg: |-
+ <p><a target="_blank" rel="noopener noreferrer nofollow" href="project-wikis-test-file">project-wikis-test-file</a></p>
+ YAML
end
let(:expected_prosemirror_json_contents) do
- # language=YAML
- <<~ES_PROSEMIRROR_JSON_YML_CONTENTS
+ <<~YAML
---
02_01_00__inlines__strong__001: |-
{
@@ -601,7 +734,121 @@
{
"existing": "This entry is manually modified and preserved because skip_update_example_snapshots will be truthy"
}
- ES_PROSEMIRROR_JSON_YML_CONTENTS
+ 06_01_00__api_request_overrides__group_upload_link__001: |-
+ {
+ "type": "doc",
+ "content": [
+ {
+ "type": "paragraph",
+ "content": [
+ {
+ "type": "text",
+ "marks": [
+ {
+ "type": "link",
+ "attrs": {
+ "href": "/uploads/groups-test-file",
+ "target": "_blank",
+ "class": null,
+ "title": null,
+ "canonicalSrc": "/uploads/groups-test-file",
+ "isReference": false
+ }
+ }
+ ],
+ "text": "groups-test-file"
+ }
+ ]
+ }
+ ]
+ }
+ 06_02_00__api_request_overrides__project_repo_link__001: |-
+ {
+ "type": "doc",
+ "content": [
+ {
+ "type": "paragraph",
+ "content": [
+ {
+ "type": "text",
+ "marks": [
+ {
+ "type": "link",
+ "attrs": {
+ "href": "projects-test-file",
+ "target": "_blank",
+ "class": null,
+ "title": null,
+ "canonicalSrc": "projects-test-file",
+ "isReference": false
+ }
+ }
+ ],
+ "text": "projects-test-file"
+ }
+ ]
+ }
+ ]
+ }
+ 06_03_00__api_request_overrides__project_snippet_ref__001: |-
+ {
+ "type": "doc",
+ "content": [
+ {
+ "type": "paragraph",
+ "content": [
+ {
+ "type": "text",
+ "text": "This project snippet ID reference IS filtered: $88888"
+ }
+ ]
+ }
+ ]
+ }
+ 06_04_00__api_request_overrides__personal_snippet_ref__001: |-
+ {
+ "type": "doc",
+ "content": [
+ {
+ "type": "paragraph",
+ "content": [
+ {
+ "type": "text",
+ "text": "This personal snippet ID reference is NOT filtered: $99999"
+ }
+ ]
+ }
+ ]
+ }
+ 06_05_00__api_request_overrides__project_wiki_link__001: |-
+ {
+ "type": "doc",
+ "content": [
+ {
+ "type": "paragraph",
+ "content": [
+ {
+ "type": "text",
+ "marks": [
+ {
+ "type": "link",
+ "attrs": {
+ "href": "project-wikis-test-file",
+ "target": "_blank",
+ "class": null,
+ "title": null,
+ "canonicalSrc": "project-wikis-test-file",
+ "isReference": false
+ }
+ }
+ ],
+ "text": "project-wikis-test-file"
+ }
+ ]
+ }
+ ]
+ }
+ YAML
end
before do
@@ -627,6 +874,7 @@
expect(es_prosemirror_json_yml_contents).to eq(expected_prosemirror_json_contents)
end
end
+ # rubocop:enable RSpec/MultipleMemoizedHelpers
def reread_io(io)
# Reset the io StringIO to the beginning position of the buffer
diff --git a/spec/scripts/lib/glfm/update_specification_spec.rb b/spec/scripts/lib/glfm/update_specification_spec.rb
index e8d34b13efa54..9fb671e0016a1 100644
--- a/spec/scripts/lib/glfm/update_specification_spec.rb
+++ b/spec/scripts/lib/glfm/update_specification_spec.rb
@@ -18,7 +18,7 @@
let(:glfm_spec_txt_io) { StringIO.new }
let(:ghfm_spec_txt_contents) do
- <<~GHFM_SPEC_TXT_CONTENTS
+ <<~MARKDOWN
---
title: GitHub Flavored Markdown Spec
version: 0.29
@@ -49,25 +49,26 @@
# Appendix
Appendix text.
- GHFM_SPEC_TXT_CONTENTS
+ MARKDOWN
end
let(:glfm_intro_txt_contents) do
- <<~GLFM_INTRO_TXT_CONTENTS
+ # language=Markdown
+ <<~MARKDOWN
# Introduction
## What is GitLab Flavored Markdown?
Intro text about GitLab Flavored Markdown.
- GLFM_INTRO_TXT_CONTENTS
+ MARKDOWN
end
let(:glfm_examples_txt_contents) do
- <<~GLFM_EXAMPLES_TXT_CONTENTS
+ <<~MARKDOWN
# GitLab-Specific Section with Examples
Some examples.
- GLFM_EXAMPLES_TXT_CONTENTS
+ MARKDOWN
end
before do
@@ -118,12 +119,12 @@
context 'with error handling' do
context 'with a version mismatch' do
let(:ghfm_spec_txt_contents) do
- <<~GHFM_SPEC_TXT_CONTENTS
+ <<~MARKDOWN
---
title: GitHub Flavored Markdown Spec
version: 0.30
...
- GHFM_SPEC_TXT_CONTENTS
+ MARKDOWN
end
it 'raises an error' do
@@ -173,7 +174,7 @@
end
it 'inserts the GitLab examples sections before the appendix section' do
- expected = <<~GHFM_SPEC_TXT_CONTENTS
+ expected = <<~MARKDOWN
End of last GitHub examples section.
# GitLab-Specific Section with Examples
@@ -183,7 +184,7 @@
<!-- END TESTS -->
# Appendix
- GHFM_SPEC_TXT_CONTENTS
+ MARKDOWN
expect(glfm_contents).to match(/#{Regexp.escape(expected)}/m)
end
end
diff --git a/spec/support/shared_contexts/markdown_snapshot_shared_examples.rb b/spec/support/shared_contexts/glfm/api_markdown_snapshot_shared_context.rb
similarity index 66%
rename from spec/support/shared_contexts/markdown_snapshot_shared_examples.rb
rename to spec/support/shared_contexts/glfm/api_markdown_snapshot_shared_context.rb
index 8401ab6541811..3623fa0850d8f 100644
--- a/spec/support/shared_contexts/markdown_snapshot_shared_examples.rb
+++ b/spec/support/shared_contexts/glfm/api_markdown_snapshot_shared_context.rb
@@ -1,37 +1,28 @@
# frozen_string_literal: true
-require 'spec_helper'
+require_relative '../../../../scripts/lib/glfm/constants'
# See https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#markdown-snapshot-testing
# for documentation on this spec.
-RSpec.shared_context 'with API::Markdown Snapshot shared context' do |glfm_specification_dir|
- include ApiHelpers
-
- let_it_be(:user) { create(:user) }
- let_it_be(:api_url) { api('/markdown', user) }
-
- before do
- # Set 'GITLAB_TEST_FOOTNOTE_ID' in order to override random number generation in
- # Banzai::Filter::FootnoteFilter#random_number, and thus avoid the need to
- # perform normalization on the value. See:
- # https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#normalization
- stub_env('GITLAB_TEST_FOOTNOTE_ID', 42)
- end
+RSpec.shared_context 'with API::Markdown Snapshot shared context' do |ee_only: false|
+ include_context 'with GLFM example snapshot fixtures'
- markdown_examples, html_examples = %w[markdown.yml html.yml].map do |file_name|
- yaml = File.read("#{glfm_specification_dir}/example_snapshots/#{file_name}")
- YAML.safe_load(yaml, symbolize_names: true, aliases: true)
- end
+ include ApiHelpers
- normalizations_yaml = File.read(
- "#{glfm_specification_dir}/input/gitlab_flavored_markdown/glfm_example_normalizations.yml")
- normalizations_by_example_name = YAML.safe_load(normalizations_yaml, symbolize_names: true, aliases: true)
+ markdown_examples, html_examples, normalizations_by_example_name, metadata_by_example_name = [
+ Glfm::Constants::ES_MARKDOWN_YML_PATH,
+ Glfm::Constants::ES_HTML_YML_PATH,
+ Glfm::Constants::GLFM_EXAMPLE_NORMALIZATIONS_YML_PATH,
+ Glfm::Constants::GLFM_EXAMPLE_METADATA_YML_PATH
+ ].map { |path| YAML.safe_load(File.open(path), symbolize_names: true, aliases: true) }
if (focused_markdown_examples_string = ENV['FOCUSED_MARKDOWN_EXAMPLES'])
focused_markdown_examples = focused_markdown_examples_string.split(',').map(&:strip).map(&:to_sym)
markdown_examples.select! { |example_name| focused_markdown_examples.include?(example_name) }
end
+ markdown_examples.select! { |example_name| !!metadata_by_example_name&.dig(example_name, :ee) == ee_only }
+
markdown_examples.each do |name, markdown|
context "for #{name}" do
let(:html) { html_examples.fetch(name).fetch(:static) }
@@ -40,6 +31,7 @@
it "verifies conversion of GLFM to HTML", :unlimited_max_formatted_output_length do
# noinspection RubyResolve
normalized_html = normalize_html(html, normalizations)
+ api_url = metadata_by_example_name&.dig(name, :api_request_override_path) || (api "/markdown")
post api_url, params: { text: markdown, gfm: true }
expect(response).to be_successful
diff --git a/spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb b/spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb
new file mode 100644
index 0000000000000..22b401bc8413e
--- /dev/null
+++ b/spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb
@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+RSpec.shared_context 'with GLFM example snapshot fixtures' do
+ let_it_be(:user) { create(:user) }
+ let_it_be(:group) { create(:group, name: 'glfm_group').tap { |group| group.add_owner(user) } }
+
+ let_it_be(:project) do
+ # NOTE: We hardcode the IDs on all fixtures to prevent variability in the
+ # rendered HTML/Prosemirror JSON, and to minimize the need for normalization:
+ # https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#normalization
+ create(:project, :repository, creator: user, group: group, name: 'glfm_project', id: 77777)
+ end
+
+ let_it_be(:project_snippet) { create(:project_snippet, title: 'glfm_project_snippet', id: 88888, project: project) }
+ let_it_be(:personal_snippet) { create(:snippet, id: 99999) }
+
+ before do
+ # Set 'GITLAB_TEST_FOOTNOTE_ID' in order to override random number generation in
+ # Banzai::Filter::FootnoteFilter#random_number, and thus avoid the need to
+ # perform normalization on the value. See:
+ # https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#normalization
+ stub_env('GITLAB_TEST_FOOTNOTE_ID', 42)
+
+ stub_licensed_features(group_wikis: true)
+ sign_in(user)
+ end
+end
--
GitLab