chg: added doc generation pipeline (#17)
This commit is contained in:
Natalia Maximo
GitHub
Родитель
6f0838c8ad
Коммит
42b8335c93
|
|
@ -97,17 +97,6 @@ jobs:
|
|||
- name: Pull tags from the repo
|
||||
run: git pull --tags
|
||||
|
||||
- name: Generate full changelog
|
||||
run: gitchangelog | sed "s/(unreleased)/$(cat VERSION) ($(date +"%Y-%m-%d"))/" > CHANGELOG.md
|
||||
|
||||
- name: Make commit for auto-generated changelog
|
||||
uses: EndBug/add-and-commit@v4
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
add: 'CHANGELOG.md'
|
||||
message: '!gitchangelog'
|
||||
|
||||
- name: Generate version changelog for release
|
||||
run: gitchangelog $previous_tag..HEAD | sed "s/## (unreleased)/Quilla v$(cat VERSION) ($(date +"%Y-%m-%d"))/" > version_changelog.md
|
||||
|
||||
|
|
@ -121,3 +110,94 @@ jobs:
|
|||
|
||||
- name: Release package
|
||||
run: twine upload dist/*
|
||||
|
||||
changelog-result:
|
||||
needs: release
|
||||
runs-on: ubuntu-latest
|
||||
name: Generating Changelog
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
- name: Create new branch
|
||||
run: git checkout -b actions/changelog-$(cat VERSION)
|
||||
|
||||
- name: Setup python
|
||||
uses: actions/setup-python@v2
|
||||
with:
|
||||
python-version: '3.8'
|
||||
|
||||
- name: Generate newest changelog
|
||||
run: gitchangelog $(cat VERSION) > CHANGELOG.md
|
||||
|
||||
- name: Make commit for auto-generated changelog
|
||||
uses: EndBug/add-and-commit@v4
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
add: 'CHANGELOG.md'
|
||||
message: '!gitchangelog'
|
||||
|
||||
- name: Create pull request for the auto generated changelog
|
||||
run: |
|
||||
echo "PR_URL=$(gh pr create \
|
||||
--title "Auto-generated changelog for release $(cat VERSION)" \
|
||||
--body "This is an auto-generated PR" \
|
||||
--reviewer microsoft/quilla-admin \
|
||||
--label documentation)" >> $GITHUB_ENV
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Set pull request to auto-merge as rebase
|
||||
run: |
|
||||
gh pr merge $PR_URL \
|
||||
--auto \
|
||||
--delete-branch \
|
||||
--rebase
|
||||
|
||||
|
||||
|
||||
|
||||
docs-build:
|
||||
needs: release
|
||||
runs-on: ubuntu-latest
|
||||
name: Build the docs artifact
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Setup python
|
||||
uses: actions/setup-python@v2
|
||||
with:
|
||||
python-version: '3.8'
|
||||
|
||||
- name: Install docs packages
|
||||
run: pip install -e .[docs]
|
||||
|
||||
- name: Build documentation
|
||||
run: DOC_TARGETS=html make docs
|
||||
|
||||
- name: Export docs as an artifact
|
||||
uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: html_docs
|
||||
path: ./docs/_build/html
|
||||
|
||||
docs-release:
|
||||
needs: docs-build
|
||||
runs-on: ubuntu-latest
|
||||
name: Publish the new documentation
|
||||
steps:
|
||||
- uses: actions/checkout
|
||||
with:
|
||||
ref: gh-pages
|
||||
- name: Download the doc artifact
|
||||
uses: actions/download-artifact@v2
|
||||
with:
|
||||
name: html_docs
|
||||
path: ./docs
|
||||
|
||||
- name: Release gh-pages
|
||||
uses: EndBug/add-and-commit@v4
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
add: '.'
|
||||
message: 'chg: updated documentation after release'
|
||||
|
|
|
|||
21
CHANGELOG.md
21
CHANGELOG.md
|
|
@ -1,4 +1,23 @@
|
|||
# Changelog
|
||||
## 0.2 (2021-06-29)
|
||||
|
||||
### New
|
||||
|
||||
* Added release pipeline workflow file (#15) [Natalia Maximo]
|
||||
|
||||
* Added pytest-quilla documentation (#11) [Natalia Maximo]
|
||||
|
||||
* Added test pipeline workflow file (#9) [Natalia Maximo]
|
||||
|
||||
* Added code analysis workflow file. [Natalia Maximo]
|
||||
|
||||
* Initial migration from ADO. [Natalia Maximo]
|
||||
|
||||
### Other
|
||||
|
||||
* Updated SUPPORT.md and setup file (#13) [Natalia Maximo]
|
||||
|
||||
* Update README.md. [Natalia Maximo]
|
||||
|
||||
|
||||
## 0.1 (2021-06-28)
|
||||
|
||||
|
|
|
|||
30
README.md
30
README.md
|
|
@ -1,5 +1,15 @@
|
|||
# Quilla
|
||||
|
||||
[](https://github.com/microsoft/quilla/actions/workflows/codeql-analysis.yml)
|
||||
[](https://github.com/microsoft/quilla/actions/workflows/test-pipeline.yml)
|
||||
[](https://github.com/microsoft/quilla/actions/workflows/release-pipeline.yml)
|
||||
[](https://microsoft.github.io/quilla)
|
||||
|
||||
[](https://github.com/microsoft/quilla/blob/main/LICENSE)
|
||||
[](https://pypi.org/project/quilla/)
|
||||
[](https://github.com/microsoft/quilla)
|
||||
[](https://pypi.org/project/quilla/)
|
||||
|
||||
<!-- THIS SECTION SHOULD BE COPY+PASTED INTO THE docs/intro.md FILE -->
|
||||
## Declarative UI Testing with JSON
|
||||
|
||||
|
|
@ -11,10 +21,9 @@ Check out the [features](docs/features.md) docs for an overview of all quilla ca
|
|||
|
||||
## Quickstart
|
||||
|
||||
1. Clone the repository
|
||||
2. `cd` into the `quilla` directory and run `make install`
|
||||
3. Ensure that you have the correct browser and drivers. Quilla will autodetect drivers that are in your PATH or in the directory it is called
|
||||
4. Write the following as `Validation.json`, substituting "Edge" for whatever browser you have installed and have the driver for:
|
||||
1. Run `pip install quilla`
|
||||
1. Ensure that you have the correct browser and drivers. Quilla will autodetect drivers that are in your PATH or in the directory it is called
|
||||
1. Write the following as `Validation.json`, substituting "Edge" for whatever browser you have installed and have the driver for:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -31,21 +40,23 @@ Check out the [features](docs/features.md) docs for an overview of all quilla ca
|
|||
}
|
||||
```
|
||||
|
||||
5. Run `quilla -f Validation.json`
|
||||
1. Run `quilla -f Validation.json`
|
||||
|
||||
## Installation
|
||||
|
||||
> Note: It is **highly recommended** that you use a virtual environment whenever you install new python packages.
|
||||
You can install Quilla by cloning the repository and running `make install`.
|
||||
|
||||
For more information on installation options and packaging Quilla for remote install, check out the documentation for it [here](docs/install.md)
|
||||
Quilla is available on [PyPI](https://pypi.org/project/quilla/), and can be installed by running `pip install quilla`.
|
||||
|
||||
For more information on installation options (such as installing from source) and packaging Quilla for remote install, check out the documentation for it [here](docs/install.md)
|
||||
|
||||
## Usage
|
||||
|
||||
This module can be used both as a library, a runnable module, as well as as a command-line tool. The output of `quilla --help` is presented below:
|
||||
|
||||
```text
|
||||
usage: quilla [-h] [-f] [-d] [--driver-dir DRIVERS_PATH] [-P] json
|
||||
usage: quilla [-h] [-f] [--debug] [--driver-dir DRIVERS_PATH] [-P] [--no-sandbox] [-d file] json
|
||||
|
||||
Program to provide a report of UI validations given a json representation of the validations or given the filename
|
||||
containing a json document describing the validations
|
||||
|
|
@ -56,10 +67,13 @@ positional arguments:
|
|||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
-f, --file Whether to treat the argument as raw json or as a file
|
||||
-d, --debug Enable debug mode
|
||||
--debug Enable debug mode
|
||||
--driver-dir DRIVERS_PATH
|
||||
The directory where browser drivers are stored
|
||||
-P, --pretty Set this flag to have the output be pretty-printed
|
||||
--no-sandbox Adds '--no-sandbox' to the Chrome and Edge browsers. Useful for running in docker containers'
|
||||
-d file, --definitions file
|
||||
A file with definitions for the 'Definitions' context object
|
||||
```
|
||||
|
||||
## Writing Validation Files
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
0.2
|
||||
0.2.1
|
||||
|
|
|
|||
|
|
@ -30,6 +30,7 @@ author = 'Natalia Maximo'
|
|||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.napoleon',
|
||||
'sphinx.ext.githubpages',
|
||||
'sphinx_autodoc_typehints',
|
||||
'myst_parser',
|
||||
'sphinx_argparse_cli',
|
||||
|
|
|
|||
|
|
@ -4,20 +4,41 @@
|
|||
|
||||
Quilla was designed to work with Python 3.8+, and currently includes syntax that will cause errors in Python 3.7. Make sure you are using the correct version of python
|
||||
|
||||
## Installing Quilla
|
||||
## Installing Quilla with pip
|
||||
|
||||
<!-- TODO: Update docs if it gets deployed to PyPI to reflect easy installation with `pip` -->
|
||||
> Note: A virtual environment is recommended. Python ships with `venv`, though other alternatives such as using `conda` or `virtualenvwrapper` are just as useful
|
||||
|
||||
Install Quilla by using `pip install quilla`.
|
||||
|
||||
The `pytest-quilla` plugin is also installed when installing quilla, though `pytest` is not. It is not necessary to install Pytest to run Quilla on its own. To download Pytest alongside Quilla, run `pip install quilla[pytest]` or `pip install pytest quilla` to install them separately.
|
||||
|
||||
## Installing Quilla from source
|
||||
|
||||
> Note: A virtual environment is recommended. Python ships with `venv`, though other alternatives such as using `conda` or `virtualenvwrapper` are just as useful
|
||||
|
||||
Download (or clone) the repository, and run `make install` to install Quilla. This will also expose the Quilla plugin to Pytest (if installed), though it will remain disabled until your pytest configuration file has the `use-quilla` option set to `True`. This does not cause any issues if Pytest is not installed, however, since it only registers the entrypoint.
|
||||
|
||||
## Packaging the Python Code
|
||||
## Installing Quilla from wheel files
|
||||
|
||||
Packaging Quilla requires the `setuptools`, `pip`, and `wheel` packages. These should come default with every installation of Python, but if something seems to be going wrong make sure to check if they are installed.
|
||||
It is occasionally necessary to install software in machines that either are not currently connected to the internet, or that cannot be connected to the internet. In these cases, it is still possible to install Quilla, although some setup will be required.
|
||||
|
||||
The preferred method of packaging Quilla is by using the `make` commands that come bundled with the project. Use `make package` to create (by default) the source and wheel distributions of Quilla, and use `make package-deps` to create a Quilla `.whl` file and all the `.whl` files required by Quilla as dependencies.
|
||||
### Use pip to create the required wheel files
|
||||
|
||||
## Customizing install & build
|
||||
From a machine that can connect to PyPI, run `pip wheel quilla`, which will download all the `.whl` files from PyPI required to install Quilla. This will include all the dependencies listed in `setup.py`, but none of the extras. Move the `.whl` files to the target machine, and run `pip install ./*.whl` to install them.
|
||||
|
||||
### Package Quilla from source
|
||||
|
||||
> Packaging Quilla requires the `setuptools`, `pip`, and `wheel` packages. These should come default with every installation of Python, but if something seems to be going wrong make sure to check if they are installed.
|
||||
|
||||
Quilla comes bundled with a convenience Makefile that has multiple commands to make managing it simpler. For creating the `.whl` files from source, do the following:
|
||||
|
||||
1. Clone the repository
|
||||
1. Run `make package-deps` to generate `.whl` files
|
||||
> Note: While this will generate a `.whl` from source for Quilla, it will still download the dependency `.whl` files from the package repository
|
||||
|
||||
1. Collect all files from the `dist/` folder (or whatever target folder you have decided) and move them to the target machine
|
||||
1. Run `pip install ./*.whl`
|
||||
|
||||
## Customizing source install & build
|
||||
|
||||
The `Makefile` provided with Quilla uses several environment variables to configure its install and build process. All the available options are defined in the [makefile vars](makefile_vars.md) docs, including explanations on how they are used.
|
||||
|
|
|
|||
|
|
@ -130,7 +130,7 @@ setup(
|
|||
version='0.1',
|
||||
packages=find_packages(),
|
||||
entry_points={
|
||||
'quillaPlugins': ['quilla-headless = headless.cli_configs']
|
||||
'QuillaPlugins': ['quilla-headless = headless.cli_configs']
|
||||
}
|
||||
)
|
||||
```
|
||||
|
|
@ -199,7 +199,7 @@ object, which will give us some basic information on the state of the current dr
|
|||
}
|
||||
```
|
||||
|
||||
5. Run `UIValidation -f Validation.json --pretty`. You should receive the following output:
|
||||
5. Run `quilla -f Validation.json --pretty`. You should receive the following output:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
|
|||
|
|
@ -4,10 +4,12 @@ This document has been written to be used by a multitude of individuals who inte
|
|||
|
||||
For all who are unfamiliar with the concept of XPaths, make sure to brush up on what they are. The W3C Schools website has a good section on them [here](https://www.w3schools.com/XML/xml_xpath.asp)
|
||||
|
||||
If you are a test writer looking for basic information on how to write a test, start by reading the section on [writing validation files](validation_files.md). This should give you the basics of how to write Quilla tests, including a couple of examples. Then, should you want to extend your tests using non-static information, such as getting data from the environment variables or from a definition file, read the section on [context expressions and context objects](context_expressions.md). Should you decide you need more extensible configuration or you need to get data from custom sources for your validations (i.e. accessing a secret store), checkout the section on [writing plugins](plugins.md). Finally, if you are seeking to integrate Quilla tests with Pytest, read the section on [the pytest-quilla integration](quilla_pytest.md) which will cover how to enable running Quilla as part of pytest.
|
||||
Test writers looking for basic information on how to write a test should start by reading the section on [writing validation files](validation_files.md). This covers the basics of how to write Quilla tests, including a couple of examples. Then, to extend tests using non-static information (such as getting data from the environment variables or from a definition file), test writers should read the section on [context expressions and context objects](context_expressions.md). If more extensible configuration or custom data sources (i.e. accessing a secret store) is needed, the section on [writing plugins](plugins.md) covers examples on how to write local plugins. For testing teams who are seeking to integrate Quilla tests with Pytest, the section on [the pytest-quilla integration](quilla_pytest.md) will cover how to enable running Quilla as part of pytest.
|
||||
|
||||
If you are a web developer looking to maintain a definition file (or multiple definition files) for a QA team to write tests with, check out the section on [context expressions and context objects](context_expressions.md), specifically the subsection on the `Definitions` context object.
|
||||
Web developer looking to maintain a definition file (or multiple definition files) for a QA team to write tests with should read the section on [context expressions and context objects](context_expressions.md), specifically the subsection on the `Definitions` context object.
|
||||
|
||||
If you are a plugin creator, make sure you're familiar with [context expressions and context objects](context_expressions.md) first, since they are a key aspect of exposing new functionality for test writers. Then, check out the section on [how to write plugins](plugins.md) to get an understanding of how plugins work in Quilla and how to publish one so that Quilla will auto-detect it. Finally, use the [hooks](hooks.rst) reference to see what plugin hooks are available to you, when they are called, and what data is exposed to you through them.
|
||||
Plugin creator, should be familiar with [context expressions and context objects](context_expressions.md) first, since they are a key aspect of exposing new functionality for test writers. Then, the material covered in the section on [how to write plugins](plugins.md) explains how plugins work in Quilla and how to publish one so that Quilla will auto-detect it. For quick reference, the [hooks](hooks.rst) section is available for an overview on available hooks, when they are called, and what data is exposed.
|
||||
|
||||
If you are a code maintainer or are looking to make a contribution to the code, first make sure you have a good understanding of [how quilla works](how_it_works.md), how to [write validation files](validation_files.md) and how to [use context objects](context_expressions.md) so that you understand the general structure of the data that Quilla processes. Then, read up on how [plugins work](plugins.md) and which [plugin hooks are exposed](hooks.rst). For information regarding the packaging & installation process, read the section in the [installation instructions](install.md) on how to package. For information on the documentation style, dependencies, and how to build the docs, check out the [documentation section](README.md). Finally, for information on how to customize the make commands using various environment variables, read the [makefile variable documentation](makefile_vars.md)
|
||||
Code maintainer or those looking to make a contribution to the code, should first have a good understanding of [how quilla works](how_it_works.md), how to [write validation files](validation_files.md) and how to [use context objects](context_expressions.md) to understand the general structure of the data that Quilla processes. In addition, the section on [how plugins work](plugins.md) and [which plugin hooks are exposed](hooks.rst) will cover necessary plugin-related information.
|
||||
|
||||
For ease of maintenance, the [documentation section](README.md) covers what dependencies are used to build the documentation, how to build the documentation, and the documentation style. Finally, the [makefile variable documentatio](makefile_vars.md) has additional information on how to customize the make commands using various environment variables.
|
||||
|
|
|
|||
|
|
@ -150,14 +150,14 @@ Example written in 2021-06-16
|
|||
}
|
||||
```
|
||||
|
||||
## Signing In to Github
|
||||
### Signing In to Github
|
||||
|
||||
Example written on 2021-06-24
|
||||
|
||||
```json
|
||||
{
|
||||
"definitions": {
|
||||
"Username": "validation-example-user",
|
||||
"Username": "${{ Environment.GITHUB_EXAMPLE_USER_USERNAME }}",
|
||||
"Password": "${{ Environment.GITHUB_EXAMPLE_USER_PASSWORD }}",
|
||||
"WelcomePage": {
|
||||
"SignInButton": "//div[@class='position-relative mr-3']/a"
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче