Updated dev guide instructions to work with master (#30014)

matschaffer · web-flow · commit 3ed5763ace72 · 2022-02-01T22:35:46.000+09:00
filebeat fails (hangs) on 8.0 due to `Elasticsearch is too old.` so updating to 8.1 as well as fixing up expectations around authentication, ssl, and information about options and where to find logs.
diff --git a/docs/devguide/contributing.asciidoc b/docs/devguide/contributing.asciidoc
@@ -83,7 +83,7 @@ and documentation. The primary command used for this is:
 --------------------------------------------------------------------------------
 make update
 --------------------------------------------------------------------------------
-Each Beat has its own `update` target, as well as a master `update` in the repository root. 
+Each Beat has its own `update` target, as well as a master `update` in the repository root.
 If a PR adds or removes a dependency, run `make update` in the root `beats` directory.
 
 Another command properly formats go source files and adds a copyright header:
diff --git a/docs/devguide/index.asciidoc b/docs/devguide/index.asciidoc
@@ -19,6 +19,8 @@ include::./pull-request-guidelines.asciidoc[]
 
 include::./contributing.asciidoc[]
 
+include::./testing.asciidoc[]
+
 include::{libbeat-dir}/communitybeats.asciidoc[]
 
 include::./fields-yml.asciidoc[]
@@ -36,5 +38,3 @@ include::./metricbeat-devguide.asciidoc[]
 include::./modules-dev-guide.asciidoc[]
 
 include::./migrate-dashboards.asciidoc[]
-
-
diff --git a/docs/devguide/modules-dev-guide.asciidoc b/docs/devguide/modules-dev-guide.asciidoc
@@ -485,8 +485,46 @@ run.
 In order to test the filesets with the sample logs and/or generate the expected output one should run the tests
 locally for a specific module, using the following procedure under Filebeat directory:
 
-. Run an Elasticsearch instance locally using docker: `docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.0.0-SNAPSHOT`
+. Start an Elasticsearch instance locally. For example, using Docker:
++
+[source,bash]
+----
+docker run \
+  --name elasticsearch \
+  -p 9200:9200 -p 9300:9300 \
+  -e "xpack.security.http.ssl.enabled=false"  -e "ELASTIC_PASSWORD=changeme" \
+  -e "discovery.type=single-node" \
+  --pull allways --rm --detach \
+  docker.elastic.co/elasticsearch/elasticsearch:master-SNAPSHOT
+----
+. Create an "admin" user on that Elasticsearch instance:
++
+[source,bash]
+----
+curl -u elastic:changeme \
+  http://localhost:9200/_security/user/admin \
+  -X POST -H 'Content-Type: application/json' \
+  -d '{"password": "changeme", "roles": ["superuser"]}'
+----
+. Create the testing binary: `make filebeat.test`
+. Update fields yaml: `make update`
 . Create python env: `make python-env`
 . Source python env: `source ./build/python-env/bin/activate`
-. Create the testing binary: `make filebeat.test`
-. Run the test, ie: `GENERATE=1 INTEGRATION_TESTS=1 BEAT_STRICT_PERMS=false TESTING_FILEBEAT_MODULES=nginx pytest tests/system/test_modules.py`
+. Run a test, for example to check nginx access log parsing:
++
+[source,bash]
+----
+INTEGRATION_TESTS=1 BEAT_STRICT_PERMS=false ES_PASS=changeme \
+TESTING_FILEBEAT_MODULES=nginx \
+pytest tests/system/test_modules.py -v --full-trace
+----
+. Add and remove option env vars as required. Here are some useful ones:
+* `TESTING_FILEBEAT_ALLOW_OLDER`: if set to 1, allow connecting older versions of Elasticsearch
+* `TESTING_FILEBEAT_MODULES`: comma separated list of modules to test.
+* `TESTING_FILEBEAT_FILESETS`: comma separated list of filesets to test.
+* `TESTING_FILEBEAT_FILEPATTERN`: glob pattern for log files within the fileset to test.
+* `GENERATE`: if set to 1, the expected documents will be generated.
+
+The filebeat logs are writen to the `build` directory. It may be useful to tail them in another terminal using `tail -F build/system-tests/run/test_modules.Test.*/output.log`.
+
+For example if there's a syntax error in an ingest pipeline, the test will probably just hang. The filebeat log output will contain the error message from elasticsearch.
diff --git a/docs/devguide/new_protocol.asciidoc b/docs/devguide/new_protocol.asciidoc
@@ -5,7 +5,7 @@ The following topics describe how to add a new protocol to Packetbeat:
 
 * <<getting-ready-new-protocol>>
 * <<protocol-modules>>
-* <<testing>>
+* <<protocol-testing>>
 
 [[getting-ready-new-protocol]]
 === Getting Ready
@@ -95,7 +95,7 @@ We are working on updating this section. While you're waiting for updates, you
 might want to try out the TCP protocol generator at
 https://github.com/elastic/beats/tree/master/packetbeat/scripts/tcp-protocol.
 
-[[testing]]
+[[protocol-testing]]
 === Testing
 
-We are working on updating this section. 
+We are working on updating this section.
diff --git a/docs/devguide/testing.asciidoc b/docs/devguide/testing.asciidoc
@@ -34,6 +34,8 @@ To run the tests without the services running locally, the command `make system-
 
 All Python tests are under `tests/system` directory.
 
+Filebeat's module python tests have additional documentation found in the <<filebeat-modules-devguide,Filebeat module>> guide.
+
 ==== Test commands
 
 This is a quick summary of the available test commands:
