Add top level examples folder and command to run, --run-examples. (#52027) (#52739)

* Add top level examples folder and command to run, `--run-examples`.

* Add comment explaining reason --run-examples flag turns off base path.

.ci/packer_cache.sh

@@ -44,6 +44,7 @@ tar -cf "$HOME/.kibana/bootstrap_cache/$branch.tar" \
   x-pack/legacy/plugins/*/node_modules \
   x-pack/legacy/plugins/reporting/.chromium \
   test/plugin_functional/plugins/*/node_modules \
+  examples/*/node_modules \
   .es \
   .chromedriver \
   .geckodriver;

examples/README.md

@@ -0,0 +1,8 @@
+## Example plugins
+
+This folder contains example plugins.  To run the plugins in this folder, use the `--run-examples` flag, via
+
+```
+yarn start --run-examples
+```
+

examples/demo_search/README.md

@@ -0,0 +1,8 @@
+## Demo search strategy
+
+This example registers a custom search strategy that simply takes a name string in the request and returns the
+string `Hello {name}`
+
+To see the demo search strategy in action, navigate to the `Search explorer` app.
+
+To run these examples, use the command `yarn start --run-examples`.

examples/demo_search/common/index.ts

@@ -17,10 +17,7 @@
  * under the License.
  */
 
-import {
-  IKibanaSearchRequest,
-  IKibanaSearchResponse,
-} from '../../../../../src/plugins/data/public';
+import { IKibanaSearchRequest, IKibanaSearchResponse } from '../../../src/plugins/data/public';
 
 export const DEMO_SEARCH_STRATEGY = 'DEMO_SEARCH_STRATEGY';
 

examples/demo_search/package.json

@@ -8,7 +8,7 @@
   },
   "license": "Apache-2.0",
   "scripts": {
-    "kbn": "node ../../../../scripts/kbn.js",
+    "kbn": "node ../../scripts/kbn.js",
     "build": "rm -rf './target' && tsc"
   },
   "devDependencies": {

examples/demo_search/public/demo_search_strategy.ts

@@ -22,8 +22,8 @@ import {
   ISearchContext,
   SYNC_SEARCH_STRATEGY,
   ISearchGeneric,
-} from '../../../../../src/plugins/data/public';
-import { TSearchStrategyProvider, ISearchStrategy } from '../../../../../src/plugins/data/public';
+} from '../../../src/plugins/data/public';
+import { TSearchStrategyProvider, ISearchStrategy } from '../../../src/plugins/data/public';
 
 import { DEMO_SEARCH_STRATEGY, IDemoResponse } from '../common';
 

examples/demo_search/public/plugin.ts

@@ -17,8 +17,8 @@
  * under the License.
  */
 
-import { DataPublicPluginSetup } from '../../../../../src/plugins/data/public';
-import { Plugin, CoreSetup, PluginInitializerContext } from '../../../../../src/core/public';
+import { DataPublicPluginSetup } from '../../../src/plugins/data/public';
+import { Plugin, CoreSetup, PluginInitializerContext } from '../../../src/core/public';
 import { DEMO_SEARCH_STRATEGY } from '../common';
 import { demoClientSearchStrategyProvider } from './demo_search_strategy';
 import { IDemoRequest, IDemoResponse } from '../common';
@@ -36,7 +36,7 @@ interface DemoDataSearchSetupDependencies {
  * If the caller does not pass in the right `request` shape, typescript will
  * complain. The caller will also get a typed response.
  */
-declare module '../../../../../src/plugins/data/public' {
+declare module '../../../src/plugins/data/public' {
   export interface IRequestTypesMap {
     [DEMO_SEARCH_STRATEGY]: IDemoRequest;
   }

examples/demo_search/server/demo_search_strategy.ts

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { TSearchStrategyProvider } from 'src/plugins/data/server';
+import { TSearchStrategyProvider } from '../../../src/plugins/data/server';
 import { DEMO_SEARCH_STRATEGY } from '../common';
 
 export const demoSearchStrategyProvider: TSearchStrategyProvider<typeof DEMO_SEARCH_STRATEGY> = () => {

examples/demo_search/server/plugin.ts

@@ -35,7 +35,7 @@ interface IDemoSearchExplorerDeps {
  * If the caller does not pass in the right `request` shape, typescript will
  * complain. The caller will also get a typed response.
  */
-declare module '../../../../../src/plugins/data/server' {
+declare module '../../../src/plugins/data/server' {
   export interface IRequestTypesMap {
     [DEMO_SEARCH_STRATEGY]: IDemoRequest;
   }

examples/demo_search/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../../tsconfig.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "./target",
     "skipLibCheck": true
@@ -10,7 +10,7 @@
     "public/**/*.ts",
     "public/**/*.tsx",
     "server/**/*.ts",
-    "../../../../typings/**/*"
+    "../../typings/**/*"
   ],
   "exclude": []
 }

examples/search_explorer/README.md

@@ -0,0 +1,8 @@
+## Search explorer
+
+This example search explorer app shows how to use different search strategies in order to retrieve data.
+
+One demo uses the built in elasticsearch search strategy, and runs a search against data in elasticsearch. The
+other demo uses the custom demo search strategy, a custom search strategy registerd inside the [demo_search plugin](../demo_search).
+
+To run this example, use the command `yarn start --run-examples`.

examples/search_explorer/package.json

@@ -8,7 +8,7 @@
   },
   "license": "Apache-2.0",
   "scripts": {
-    "kbn": "node ../../../../scripts/kbn.js",
+    "kbn": "node ../../scripts/kbn.js",
     "build": "rm -rf './target' && tsc"
   },
   "devDependencies": {

examples/search_explorer/public/application.tsx

@@ -28,7 +28,7 @@ import {
   EuiSideNav,
 } from '@elastic/eui';
 
-import { AppMountContext, AppMountParameters } from '../../../../../src/core/public';
+import { AppMountContext, AppMountParameters } from '../../../src/core/public';
 import { EsSearchTest } from './es_strategy';
 import { Page } from './page';
 import { DemoStrategy } from './demo_strategy';

examples/search_explorer/public/demo_strategy.tsx

@@ -25,7 +25,7 @@ import {
   EuiFlexGroup,
   EuiFieldText,
 } from '@elastic/eui';
-import { ISearchGeneric } from '../../../../../src/plugins/data/public';
+import { ISearchGeneric } from '../../../src/plugins/data/public';
 import { DoSearch } from './do_search';
 import { GuideSection } from './guide_section';
 

examples/search_explorer/public/do_search.tsx

@@ -21,10 +21,7 @@ import React from 'react';
 import { EuiButton, EuiCodeBlock, EuiFlexItem, EuiFlexGroup, EuiText } from '@elastic/eui';
 import { EuiProgress } from '@elastic/eui';
 import { Observable } from 'rxjs';
-import {
-  IKibanaSearchResponse,
-  IKibanaSearchRequest,
-} from '../../../../../src/plugins/data/public';
+import { IKibanaSearchResponse, IKibanaSearchRequest } from '../../../src/plugins/data/public';
 
 interface Props {
   request: IKibanaSearchRequest;

examples/search_explorer/public/es_strategy.tsx

@@ -29,19 +29,19 @@ import {
   ISearchGeneric,
   IEsSearchResponse,
   IEsSearchRequest,
-} from '../../../../../src/plugins/data/public';
+} from '../../../src/plugins/data/public';
 import { DoSearch } from './do_search';
 import { GuideSection } from './guide_section';
 
 // @ts-ignore
-import serverPlugin from '!!raw-loader!./../../../../../src/plugins/data/server/search/es_search/es_search_service';
+import serverPlugin from '!!raw-loader!./../../../src/plugins/data/server/search/es_search/es_search_service';
 // @ts-ignore
-import serverStrategy from '!!raw-loader!./../../../../../src/plugins/data/server/search/es_search/es_search_strategy';
+import serverStrategy from '!!raw-loader!./../../../src/plugins/data/server/search/es_search/es_search_strategy';
 
 // @ts-ignore
-import publicPlugin from '!!raw-loader!./../../../../../src/plugins/data/public/search/es_search/es_search_service';
+import publicPlugin from '!!raw-loader!./../../../src/plugins/data/public/search/es_search/es_search_service';
 // @ts-ignore
-import publicStrategy from '!!raw-loader!./../../../../../src/plugins/data/public/search/es_search/es_search_strategy';
+import publicStrategy from '!!raw-loader!./../../../src/plugins/data/public/search/es_search/es_search_strategy';
 
 interface Props {
   search: ISearchGeneric;

examples/search_explorer/public/plugin.tsx

@@ -18,7 +18,7 @@
  */
 
 import { Plugin, CoreSetup } from 'kibana/public';
-import { ISearchAppMountContext } from '../../../../../src/plugins/data/public';
+import { ISearchAppMountContext } from '../../../src/plugins/data/public';
 
 declare module 'kibana/public' {
   interface AppMountContext {

examples/search_explorer/public/search_api.tsx

@@ -20,22 +20,22 @@ import React from 'react';
 import { GuideSection } from './guide_section';
 
 // @ts-ignore
-import publicSetupContract from '!!raw-loader!./../../../../../src/plugins/data/public/search/i_search_setup';
+import publicSetupContract from '!!raw-loader!./../../../src/plugins/data/public/search/i_search_setup';
 // @ts-ignore
-import publicSearchStrategy from '!!raw-loader!./../../../../../src/plugins/data/public/search/i_search_strategy';
+import publicSearchStrategy from '!!raw-loader!./../../../src/plugins/data/public/search/i_search_strategy';
 // @ts-ignore
-import publicSearch from '!!raw-loader!./../../../../../src/plugins/data/public/search/i_search';
+import publicSearch from '!!raw-loader!./../../../src/plugins/data/public/search/i_search';
 // @ts-ignore
-import publicPlugin from '!!raw-loader!./../../../../../src/plugins/data/public/search/search_service';
+import publicPlugin from '!!raw-loader!./../../../src/plugins/data/public/search/search_service';
 
 // @ts-ignore
-import serverSetupContract from '!!raw-loader!./../../../../../src/plugins/data/server/search/i_search_setup';
+import serverSetupContract from '!!raw-loader!./../../../src/plugins/data/server/search/i_search_setup';
 // @ts-ignore
-import serverSearchStrategy from '!!raw-loader!./../../../../../src/plugins/data/server/search/i_search_strategy';
+import serverSearchStrategy from '!!raw-loader!./../../../src/plugins/data/server/search/i_search_strategy';
 // @ts-ignore
-import serverSearch from '!!raw-loader!./../../../../../src/plugins/data/server/search/i_search';
+import serverSearch from '!!raw-loader!./../../../src/plugins/data/server/search/i_search';
 // @ts-ignore
-import serverPlugin from '!!raw-loader!./../../../../../src/plugins/data/server/search/search_service';
+import serverPlugin from '!!raw-loader!./../../../src/plugins/data/server/search/search_service';
 
 export const SearchApiPage = () => (
   <GuideSection

examples/search_explorer/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../../tsconfig.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "./target",
     "skipLibCheck": true
@@ -9,7 +9,7 @@
     "public/**/*.ts",
     "public/**/*.tsx",
     "server/**/*.ts",
-    "../../../../typings/**/*",
+    "../../typings/**/*",
   ],
   "exclude": []
 }

package.json

@@ -94,6 +94,7 @@
       "packages/*",
       "x-pack",
       "x-pack/legacy/plugins/*",
+      "examples/*",
       "test/plugin_functional/plugins/*",
       "test/interpreter_functional/plugins/*"
     ],

packages/kbn-pm/dist/index.js

@@ -23185,6 +23185,7 @@ function getProjectPaths(rootPath, options = {}) {
 
   projectPaths.push(Object(path__WEBPACK_IMPORTED_MODULE_0__["resolve"])(rootPath, 'test/plugin_functional/plugins/*'));
   projectPaths.push(Object(path__WEBPACK_IMPORTED_MODULE_0__["resolve"])(rootPath, 'test/interpreter_functional/plugins/*'));
+  projectPaths.push(Object(path__WEBPACK_IMPORTED_MODULE_0__["resolve"])(rootPath, 'examples/*'));
 
   if (!ossOnly) {
     projectPaths.push(Object(path__WEBPACK_IMPORTED_MODULE_0__["resolve"])(rootPath, 'x-pack'));

packages/kbn-pm/src/config.ts

@@ -44,6 +44,7 @@ export function getProjectPaths(rootPath: string, options: IProjectPathOptions =
   // correct and the expect behavior.
   projectPaths.push(resolve(rootPath, 'test/plugin_functional/plugins/*'));
   projectPaths.push(resolve(rootPath, 'test/interpreter_functional/plugins/*'));
+  projectPaths.push(resolve(rootPath, 'examples/*'));
 
   if (!ossOnly) {
     projectPaths.push(resolve(rootPath, 'x-pack'));

renovate.json5

@@ -13,6 +13,7 @@
     'x-pack/package.json',
     'x-pack/legacy/plugins/*/package.json',
     'packages/*/package.json',
+    'examples/*/package.json',
     'test/plugin_functional/plugins/*/package.json',
     'test/interpreter_functional/plugins/*/package.json',
   ],

scripts/functional_tests.js

@@ -24,4 +24,5 @@ require('@kbn/test').runTestsCli([
   require.resolve('../test/plugin_functional/config.js'),
   require.resolve('../test/interpreter_functional/config.ts'),
   require.resolve('../test/ui_capabilities/newsfeed_err/config.ts'),
+  require.resolve('../test/examples/config.js')
 ]);

src/cli/serve/serve.js

@@ -144,6 +144,11 @@ function applyConfigOverrides(rawConfig, opts, extraCliOptions) {
   set('plugins.paths', _.compact([].concat(
     get('plugins.paths'),
     opts.pluginPath,
+    opts.runExamples ? [
+      // Ideally this would automatically include all plugins in the examples dir
+      fromRoot('examples/demo_search'),
+      fromRoot('examples/search_explorer'),
+    ] : [],
 
     XPACK_INSTALLED && !opts.oss
       ? [XPACK_DIR]
@@ -201,7 +206,8 @@ export default function (program) {
 
   if (!IS_KIBANA_DISTRIBUTABLE) {
     command
-      .option('--oss', 'Start Kibana without X-Pack');
+      .option('--oss', 'Start Kibana without X-Pack')
+      .option('--run-examples', 'Adds plugin paths for all the Kibana example plugins and runs with no base path');
   }
 
   if (CAN_CLUSTER) {
@@ -238,7 +244,12 @@ export default function (program) {
           silent: !!opts.silent,
           watch: !!opts.watch,
           repl: !!opts.repl,
-          basePath: !!opts.basePath,
+          // We want to run without base path when the `--run-examples` flag is given so that we can use local
+          // links in other documentation sources, like "View this tutorial [here](http://localhost:5601/app/tutorial/xyz)".
+          // We can tell users they only have to run with `yarn start --run-examples` to get those
+          // local links to work.  Similar to what we do for "View in Console" links in our
+          // elastic.co links.
+          basePath: opts.runExamples ? false : !!opts.basePath,
           optimize: !!opts.optimize,
           oss: !!opts.oss
         },

src/dev/typescript/projects.ts

@@ -40,6 +40,9 @@ export const PROJECTS = [
   ...glob
     .sync('packages/*/tsconfig.json', { cwd: REPO_ROOT })
     .map(path => new Project(resolve(REPO_ROOT, path))),
+  ...glob
+    .sync('examples/*/tsconfig.json', { cwd: REPO_ROOT })
+    .map(path => new Project(resolve(REPO_ROOT, path))),
   ...glob
     .sync('test/plugin_functional/plugins/*/tsconfig.json', { cwd: REPO_ROOT })
     .map(path => new Project(resolve(REPO_ROOT, path))),

test/examples/README.md

@@ -0,0 +1,23 @@
+# Example plugin functional tests
+
+This folder contains functional tests for the example plugins.
+
+## Run the test
+
+To run these tests during development you can use the following commands:
+
+```
+# Start the test server (can continue running)
+node scripts/functional_tests_server.js --config test/examples/config.js
+# Start a test run
+node scripts/functional_test_runner.js --config test/examples/config.js
+```
+
+## Run Kibana with a test plugin
+
+In case you want to start Kibana with the example plugins, you can just run:
+
+```
+yarn start --run-examples
+```
+

test/examples/config.js

@@ -0,0 +1,55 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import path from 'path';
+import { services } from '../plugin_functional/services';
+
+export default async function ({ readConfigFile }) {
+  const functionalConfig = await readConfigFile(require.resolve('../functional/config'));
+
+  return {
+    testFiles: [
+      require.resolve('./search'),
+    ],
+    services: {
+      ...functionalConfig.get('services'),
+      ...services,
+    },
+    pageObjects: functionalConfig.get('pageObjects'),
+    servers: functionalConfig.get('servers'),
+    esTestCluster: functionalConfig.get('esTestCluster'),
+    apps: functionalConfig.get('apps'),
+    esArchiver: {
+      directory: path.resolve(__dirname, '../es_archives')
+    },
+    screenshots: functionalConfig.get('screenshots'),
+    junit: {
+      reportName: 'Example plugin functional tests',
+    },
+    kbnTestServer: {
+      ...functionalConfig.get('kbnTestServer'),
+      serverArgs: [
+        ...functionalConfig.get('kbnTestServer.serverArgs'),
+        '--run-examples',
+        // Required to run examples
+        '--env.name=development',
+      ],
+    },
+  };
+}

test/plugin_functional/config.js

@@ -33,7 +33,6 @@ export default async function ({ readConfigFile }) {
       require.resolve('./test_suites/app_plugins'),
       require.resolve('./test_suites/custom_visualizations'),
       require.resolve('./test_suites/panel_actions'),
-      require.resolve('./test_suites/search'),
 
       /**
        * @todo Work on re-enabling this test suite after this is merged. These tests pass