diff --git a/docs/how_to_use.md b/docs/how_to_use.md
index 5c0db16ec..94b05a4a2 100644
--- a/docs/how_to_use.md
+++ b/docs/how_to_use.md
@@ -1,7 +1,7 @@
# How To Use
-Create a test file in the tests folder
+1. Create a test file in the tests folder
```python
from pytest_splunk_addon.standard_lib.addon_basic import Basic
@@ -10,6 +10,10 @@ class Test_App(Basic):
pass
```
+2. Create sample files and pytest-splunk-addon-data.conf
+
+- For detailed information on how to create samples and pytest-splunk-addon-data.conf, please refer [here](./sample_generator.md).
+
## Test Execution
There are three ways to execute the tests:
@@ -34,7 +38,6 @@ There are three ways to execute the tests:
ARG SPLUNK_APP_ID=TA_UNKNOWN
ARG SPLUNK_APP_PACKAGE=$SPLUNK_APP_PACKAGE
RUN echo Splunk VERSION=$SPLUNK_VERSION
- COPY deps/apps /opt/splunk/etc/apps/
COPY $SPLUNK_APP_PACKAGE /opt/splunk/etc/apps/$SPLUNK_APP_ID
```
@@ -438,6 +441,6 @@ def splunk_setup(splunk):
How can this be achieved :
- - Make json representation of the data models, which satisfies this [DataModelSchema](https://github.com/splunk/pytest-splunk-addon/blob/main/pytest_splunk_addon/standard_lib/cim_tests/DatamodelSchema.json).
+ - Make json representation of the data models, which satisfies this [DataModelSchema](https://github.com/splunk/pytest-splunk-addon/blob/main/pytest_splunk_addon/cim_tests/DatamodelSchema.json).
- Provide the path to the directory having all the data models by adding `--splunk_dm_path path_to_dir` to the pytest command
- - The test cases will now be generated for the data models provided to the plugin and not for the [default data models](https://github.com/splunk/pytest-splunk-addon/tree/main/pytest_splunk_addon/standard_lib/data_models).
+ - The test cases will now be generated for the data models provided to the plugin and not for the [default data models](https://github.com/splunk/pytest-splunk-addon/tree/main/pytest_splunk_addon/data_models).
diff --git a/docs/sample_generator.md b/docs/sample_generator.md
index ba3d48ce0..e892da339 100644
--- a/docs/sample_generator.md
+++ b/docs/sample_generator.md
@@ -5,6 +5,90 @@ The sample generation & ingestion takes place before executing the testcases.
For index-time test cases, there are multiple metadata required about the sample file for which `pytest-splunk-addon-data.conf` must be created and provided to the pytest command.
+## Generate sample files
+Pytest splunk addon supports 2 different formats of sample files
+
+**1. Text format**
+
+- Sample events can be generated from the live events by replacing the field values with the tokens. Token name should be enclosed with ##.
+- Token replacement setting for this samples should be added to pytest-splunk-addon-data.conf to generate events
+- For example,
+ ```
+ Example live event:
+ <111> 2020-02-12T03:27:09+10:00 10.0.0.3 RT_FLOW: RT_FLOW_SESSION_CREATE: action=allowed transport=ICMP dest=10.0.0.1 dest_ip=10.0.0.1 dest_port=5048 dest_zone=DUMMY_ZONE app=app1
+
+ Sample created from live event:
+ <111> ##timestamp_token## ##src_ip_token## RT_FLOW: RT_FLOW_SESSION_CREATE: action=##action_token## transport=##transport_type_token## dest=##dest_ip_token## dest_ip=##dest_ip_token## dest_port=##dest_port_token## dest_zone=##dest_zone_token## app=##app_token##
+ ```
+
+**2. XML format**
+
+- Generate sample xml file using the format provided [here](https://github.com/splunk/pytest-splunk-addon/blob/main/pytest_splunk_addon/sample_generation/schema.xsd)
+- Using xml format for the sample events, user can also execute requirement tests for the event for fields mentioned in the cim_fields and other_mappings
+- For example,
+
+```
+Example live event:
+<111> 2020-02-12T03:27:09+10:00 10.0.0.3 RT_FLOW: RT_FLOW_SESSION_CREATE: action=allowed transport=ICMP dest=10.0.0.1 dest_ip=10.0.0.1 dest_port=5048 dest_zone=DUMMY_ZONE app=app1
+```
+
+
+Sample xml created from live event:
+```xml
+
+
+ Test
+ Test product
+
+
+
+
+
+
+
+ 2020-02-12T03:27:09+10:00 10.0.0.3 RT_FLOW: RT_FLOW_SESSION_CREATE: action=allowed transport=ICMP dest=10.0.0.1 dest_ip=10.0.0.1 dest_port=5048 dest_zone=DUMMY_ZONE app=app1]]>
+
+
+
+ Network Traffic
+
+
+
+
+
+
+
+
+
+
+
+ bytes
+ bytes_in
+ bytes_out
+ dvc
+ rule
+ session_id
+ src
+ src_ip
+ src_port
+ src_zone
+ src_interface
+ user
+ protocol
+ vendor_product
+
+
+
+
+
+
+
+
+
+
+```
+
+
## pytest-splunk-addon-data.conf.spec
**Default Values**:
@@ -18,6 +102,7 @@ sourcetype = pytest-splunk-addon
source = pytest-splunk-addon:{{input_type}}
sourcetype_to_search = {{sourcetype}}
sample_count = 1
+requirement_test_sample = 1
timestamp_type = event
count = 0
earliest = now
@@ -78,6 +163,11 @@ host_prefix = {{host_prefix}}
- This parameter will be used to calculate the total number of events which will be generated from the sample file.
- If `input_type = modinput`, do not provide this parameter.
+**requirement_test_sample = 1**
+
+- This parameter is used to run requirement tests for the provided sample xml file
+- only supported with the xml sample file
+
**expected_event_count = **
- The no. of events this sample stanza should generate.