Skip to content

Commit

Permalink
docs(markdown): migrate docs from rst to md (#422)
Browse files Browse the repository at this point in the history
Migrated docs from `readthedocs.io` to `github.io`.

---------

Co-authored-by: Artem Rys <[email protected]>
  • Loading branch information
hetangmodi-crest and artemrys authored May 21, 2024
1 parent c70b4bf commit 39ccda1
Show file tree
Hide file tree
Showing 90 changed files with 665 additions and 1,473 deletions.
29 changes: 29 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: docs
on:
push:
branches:
- main
pull_request:
branches:
- main

jobs:
docs:
runs-on: ubuntu-latest
permissions:
contents: write
pages: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: 3.8
- run: |
curl -sSL https://install.python-poetry.org | python3 - --version 1.5.1
pip install mkdocs mkdocs-material mkdocstrings-python
- name: Deploy to GitHub Pages
if: github.ref_name == 'main'
run: mkdocs gh-deploy --force --strict
- name: Build Docs
if: github.ref_name != 'main'
run: mkdocs build --strict
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,9 @@ celerybeat.pid

# Environments
.env
.venv
# ignore all venv with different Py versions
.venv*
env/
venv/
ENV/
env.bak/
venv.bak/
Expand Down
17 changes: 0 additions & 17 deletions .readthedocs.yml

This file was deleted.

79 changes: 7 additions & 72 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,77 +1,12 @@
# SmartX
# addon-factory-smartx-ui-test-library

UCC based Add-on UI automation framework
![PyPI](https://img.shields.io/pypi/v/pytest-splunk-addon-ui-smartx)
![Python](https://img.shields.io/pypi/pyversions/pytest-splunk-addon-ui-smartx.svg)

Confluence Page link: https://confluence.splunk.com/display/PROD/SmartX+UI+Automation+Framework+for+Ucc+based+Add-ons
## What is SmartX UI Test Framework

ReadTheDocs Page link: https://addon-factory-smartx-ui-test-library.readthedocs.io
This framework is wrapper on selenium to write UI test cases for Splunk Add-ons.

## Table of contents
## Usage

- [Goal](#goal)
- [Design](#design)
- [Features](#features)
- [Build test cases using the framework](#build-test-cases-using-the-framework)
- [Steps to test in Local environment](#steps-to-test-in-local-environment)
- [Steps to test with Saucelabs](#steps-to-test-with-saucelabs)

### Goal

To test all the UI configuration page of the Splunk add-ons. All the add-ons are built with the same template. The configuration pages consist of an Input page and a configuration page that has different tabs to configure logging, proxy settings and add product account in the add-ons. To support the testing of all the add-ons, a generic framework should be made, which can be used in the test cases for all the add-ons. The framework should have methods that can interact with UI components and test the working of UI.

### Design

For UI development, we follow a practice in which we create a set of components first. The component has its own state-cycle. The component will be reusable so that it can be placed on any page. A web-page will be a composition of these components placed in the proper container.

The testing framework will follow the same practice. It will have classes for all the components used in all the pages. These “Component” class will consist of methods to interact with the component, to get & set values in the component. These components will be put on different pages. The structure is created so that it can easily be maintained and understandable. As per design, the class “Page” should only be used to contain a set of components. No interaction methods should be in the Page class.

The structure of the framework can be divided into 3 parts.

Components : A UI component with which a user interacts with.
Pages : Holds multiple components of a specific page
Test cases : Tests the interaction & values in the components

### Features

- pytest fixture to control when the browser should be initialized & tear-downed.
- Flag to easily convert the environment from SauceLabs to local for debugging purposes.
- Screenshot when any test case fails.
- An Html report containing the trace-back and the screenshots of the failed test cases.
- Being able to read environment variables to dynamically change the URL and the credentials of a test page.
- Backend configuration that can be fetched from the management API of the Splunk instance.
- Reruns, the test cases will be rerunning to avoid some rare timeout/network issues


### Build test cases using the framework

1. Create the appropriate folders and pytest files within the TA's test/ui directory
2. Create Add-on specific Page classes (we only need to specify which components it contains, demo: server_page)
3. Implement the test-cases by using the page classes & its components
4. Jenkins integrations

Demo link : https://git.splunk.com/projects/SOLN/repos/ta-microsoft-scom/browse/test/ui

### Steps to test in Local environment

1. Install SmartX by using 'pip install pytest-splunk-addon-ui-smartx' or cloning this repository and running 'poetry install'
2. Download Browser's specific driver
For Chrome: download chromedriver
For Firefox: download geckodriver
For IE: download IEdriverserver
3. Put the downloaded driver into test/ui/ directory, make sure that it is within the environment's PATH variable, and that it is executable
4. For Internet explorer, The steps mentioned at below link must be performed:
https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration
5. Execute the test cases:
```script
pytest -vv --browser={browser} --local --splunk-host={web_url} --splunk-port={mgmt_url} --splunk-user {username} --splunk-password {password}
```
### Steps to test with Saucelabs

1. Install SmartX by using 'pip install pytest-splunk-addon-ui-smartx' or cloning this repository and running 'poetry install'
2. Configure saucelabs credentials as environment variables
SAUCE_USERNAME : <saucelabs_username>
SAUCE_PASSWORD : <saucelabs_access_key>
3. Execute the test case
```script
pytest -vv --browser={browser} --splunk-host={web_url} --splunk-port={mgmt_url} --setup-retry-count={retry-count} --splunk-user {username} --splunk-password {password}
```
For full usage instructions, please visit the [documentation](https://splunk.github.io/addon-factory-smartx-ui-test-library).
20 changes: 0 additions & 20 deletions docs/Makefile

This file was deleted.

15 changes: 0 additions & 15 deletions docs/api_reference.rst

This file was deleted.

3 changes: 3 additions & 0 deletions docs/api_reference/backend_confs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# backend_confs

::: pytest_splunk_addon_ui_smartx.backend_confs
3 changes: 3 additions & 0 deletions docs/api_reference/base_test.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# base_test

::: pytest_splunk_addon_ui_smartx.base_test
3 changes: 3 additions & 0 deletions docs/api_reference/components/base_component.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# base_component

::: pytest_splunk_addon_ui_smartx.components.base_component
3 changes: 3 additions & 0 deletions docs/api_reference/components/conf_table.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# conf_table

::: pytest_splunk_addon_ui_smartx.components.conf_table
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/base_control.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# base_control

::: pytest_splunk_addon_ui_smartx.components.controls.base_control
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/button.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# button

::: pytest_splunk_addon_ui_smartx.components.controls.button
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/checkbox.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# checkbox

::: pytest_splunk_addon_ui_smartx.components.controls.checkbox
14 changes: 14 additions & 0 deletions docs/api_reference/components/controls/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# controls

The following is the API Reference for SmartX Controls:

+ [base_control](base_control.md)
+ [button](button.md)
+ [checkbox](checkbox.md)
+ [learn_more](learn_more.md)
+ [message](message.md)
+ [multi_select](multi_select.md)
+ [oauth_select](oauth_select.md)
+ [single_select](single_select.md)
+ [textbox](textbox.md)
+ [toggle](toggle.md)
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/learn_more.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# learn_more

::: pytest_splunk_addon_ui_smartx.components.controls.learn_more
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/message.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# message

::: pytest_splunk_addon_ui_smartx.components.controls.message
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/multi_select.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# multi_select

::: pytest_splunk_addon_ui_smartx.components.controls.multi_select
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/oauth_select.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# oauth_select

::: pytest_splunk_addon_ui_smartx.components.controls.oauth_select
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/single_select.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# single_select

::: pytest_splunk_addon_ui_smartx.components.controls.single_select
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/textbox.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# textbox

::: pytest_splunk_addon_ui_smartx.components.controls.textbox
3 changes: 3 additions & 0 deletions docs/api_reference/components/controls/toggle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# toggle

::: pytest_splunk_addon_ui_smartx.components.controls.toggle
3 changes: 3 additions & 0 deletions docs/api_reference/components/dropdown.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# dropdown

::: pytest_splunk_addon_ui_smartx.components.dropdown
3 changes: 3 additions & 0 deletions docs/api_reference/components/entity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# entity

::: pytest_splunk_addon_ui_smartx.components.entity
12 changes: 12 additions & 0 deletions docs/api_reference/components/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# components

The following is the API Reference for SmartX Components:

+ [base_component](base_component.md)
+ [conf_table](conf_table.md)
+ [dropdown](dropdown.md)
+ [entity](entity.md)
+ [input_table](input_table.md)
+ [login](login.md)
+ [table](table.md)
+ [tabs](tabs.md)
3 changes: 3 additions & 0 deletions docs/api_reference/components/input_table.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# input_table

::: pytest_splunk_addon_ui_smartx.components.input_table
3 changes: 3 additions & 0 deletions docs/api_reference/components/login.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# login

::: pytest_splunk_addon_ui_smartx.components.login
3 changes: 3 additions & 0 deletions docs/api_reference/components/table.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# table

::: pytest_splunk_addon_ui_smartx.components.table
3 changes: 3 additions & 0 deletions docs/api_reference/components/tabs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# tabs

::: pytest_splunk_addon_ui_smartx.components.tabs
31 changes: 31 additions & 0 deletions docs/api_reference/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
The following is the API Reference for SmartX:

- [backend_conf](backend_confs.md)
- [base_test](base_test.md)
- [plugin](plugin.md)
- [utils](utils.md)
- [pages](pages/index.md)
+ [logging](pages/logging.md)
+ [login](pages/login.md)
+ [page](pages/page.md)
+ [proxy](pages/proxy.md)
- [components](components/index.md)
+ [base_component](components/base_component.md)
+ [conf_table](components/conf_table.md)
+ [dropdown](components/dropdown.md)
+ [entity](components/entity.md)
+ [input_table](components/input_table.md)
+ [login](components/login.md)
+ [table](components/table.md)
+ [tabs](components/tabs.md)
- [controls](components/controls/index.md)
+ [base_control](components/controls/base_control.md)
+ [button](components/controls/button.md)
+ [checkbox](components/controls/checkbox.md)
+ [learn_more](components/controls/learn_more.md)
+ [message](components/controls/message.md)
+ [multi_select](components/controls/multi_select.md)
+ [oauth_select](components/controls/oauth_select.md)
+ [single_select](components/controls/single_select.md)
+ [textbox](components/controls/textbox.md)
+ [toggle](components/controls/toggle.md)
8 changes: 8 additions & 0 deletions docs/api_reference/pages/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# pages

The following is the API Reference for SmartX Pages:

+ [logging](logging.md)
+ [login](login.md)
+ [page](page.md)
+ [proxy](proxy.md)
3 changes: 3 additions & 0 deletions docs/api_reference/pages/logging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# logging

::: pytest_splunk_addon_ui_smartx.pages.logging
3 changes: 3 additions & 0 deletions docs/api_reference/pages/login.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# login

::: pytest_splunk_addon_ui_smartx.pages.login
3 changes: 3 additions & 0 deletions docs/api_reference/pages/page.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# page

::: pytest_splunk_addon_ui_smartx.pages.page
3 changes: 3 additions & 0 deletions docs/api_reference/pages/proxy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# proxy

::: pytest_splunk_addon_ui_smartx.pages.proxy
3 changes: 3 additions & 0 deletions docs/api_reference/plugin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# plugin

::: pytest_splunk_addon_ui_smartx.plugin
3 changes: 3 additions & 0 deletions docs/api_reference/utils.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# utils

::: pytest_splunk_addon_ui_smartx.utils
6 changes: 0 additions & 6 deletions docs/backend_confs.rst

This file was deleted.

6 changes: 0 additions & 6 deletions docs/base_test.rst

This file was deleted.

6 changes: 0 additions & 6 deletions docs/components/base_component.rst

This file was deleted.

6 changes: 0 additions & 6 deletions docs/components/conf_table.rst

This file was deleted.

6 changes: 0 additions & 6 deletions docs/components/controls/base_control.rst

This file was deleted.

Loading

0 comments on commit 39ccda1

Please sign in to comment.