Merge pull request #62 from kris7t/integration-tests

Integration tests framework
graphs4value · Jul 29, 2024 · 85b30d2 · 85b30d2
2 parents f675090 + 9fdd5e0
commit 85b30d2
Show file tree

Hide file tree

Showing 172 changed files with 5,416 additions and 329 deletions.
diff --git a/subprojects/docs/build.gradle.kts b/subprojects/docs/build.gradle.kts
@@ -22,22 +22,37 @@ val javadocs: Configuration by configurations.creating {
 	isCanBeResolved = true
 }
 
+val releasedJavadocs: Configuration by configurations.creating {
+	isCanBeConsumed = false
+	isCanBeResolved = true
+}
+
+val interpreterGroup = property("tools.refinery.interpreter.group").toString()
+val releasedVersion = property("tools.refinery.release").toString()
+val releasedInterpreterVersion = property("tools.refinery.interpreter.release").toString()
+
+repositories {
+	mavenCentral()
+}
+
 dependencies {
 	gradle.projectsEvaluated {
 		for (subproject in rootProject.subprojects) {
 			if (subproject.plugins.hasPlugin(JavaLibraryPlugin::class)) {
 				javadocs(project(subproject.path, "javadocElements"))
+				val releasedProjectVersion = if (subproject.group.toString() == interpreterGroup)
+					releasedInterpreterVersion else releasedVersion
+				releasedJavadocs("${subproject.group}:${subproject.name}:$releasedProjectVersion:javadoc@jar")
 			}
 		}
 	}
 
 	javadocs(project(":refinery-gradle-plugins", "javadocElements"))
+	releasedJavadocs("tools.refinery:refinery-gradle-plugins:$releasedVersion:javadoc@jar")
 }
 
 val srcDir = "src"
-
 val docusaurusOutputDir = layout.buildDirectory.dir("docusaurus")
-
 val javadocsDir = layout.buildDirectory.dir("javadocs")
 
 val configFiles: FileCollection = files(
@@ -72,7 +87,7 @@ abstract class ExtractJavadocTask : DefaultTask() {
 		fs.delete {
 			delete(targetDir)
 		}
-		val javadocsDocsDir = targetDir.get().dir("develop/javadoc")
+		val javadocsDocsDir = targetDir.get()
 		resolvedJavadocArtifacts.get().forEach { artifact ->
 			fs.copy {
 				from(archive.zipTree(artifact.value))
@@ -82,19 +97,29 @@ abstract class ExtractJavadocTask : DefaultTask() {
 	}
 }
 
+fun resolveJavadocs(configuration: Configuration): Provider<Map<String, File>> {
+	return provider {
+		configuration.resolvedConfiguration.resolvedArtifacts.associate { artifact ->
+			artifact.moduleVersion.id.name to artifact.file
+		}
+	}
+}
+
 tasks {
 	val extractJavadocs by registering(ExtractJavadocTask::class) {
 		dependsOn(javadocs)
-		targetDir = javadocsDir
-		resolvedJavadocArtifacts = provider {
-			javadocs.resolvedConfiguration.resolvedArtifacts.associate { artifact ->
-				artifact.moduleVersion.id.name to artifact.file
-			}
-		}
+		targetDir = javadocsDir.map { it.dir("snapshot/develop/javadoc" ) }
+		resolvedJavadocArtifacts = resolveJavadocs(javadocs)
+	}
+
+	val extractReleasedJavadocs by registering(ExtractJavadocTask::class) {
+		dependsOn(releasedJavadocs)
+		targetDir = javadocsDir.map { it.dir("develop/javadoc" ) }
+		resolvedJavadocArtifacts = resolveJavadocs(releasedJavadocs)
 	}
 
 	assembleFrontend {
-		dependsOn(extractJavadocs)
+		dependsOn(extractJavadocs, extractReleasedJavadocs)
 		inputs.dir(srcDir)
 		inputs.dir("static")
 		inputs.dir(javadocsDir)

diff --git a/subprojects/docs/docusaurus.config.ts b/subprojects/docs/docusaurus.config.ts
@@ -16,30 +16,25 @@ import type { UserThemeConfig } from '@docusaurus/theme-common';
 import type { UserThemeConfig as AlgoliaConfig } from '@docusaurus/theme-search-algolia';
 import type { Config } from '@docusaurus/types';
 import type { Config as SwcConfig } from '@swc/core';
+import { PropertiesFile } from 'java-properties';
 import { themes } from 'prism-react-renderer';
 import smartypants from 'remark-smartypants';
 
 import remarkPosix2Windows from './src/plugins/remarkPosix2Windows';
 import remarkReplaceVariables from './src/plugins/remarkReplaceVariables';
 
+const properties = new PropertiesFile(
+  path.join(__dirname, '../../gradle.properties'),
+);
+
 const markdownOptions: Partial<MDXOptions> = {
   remarkPlugins: [
-    [
-      remarkReplaceVariables,
-      { propertiesPath: path.join(__dirname, '../../gradle.properties') },
-    ],
+    [remarkReplaceVariables, { properties }],
     [smartypants, { dashes: 'oldschool' }],
     remarkPosix2Windows,
   ],
 };
 
-const docsOptions = {
-  ...markdownOptions,
-  sidebarPath: undefined,
-  editUrl:
-    'https://github.com/graphs4value/refinery/edit/main/subprojects/docs',
-} satisfies DocsOptions;
-
 export default {
   title: 'Refinery',
   tagline: 'An efficient graph solver for generating well-formed models',
@@ -52,19 +47,18 @@ export default {
     [
       '@docusaurus/plugin-content-docs',
       {
-        id: 'learn',
-        path: 'src/learn',
-        routeBasePath: '/learn',
-        ...docsOptions,
-      } satisfies DocsOptions,
-    ],
-    [
-      '@docusaurus/plugin-content-docs',
-      {
-        id: 'develop',
-        path: 'src/develop',
-        routeBasePath: '/develop',
-        ...docsOptions,
+        path: 'src/docs',
+        routeBasePath: '/',
+        sidebarPath: './sidebars.ts',
+        editUrl:
+          'https://github.com/graphs4value/refinery/edit/main/subprojects/docs',
+        versions: {
+          current: {
+            path: 'snapshot',
+            label: `${String(properties.get('version'))} 🚧`,
+          },
+        },
+        ...markdownOptions,
       } satisfies DocsOptions,
     ],
     [
@@ -113,13 +107,14 @@ export default {
       hideOnScroll: true,
       items: [
         {
+          type: 'doc',
           label: 'Learn',
-          to: '/learn',
+          docId: 'learn/index',
         },
         {
+          type: 'doc',
           label: 'Develop',
-          to: '/develop/java',
-          activeBasePath: '/develop',
+          docId: 'develop/java',
         },
         {
           label: 'GitHub',
@@ -132,6 +127,10 @@ export default {
           href: 'https://refinery.services/',
           className: 'navbar__link--try-now',
         },
+        {
+          type: 'docsVersionDropdown',
+          position: 'right',
+        },
       ],
     },
     footer: {
@@ -228,10 +227,8 @@ export default {
       appId: 'KYHOYEO80F',
       apiKey: '152acfb8d1ad9e10f29f083a6b017a69',
       indexName: 'refinery',
-      // We don't have any context specified, so we need to disable this to return results.
-      contextualSearch: false,
       // Javadoc doesn't use the Docusaurus router and has to be navigated to with `location.href` instead.
-      externalUrlRegex: '/develop/javadoc/.+',
+      externalUrlRegex: '/([^/]+/)?develop/javadoc/.+',
     },
   } satisfies UserThemeConfig & AlgoliaConfig,
   webpack: {

diff --git a/subprojects/docs/sidebars.ts b/subprojects/docs/sidebars.ts
@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+export default {
+  learnSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: 'learn',
+    },
+  ],
+  developSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: 'develop',
+    },
+  ],
+} satisfies SidebarsConfig;
diff --git a/subprojects/docs/src/css/custom.css b/subprojects/docs/src/css/custom.css
@@ -80,6 +80,12 @@ code {
   --ifm-navbar-shadow: var(--ifm-global-shadow-lw) !important;
 }
 
+@media (max-width: 996px) {
+  .navbar__inner .navbar__logo {
+    display: none;
+  }
+}
+
 .button, .navbar__link, .footer__link-item {
   text-transform: uppercase;
   font-variation-settings: 'wdth' 87.5;
@@ -112,7 +118,7 @@ code {
 }
 
 .navbar__inner .navbar__link--try-now {
-  margin: 0 0.75rem 0 0.5rem;
+  margin: 0 0.5rem;
   padding: 0.25rem 1.25rem;
   border-radius: 50em;
 }

diff --git a/...docs/src/develop/contributing/commands.md → ...src/docs/develop/contributing/commands.md b/...docs/src/develop/contributing/commands.md → ...src/docs/develop/contributing/commands.md
@@ -34,8 +34,8 @@ This will also be run by GitHub Actions for each commit or pull requests.
 
 Publishes the Refinery Java artifacts to the [Maven local repository](https://www.baeldung.com/maven-local-repository).
 
-Build tools, such as Gradle, will be able to consume such artifacts, which enables you to use the latest version of Refinery -- possibly including your own modification -- in other Java projects.
-For more information, see our [programming guide](../../java).
+Build tools, such as Gradle, will be able to consume such artifacts, which enables you to use the latest version of Refinery -- possibly including your own modifications -- in other Java projects.
+For more information, see our [programming guide](/snapshot/develop/java).
 
 ### `serve`
 
@@ -49,7 +49,7 @@ This task is ideal for running the Refinery backend if you don't intend to work
 The Refinery frontend TypeScript projects is automatically built before the server starts.
 The server will use the latest build output of the frontend as static assets.
 
-The behavior of this task is influenced by the same [environmental variables](/learn/docker#environmental-variables) as the Refinery [Docker container](/learn/docker).
+The behavior of this task is influenced by the same [environmental variables](../../../learn/docker#environmental-variables) as the Refinery [Docker container](../../../learn/docker).
 However, the default value of `REFINERY_LISTEN_PORT` is `1312`.
 
 ### `serveBackend`
@@ -64,7 +64,7 @@ This task is ideal for running the Refinery backend if you're working on the fro
 No static assets will be build.
 You'll need to use [`yarnw frontend dev`](#frontend-dev)
 
-Like [`./gradlew serve`](#serve), the behavior of this task is influenced by the same [environmental variables](/learn/docker#environmental-variables) as the Refinery [Docker container](/learn/docker).
+Like [`./gradlew serve`](#serve), the behavior of this task is influenced by the same [environmental variables](../../../learn/docker#environmental-variables) as the Refinery [Docker container](../../../learn/docker).
 However, the default value of `REFINERY_LISTEN_PORT` is `1312`.
 
 ## Yarn commands

diff --git a/...ocs/src/develop/contributing/ide-setup.md → ...rc/docs/develop/contributing/ide-setup.md b/...ocs/src/develop/contributing/ide-setup.md → ...rc/docs/develop/contributing/ide-setup.md
diff --git a/...ts/docs/src/develop/contributing/index.md → ...cs/src/docs/develop/contributing/index.md b/...ts/docs/src/develop/contributing/index.md → ...cs/src/docs/develop/contributing/index.md
diff --git a/subprojects/docs/src/develop/java.md → subprojects/docs/src/docs/develop/java.md b/subprojects/docs/src/develop/java.md → subprojects/docs/src/docs/develop/java.md
@@ -13,7 +13,7 @@ See the [contributor's guide](../contributing) for information on building and m
 :::note
 
 Refinery can run as a cloud-based [_Graph Solver as a Service_](https://refinery.services/) without local installation.
-You can also run a compiled version as a [Docker container](/learn/docker).
+You can also run a compiled version as a [Docker container](../../learn/docker).
 
 :::
 
@@ -24,36 +24,17 @@ Below, you can find instructions on using [Gradle](#gradle) or [Apache Maven](#m
 We recommend [Gradle](https://gradle.org/) as a build system for creating Java programs that use Refinery as a library.
 We created a [Gradle plugin](pathname://../javadoc/refinery-gradle-plugins/) to simplify project configuration.
 
-To find out how to add the plugin to your build, select below whether you want to use a **released** version or a **snapshot** version of refinery or whether you want to build Refinery **locally** yourself.
+This tutorial explains how to use a **snapshot** or **local** pre-release version of Refinery with Gradle.
+Released versions, such as the [**latest version**](/develop/java#gradle), are available from [Maven Central](https://central.sonatype.com/namespace/tools.refinery).
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 <Tabs groupId="version">
-  <TabItem value="release" label="Release" default>
-    To find out the configuration required to use our artifacts, select whether you use a Kotlin-based (`.gradle.kts`) or a Groovy-based (`.gradle`) configuration format for your Gradle build. You should add this code to your Gradle *settings* file, which is named `settings.gradle.kts` or `settings.gradle`.
-
-    <Tabs groupId="gradleLanguage">
-      <TabItem value="kotlin" label="Kotlin">
-        ```kotlin title="settings.gradle.kts"
-        plugins {
-            id("tools.refinery.settings") version "@@@tools.refinery.release@@@"
-        }
-        ```
-      </TabItem>
-      <TabItem value="groovy" label="Groovy">
-        ```groovy title="settings.gradle"
-        plugins {
-            id 'tools.refinery.settings' version '@@@tools.refinery.release@@@'
-        }
-        ```
-      </TabItem>
-    </Tabs>
-  </TabItem>
-  <TabItem value="snapshot" label="Snapshot">
+  <TabItem value="snapshot" label="Snapshot" default>
     We always publish a [SNAPSHOT](https://maven.apache.org/guides/getting-started/index.html#what-is-a-snapshot-version) version of Refinery based on the latest commit in our [Git repository](https://github.com/graphs4value/refinery). This is the development version of our code and may change without warning at any time.
 
-    To find out the configuration required to use our snapshot artifacts, select whether you use a Kotlin-based (`.gradle.kts`) or a Groovy-based (`.gradle`) configuration format for your Gradle build. You should add this code to your Gradle *settings* file, which is named `settings.gradle.kts` or `settings.gradle`.
+    To find out the configuration for using our snapshot artifacts, select whether you use a Kotlin-based (`.gradle.kts`) or a Groovy-based (`.gradle`) configuration format for your Gradle build. You should add this code to your Gradle *settings* file, which is named `settings.gradle.kts` or `settings.gradle`.
 
     <Tabs groupId="gradleLanguage">
       <TabItem value="kotlin" label="Kotlin">
@@ -96,7 +77,7 @@ import TabItem from '@theme/TabItem';
     Running Refinery from a local build is an _advanced technique_ that you should only use if you want to [contribute to Refinery](../contributing) and have modified it yourself.
     First you'll have to run the [`./gradlew publishToMavenLocal`](../contributing/commands#publishtomavenlocal) command in your local clone of the Refinery repository to install Refinery into your [local Maven repository](https://www.baeldung.com/maven-local-repository).
 
-    Next, to find out the configuration required to use the local artifacts, select whether you use a Kotlin-based (`.gradle.kts`) or a Groovy-based (`.gradle`) configuration format for your Gradle build. You should add this code to your Gradle *settings* file, which is named `settings.gradle.kts` or `settings.gradle`.
+    Next, to find out the configuration for using local artifacts, select whether you use a Kotlin-based (`.gradle.kts`) or a Groovy-based (`.gradle`) configuration format for your Gradle build. You should add this code to your Gradle *settings* file, which is named `settings.gradle.kts` or `settings.gradle`.
 
     <Tabs groupId="gradleLanguage">
       <TabItem value="kotlin" label="Kotlin">
@@ -305,29 +286,26 @@ Instead, you should use Xtext's [dependency injection](https://eclipse.dev/Xtext
   </TabItem>
 </Tabs>
 
-Afterwards, you can use the `@ExtendWith`, `@InjectWith`, and `@Inject` annotations to set up your unit test.
+The test fixtures for `refinery-language` include the `@InjectWithRefinery` [composed annotation](https://junit.org/junit5/docs/current/user-guide/#writing-tests-meta-annotations) to simplify Xtext injector configuration.
+You can use this annotation in conjunction with `@Inject` annotations to set up your unit test.
 
 ```java
 package org.example;
 
 import com.google.inject.Inject;
-import org.eclipse.xtext.testing.InjectWith;
-import org.eclipse.xtext.testing.extensions.InjectionExtension;
 import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.extension.ExtendWith;
 import tools.refinery.generator.GeneratorResult;
 import tools.refinery.generator.ModelGeneratorFactory;
 import tools.refinery.generator.ProblemLoader;
-import tools.refinery.language.tests.ProblemInjectorProvider;
+import tools.refinery.language.tests.InjectWithRefinery;
 
 import java.io.IOException;
 
 import static org.hamcrest.MatcherAssert.assertThat;
-import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.*;
 
 // highlight-start
-@ExtendWith(InjectionExtension.class)
-@InjectWith(ProblemInjectorProvider.class)
+@InjectWithRefinery
 // highlight-end
 class ExampleTest {
     // highlight-start
@@ -398,31 +376,11 @@ Do *not* attempt to set a `version` for this plugin, because versioning is alrea
 You may also develop applications based on Refiney using [Apache Maven](https://maven.apache.org/) as the build system.
 Although we don't provide a Maven plugin for simplified configuration, you can still use our [platform](https://docs.gradle.org/current/userguide/platforms.html#sub:using-platform-to-control-transitive-deps) (Maven BOM) to lock the versions of Refinery and its dependencies to tested versions.
 
-To find out how to add the BOM to your build, select below whether you want to use a **released** version or a **snapshot** version of refinery or whether you want to build Refinery **locally** yourself.
+This tutorial explains how to use a **snapshot** or **local** pre-release version of Refinery with Maven.
+Released versions, such as the [**latest version**](/develop/java#maven), are available from [Maven Central](https://central.sonatype.com/namespace/tools.refinery).
 
 <Tabs groupId="version">
-  <TabItem value="release" label="Release" default>
-    You should add the following configuration to your `pom.xml` file. If you use multi-module projects, we recommend that you add this to your parent POM.
-
-    ```xml title="pom.xml"
-    <project>
-        ...
-        <dependencyManagement>
-            <dependencies>
-                <dependency>
-                    <groupId>tools.refinery</groupId>
-                    <artifactId>refinery-bom</artifactId>
-                    <version>@@@tools.refinery.release@@@</version>
-                    <type>pom</type>
-                    <scope>import</scope>
-                </dependency>
-            </dependencies>
-        </dependencyManagement>
-        ...
-    </project>
-    ```
-  </TabItem>
-  <TabItem value="snapshot" label="Snapshot">
+  <TabItem value="snapshot" label="Snapshot" default>
     We always publish a [SNAPSHOT](https://maven.apache.org/guides/getting-started/index.html#what-is-a-snapshot-version) version of Refinery based on the latest commit in our [Git repository](https://github.com/graphs4value/refinery). This is the development version of our code and may change without warning at any time.
 
     You should add the following configuration to your `pom.xml` file. If you use multi-module projects, we recommend that you add this to your parent POM.