Metadata-Version: 2.1
Name: robotkernel
Version: 1.0.2
Summary: A Jupyter kernel for interactive acceptance-test-driven development with the Robot Framework
Home-page: https://github.com/robots-from-jupyter/robotkernel
Author: Asko Soukka
Author-email: asko.soukka@iki.fi
License: BSD-3-Clause
Keywords: Interactive,Interpreter,Shell,Testing,Web
Platform: UNKNOWN
Classifier: Framework :: Jupyter
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Tool
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Dist: docutils
Requires-Dist: ipykernel
Requires-Dist: ipywidgets
Requires-Dist: lunr
Requires-Dist: nbformat
Requires-Dist: pillow
Requires-Dist: pygments
Requires-Dist: robotframework (>=3.1)

Robotkernel
===========

`Robot Framework`_ IPython_ kernel for `Jupyter Notebook`_ and JupyterLab_. Check a `video to see it in action`_.

Requires Python 3.6 or later with setuptools 40.5.0 later and Robot Framework
3.1 or later.

Log | Report -links on existing notebooks are only active on trusted notebooks.

.. _video to see it in action: https://youtu.be/uYGh9_c3b7s
.. _Robot Framework: http://robotframework.org/
.. _IPython: https://ipython.org/
.. _Jupyter Notebook: https://jupyter.readthedocs.io/en/latest/
.. _JupyterLab: https://jupyterlab.readthedocs.io/en/stable/


Try Robotkernel at Binder
-------------------------

Jupyter Notebook: https://mybinder.org/v2/gh/robots-from-jupyter/robotkernel/master?urlpath=tree/example.ipynb

JupyterLab: https://mybinder.org/v2/gh/robots-from-jupyter/robotkernel/master?urlpath=lab/tree/example.ipynb


Install Robotkernel
-------------------

.. code:: bash

   $ pip install robotkernel

For JupyterLab you should also install the companion syntax highlighting and Jupyter widgets support:

.. code:: bash

   $ jupyter labextension install jupyterlab_robotmode
   $ jupyter labextension install @jupyter-widgets/jupyterlab-manager

For some environments it might be required to run the following command to
manually register robotkernel as Jupyter kernel:

.. code:: bash

   $ python -m robotkernel.install


Install Robotkernel from Python 3 notebook
------------------------------------------

.. code:: bash

   !pip install robotkernel

After refreshing the notebook, it is possible change the kernel to Robot Framework kernel or create a new notebook with Robot Framework kernel.

For JupyterLab you should also install the companion syntax highlighting and Jupyter widgets support:

.. code:: bash

   !jupyter labextension install jupyterlab_robotmode
   !jupyter labextension install @jupyter-widgets/jupyterlab-manager


Export robot files
------------------

It is possible to export test suites direclty from Jupyter Notebook or JupyterLab user interface (into traditional ``.robot`` files), but also from command line:

.. code:: bash

   $ jupyter nbconvert --to script example.ipynb


Execute notebooks
-----------------

Robotkernel installs script named ``nbrobot``, which the Robot Frameworks test runner ``robot`` with support for executing Jupyter notebooks created with Robotkernel:

.. code:: bash

   $ nbrobot example.ipynb

In addition, it is also possible to execute notebooks as such, resulting into a new notebook with embedded execution logs and reports:

.. code:: bash

   $ jupyter nbconvert --to notebook --execute example.ipynb

This will stop the execution at first failing test case.

When execution with errors, to also get a result notebook with execution logs saved, an extra flag ``--ExecutePreprocessor.allow_errors=True`` must be set:

.. code:: bash

   $ jupyter nbconvert --ExecutePreprocessor.allow_errors=True --to notebook --execute example.ipynb

This `may change`__ in future versions of nbconvert.

__ https://github.com/jupyter/nbconvert/issues/626

Note that when executing a notebook, each cell with tests cases or tasks will be executed as its own suite. It might be more efficient to export notebook into a robot script and execute that with the traditional robot runner.


Local installation and development
----------------------------------

See also: http://jupyter.readthedocs.io/en/latest/install.html

Create and activate clean Python virtual environment::

    $ venv myenv
    $ source myenv/bin/activate

Install Jupyter::

    $ pip install --upgrade pip setuptools
    $ pip install jupyter

Clone this kernel::

    $ git clone https://github.com/robots-from-jupyter/robotkernel.git
    $ cd robotkernel

Install the kernel into virtualenv in develop mode::

    $ python setup.py develop

Launch the jupyter::

    $ jupyter notebook

Reloading the kernel reloads the code.


Nix-shell (https://nixos.org/nix/)
----------------------------------

This repository includes opinionated instructions for running and developing Robotkernel with Nix for Jupyter Notebook:

.. code:: bash

   $ nix-shell -E 'import (fetchTarball https://github.com/robots-from-jupyter/robotkernel/archive/master.tar.gz + "/shell.nix")' --run "jupyter notebook"

And for Jupyter Lab:

.. code:: bash

   $ nix-shell -E 'import (fetchTarball https://github.com/robots-from-jupyter/robotkernel/archive/master.tar.gz + "/shell.nix")'
   $ jupyter labextension install jupyterlab_robotmode --app-dir=.jupyterlab
   $ jupyter lab --app-dir=.jupyterlab
   $ exit

Add ``--arg sikuli true`` to include SikuliLibrary_.

Add ``--arg vim true`` to enable `vim bindings`_.

.. _SikuliLibrary: https://github.com/rainmanwy/robotframework-SikuliLibrary
.. _vim bindings: https://github.com/lambdalisue/jupyter-vim-binding

Development environment with Nix:

.. code:: bash

    $ git clone https://github.com/robots-from-jupyter/robotkernel.git
    $ cd robotkernel
    $ nix-build setup.nix -A env  # to generate ./result/bin/python for IDE
    $ nix-shell setup.nix -A develop

Changelog
=========

1.0.2 (2019-12-04)
------------------

- Fix issue where text strings feed to JSON displayed a warning
  [datakurre]
- Fix JupyterLab context help support to work when clicked in the middlle of a keyword
  [datakurre]
- Fix to close dangling Selenium connections
  [datakurre]

1.0.1 (2019-09-19)
------------------

- Fix issue where ${CURDIR} was broken on Windows, because it contained path without
  escaped path separators required by Robot Framework
  [datakurre]
- Fix issue where suite variable listener reported errors when running robot suites,
  because it tried to restore dictionary variables with empty value
  [datakurre]

1.0 (2019-09-12)
----------------

- Fix issue where log and report links did not open on JupyterLab 1.0
  [datakurre]

1.0rc1 (2019-04-01)
-------------------

- Move tutorials notebooks into notebooks folder
  [datakurre]
- Fix WhiteLibrary autocompletion to suggest selectors with :-separator
  instead of =-separator
  [datakurre]

0.12.2 (2019-03-30)
-------------------

- Fix remaining where keeping state of suite level variables between cell
  executions since 0.12.0 caused regression by fixing the listener to ignore
  all known built-in variables
  [datakurre]

0.12.1 (2019-03-27)
-------------------

- Fix issue where keeping state of suite level variables between cell
  executions resulted in errors caused by outdated output directory
  from the old variables
  [datakurre]

0.12.0 (2019-03-26)
-------------------

New features:

- Add keyword execution widgets below executed keyword cells; Add to toggle
  widgets on consecutive executions without code changes
  [datakurre]

- Add listener to keep state of suite level variables between robot executions
  [datakurre]

- Add IPython display hooks
  [datakurre]

New features:

- Add updates to highlighting from ipythonrobotframework
  [datakurre]

0.11.0 (2019-01-29)
-------------------

- Add WhiteLibrary state support and interactive element picker
  [datakurre]

- Add WhiteLibraryCompanion keyword library to interactively
  select elements and click elements with OpenCV templates
  [datakurre]

0.10.2 (2019-01-11)
-------------------

- Fix syntax highlighting issue where only the first variable of many was
  highlighted
  [datakurre]

0.10.1 (2019-01-10)
-------------------

- Update package trove classifiers
  [datakurre]

0.10.0 (2019-01-08)
-------------------

Breaking:

- Setuptools 40.5.0 later and Robot Framework 3.1 or later.
  [datakurre]

new features:

- Add pregenerated kernel.json in data_files to auto-install robotkernel,
  but requiring
  [datakurre]

0.9.0 (2019-01-04)
------------------

New features:

- Rewrite status updater to the status of currently run test as
  ``trobber | test name | keyword name | robot.api.logger.console message``
  [datakurre]

- Add embedded log and report to include Download-links at top right corner
  [datakurre]

- Add to display the results of the last executed keyword as the notebook
  result for the executed code cell
  [datakurre]

- Add syntax highlighting for variables and assignment operators
  [datakurre]

Bug fixes:

- Fix issue where setup.cfg contained OS specific path separators preventing
  build on Windows
  [datakurre]

- Fix issue where PNGs were interpreted as APNG on Windows preventing
  them from being rendered on Windows
  [datakurre]

- Update example notebook to use SeleniumLibrary and SeleniumScreenshots
  instead of SeleniumLibrary and Selenium2Screenshots
  [datakurre]

- Add to always reload libraries imported from other notebooks
  [datakurre]

0.8.0 (2018-12-14)
------------------

- Add to auto-import nbimporter when available to make it possible to
  import eg. keyword libraries from Python notebooks
  [datakurre]
- Fix issue where nbrobot did support %%python module magic
  [datakurre]

0.7.1 (2018-11-20)
------------------

- Add to require robotframework >= 3.1b1 in requires

0.7.0 (2018-10-31)
------------------

Breaking:

- Requires robotframework >= 3.1b1

Other:

- Add to create nbreader and nblibdoc cli to run robot with notebook reader
  support
  [datakurre]
- Add Selenium completions to sometimes include raw Simmer results with
  simplfied id completion results
  [datakurre]
- Add proof-of-concept selector completion for Appium and AutoIT libraries
  [datakurre]
- Fix screenshot processor to also discover images with absolute path or within
  the current working directory
  [datakurre]

0.6.3 (2018-10-19)
------------------

This is the last release compatible with robotframework < 3.1

- Remove deprecated replace-flag from kernel installer
  [datakurre]

0.6.2 (2018-10-19)
------------------

- Fix compatibility issue with robotframework < 3.1
  [datakurre]

0.6.1 (2018-10-19)
------------------

- Fix issue where kernel installation produced broken kernel.json on Windows
  [datakurre]

0.6.0 (2018-10-18)
------------------

- Revert data source path from temporary directory into current working
  directory to allow local libraries and resources work in the usual use cases
  [datakurre]
- Add experimental Simmerjs based CSS-selector builder and element picker with
  when auto-completion is called with empty "css:"-selector
  [datakurre]
- Add experimental Selenium selector auto-completion
  [datakurre]
- Add dummy variable completion with only variables from current suite without
  context knowledge
  [datakurre]
- Add inline documentation links to Robot Framework User Guide for structural
  keywords
  [datakurre]

0.5.4 (2018-10-09)
------------------

- Fix issue where single term keywords got no completions
  [datakurre]

0.5.3 (2018-10-09)
------------------

- Update README
  [datakurre]

0.5.1 (2018-10-08)
------------------

- Auto completion and keyword doc inspection enhancements
  [datakurre]

0.5.0 (2018-10-08)
------------------

- Add auto-completion, keyword doc inspection and support for
  replacing and deleting cell history on Jupyter lab
  [datakurre]

0.4.0 (2018-09-26)
------------------

- Add support for robotframework 3.1a2
  [datakurre]

- Add support for reporting RPA suites with "Tasks" instead of "Tests"
  [datakurre]

0.3.5 (2018-09-25)
------------------

- Update README with notebook execution instructions
  [datakurre]

0.3.4 (2018-09-25)
------------------

- Update README
  [datakurre]

0.3.3 (2018-09-25)
------------------

- Note on README that Log | Report -links require trusting the notebook
  [datakurre]

- Fix to wrap test execution updates with '<pre>' for better readability
  [datakurre]

0.3.2 (2018-09-25)
------------------

- Change to always send display data updates in text/html to workaround a bug
  that caused 'undefined' to be rendered in JupyterLab
  [datakurre]

0.3.1 (2018-09-24)
------------------

- Update README
  [datakurre]

0.3.0 (2018-09-23)
------------------

- First release.
  [datakurre]


