diff --git a/docs/devguide/contributing.asciidoc b/docs/devguide/contributing.asciidoc index 435eb10416b..ae9e4a1ee8e 100644 --- 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 index 6810240121c..2f9af959ce1 100644 --- 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 index 03b3179c596..ee264b15741 100644 --- 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 index c653ff86316..defd50c0bc3 100644 --- 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]] === 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 index 75a476d5c5a..4f8a138beb3 100644 --- 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 <> guide. + ==== Test commands This is a quick summary of the available test commands: