Merge branch 'master' of https://github.com/rhoerbe/saml2test

Conflicts:
	INSTALL
	LICENSE.txt
	README.rst
	doc/Makefile
	doc/conf.py
	doc/index.rst
	doc/install.rst
	doc/make.bat
	doc/make.sh
	setup.py
	tests/attributemaps/basic.py
	tests/attributemaps/saml_uri.py
	tests/attributemaps/shibboleth_uri.py

8 files changed, 892 insertions, 191 deletions

diff --git a/doc/Makefile b/doc/Makefile
index e467970b..462e0de6 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,84 +5,149 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
+BUILDDIR      = _build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf _build/*
+	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
-	@echo "Build finished. The HTML pages are in _build/dirhtml."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in _build/htmlhelp."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in _build/qthelp, like this:"
-	@echo "# qcollectiongenerator _build/qthelp/pysaml2.qhcp"
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SAML2test.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SAML2test.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile _build/qthelp/pysaml2.qhc"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/SAML2test"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SAML2test"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
-	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
 changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
-	@echo "The overview file is in _build/changes."
+	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-	      "or in _build/linkcheck/output.txt."
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in _build/doctest/output.txt."
+	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/doc/conf.py b/doc/conf.py
index 1f7f2b52..81a57fd9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
-# pysaml2 documentation build configuration file, created by
-# sphinx-quickstart on Mon Aug 24 08:13:41 2009.
+# SAML2test documentation build configuration file, created by
+# sphinx-quickstart on Sat Jan 19 11:38:19 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
@@ -17,13 +17,16 @@ import alabaster
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+#sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'sphinx.ext.viewcode',]
+extensions = ['alabaster', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -32,23 +35,23 @@ templates_path = ['_templates']
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8'
+#source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'pysaml2'
-copyright = u'2014, Roland Hedberg'
+project = u'SAML2test'
+copyright = u'2013, Roland Hedberg'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.2'
+version = '0.3.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.2.0beta'
+release = '0.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -60,12 +63,9 @@ release = '1.2.0beta'
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['_build']
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -90,9 +90,8 @@ pygments_style = 'sphinx'
 
 # -- Options for HTML output ---------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-#html_theme = 'default'
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
 html_theme_path = [alabaster.get_path()]
 html_theme = 'alabaster'
 html_sidebars = {
@@ -105,10 +104,10 @@ html_sidebars = {
 }
 
 html_theme_options = {
-   'description': 'SAML2 implementation',
+   'description': '',
    'github_button': False,
-   'github_user': 'rohe',
-   'github_repo': 'pysaml2',
+   'github_user': 'its-dirg',
+   'github_repo': 'IdProxy',
    'github_banner': False,
 
 }
@@ -158,7 +157,7 @@ html_static_path = ['_static']
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_use_modindex = True
+#html_domain_indices = True
 
 # If false, no index is generated.
 #html_use_index = True
@@ -169,30 +168,41 @@ html_static_path = ['_static']
 # If true, links to the reST sources are added to the pages.
 #html_show_sourcelink = True
 
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pysaml2doc'
+htmlhelp_basename = 'SAML2testdoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
 
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
 
 # The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'pysaml2.tex', u'pysaml2 Documentation',
+  ('index', 'SAML2test.tex', u'SAML2test Documentation',
    u'Roland Hedberg', 'manual'),
 ]
 
@@ -204,11 +214,48 @@ latex_documents = [
 # not chapters.
 #latex_use_parts = False
 
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
-#latex_use_modindex = True
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'saml2test', u'SAML2test Documentation',
+     [u'Roland Hedberg'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'SAML2test', u'SAML2test Documentation',
+   u'Roland Hedberg', 'SAML2test', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
diff --git a/doc/howto.rst b/doc/howto.rst
new file mode 100644
index 00000000..5fa65de8
--- /dev/null
+++ b/doc/howto.rst
@@ -0,0 +1,431 @@
+.. _howto:
+
+How to use SAML2test
+====================
+
+:Release: |release|
+:Date: |today|
+
+Before you can use SAML2test, you must get it installed.
+If you have not done so yet, read `Install <install.rst>`_.
+
+When you want to test a SAML2 entity with this tool you need following things:
+
+#. The Test Driver Configuration, an example can be found in tests/idp_test/config.py
+#. Attribute Maps mapping URNs, OIDs and friendly names
+#. Key files for the test tool
+#. A metadata file representing the tool
+#. The Test Target Configuration file describes how to interact with the entity to be tested.  The metadata for the entity is part of this file. An example can be found in tests/idp_test/test_target_config.py.
+
+These files should be stored outside the saml2test package to have a clean separation between the package and a particular test configuration. To create a directory for the configuration files copy the saml2test/tests including its contents.
+
+
+(1) Test Driver Configuration
+:::::::::::::::::::::::::::::
+
+This is a normal `PySAML2 configuration file <http://pythonhosted.org/pysaml2/howto/config.html>`_. You can have more than one and then chose which one to use at run time by supplying the test script with an argument. If no configuration is explicitly provided than **tests/ipd_test/config.py** is provided as a default.
+
+This configuration mostly contains the test tool’s metadata structured as a Python dictionary. It doesn't vary a lot between testing different IdPs, except for the value of BASE, and optionally these control options:
+
+In addition to the configuration directives documented for the PySAML2 configuration file these may be used:
+
+accepted_time_diff
+..................
+Default: 60
+
+logger
+......
+Specify the logging options for the test run.
+
+only_use_keys_in_metadata
+.........................
+If true it ignore the validation path of signing keys. As of V0.4.0, this does not apply to TLS keys (which does not conform to [SAML MetaIOP].
+If false it does validate the signing certificate against the default CA keys of pysaml2. Add the directory to python path, like:
+export PYTHONPATH=/some_path/saml2test.conf   # Remember: no trailing slash in PYTHONPATH
+
+secret
+......
+Not being used currently
+
+You could also change organization and contact information if you'd like to.
+
+(2) Attribute Mapping
+:::::::::::::::::::::
+Attributes that may be contained in a SAML assertion must be defined in the attribute mapping as documented in the `PySAML2 config guide <http://pythonhosted.org/pysaml2/howto/config.html#attribute-map-dir>`_. If the ‚to‘ and ‚fro‘ mappings are exactly the same just one of them is required. But sometimes it is necessary to have both "to" and "from" because translation isn't symmetric. Like having "sn" and "surname" mapping to the same urn.
+
+You may copy the default mapping into your test configuration directory:
+cp -pr saml2test/tests/attributemaps .
+
+There must be one file per attribute namespace, i.e. attrname-format:basic needs to go into basic.py, and attrname-format:uri needs to go into saml_uri.py.
+
+(3) Key Files
+:::::::::::::
+The test tool’s metadata needs key files, both a private key and a certificate. The default files are provided in same2test/tests/keys as:
+mykey.pem
+mycert.pem
+To change file names, the references in the Tool Configuration need be be changed as well.
+
+(4) Test Tool Metadata
+::::::::::::::::::::::
+The test tool’s metadata is generated from the contents of the Tool Configuration, e.g.:
+make_metadata.py config.py > testdrv_metadata.xml
+
+The resulting SAML2 metadata needs to be imported to the test target.
+
+
+(5) Test Target Configuration File
+::::::::::::::::::::::::::::::::::
+This configuration is contained in the "info" Python dictionary.
+
+The keys are:
+
+entity_id
+.........
+
+**entity_id** is really only necessary if there is more than one entity
+represented in the metadata. If not provided and if the **metadata** only
+describes one entity that entity's entityID is used.
+
+start_page
+..........
+
+URL for the initial request the test driver issues when executing an SP test.
+
+args
+....
+
+Contains a Python dictionary controlling some aspects of an Authnentication Response" with following structure::
+
+    "AuthnResponse": {
+        "sign_assertion": True,
+        "authn":  {"class_ref": AUTHN_PASSWORD_PROTECTED, # Authentication Context Class Reference
+                   "authn_auth": "http://authnservice.example.com/login"}  # Authenticating Authority
+    },
+
+identity
+........
+
+Contains a list of key-value pairs with attribute names and values, that the embedded IDP will include in assertions.
+Attribute Names in this context are friendly names, not URNs/OIDs.
+To obtain these attributes from the IDP there are three options:
+    #. include an EntityCategory in the EntityDescriptor of the SP. The EntityCategory must be defined in pysaml2.
+    #. include RequestedAttributes in the EntityDescriptor of the SP.
+    #. include RequestedAttributes in the AuthnRequest.
+These methods work additive. Attributes must be registered in the attribute map.
+
+userid
+......
+
+The UserID used as a base for the Assertion/Subject/NameID.
+
+
+interaction
+...........
+
+The really hard part is the **interaction** part. This is where the
+the script is told how to fake that there is a human behind the keyboard.
+
+It consists of a lists of dictionaries with the keys: **matches**,
+**page-type** and **control**.
+
+The idea is to use **matches** to **activated** a corresponding set of **controls**.
+
+matches
+-------
+
+**matches** is used to identify a page or a form within a page.
+There are four different things that can be used to match the page:
+
+* url : The action url
+* title : The title of the page, substring matching is used.
+* content: Something in the page, again substring matching is used, and finally
+* class: (currently not used)
+
+Normally the front-end will pick out the necessary information by
+using a users interaction with the entity. If you are running this
+directly from the prompt then you have to provide the information.
+You can build this information by using the fact that the script will
+dump any page it doesn't know what to do with.
+
+An example::
+
+
+    {
+        "matches": {
+            "url": "http://localhost:8088/login",
+            "title": 'IDP test login'
+        },
+        "page-type": "login",
+        "control": {
+            "type": "form",
+            "set": {"login": "roland", "password": "dianakra"}
+        }
+    }
+
+The action here is to set the control *login* to 'roland' and the control
+*password* to 'dianakra' and then post the form.
+
+Or if the server uses HTTP Post binding::
+
+    {
+        "matches": {
+            "url": "http://localhost:8088/sso/redirect",
+            "title": "SAML 2.0 POST"
+        },
+        "control": {
+            "type": "response",
+            "pick": {"form": {"action":"http://localhost:8088/acs"}}
+        }
+    },
+
+Here the action is just to post the form, no information is added to the form.
+
+page-type
+---------
+
+**page-type** is used to mark the page as *login* or *user-consent*.
+This is used in specific conversation where one or the other is expected
+in certain circumstances.
+
+control
+-------
+
+**control** specifies what the script should enter where and which button
+to press.
+
+metadata
+........
+
+This is then the metadata for the entity to be tested. As noted previously
+the metadata can actually describe more than one entity. In this case
+the **entity_id** must be specified explicitly.
+
+Running the script testing an IDP
+:::::::::::::::::::::::::::::::::
+
+Synopsis::
+
+    $ idp_testdrv.py --help
+    usage: idp_testdrv.py [-h] [-d] [-H] [-C CA_CERTS] [-J TT_CONFIG_FILE] [-m] [-l]
+                     [-c TD_CONFIG]
+                     [oper]
+
+    positional arguments:
+      oper                 Which test to run
+
+    optional arguments:
+      -C CA_CERTS            CA certs to use to verify HTTPS server certificates, if
+                             HTTPS is used and no server CA certs are defined then
+                             no cert verification will be done. For a generic validation you may use the ca_bundle.crt
+                             file that comes with Mozilla.
+      -c TD_CONFIG, --config Test driver configuration module at the current directory or the path specified
+                             with the -P option. Do not use relative paths or the .py filename extension
+      -d, --debug            Print debug information to stderr
+      -H, --prettyprint      Status output as human readable python dictionary
+      -h, --help             show this help message and exit
+      -J TT_CONFIG_FILE      Test target configuration in JSON format
+      -L, --log              Print HTTP log information # TODO: update documentation
+      -l, --list             List all the test operations as a JSON object
+      -m, --metadata         Return the SP metadata
+      -O, --operations       Operations module (generated from Repository as idp_saml2base.py)
+      -P, --configpath       Path to the configuration file for the SP
+      -t, --testpackage      Module describing tests (e.g. idp_samlbase.py generated from repository)
+      -Y, --pysamllog        Print pySAML2 logs to stderr
+
+    Output on stdout is a JSON dicitionary containing the test summary (overwrite with -H).
+    Output to stderr is the log file
+
+
+Remember to generate the test target's config file in json format from python.
+
+
+Running the script testing an SP
+::::::::::::::::::::::::::::::::
+
+Synopsis::
+
+    $ sp_testdrv.py --help
+    usage: sp_testdrv.py [-h] [-H] [-d] [-C CA_CERTS] [-J TT_CONFIG_FILE] [-m] [-l] [-c TD_CONFIG] [oper]
+
+    positional arguments:
+      oper                 Which test to run (mandatory except for options -h, -l and -m)
+
+    optional arguments:
+      -C CA_CERTS           CA certs to use to verify HTTPS server certificates, if
+                            HTTPS is used and no server CA certs are defined then
+                            no cert verification will be done. For a generic validation you may use the ca_bundle.crt
+                            file that comes with Mozilla.
+      -c TD_CONFIG, --config Test driver configuration module at the current directory or the path specified
+                            with the -P option. Do not use relative paths or filename extension
+      -d, --debug           Print debug information to stderr
+      -h, --help            show this help message and exit
+      -H, --prettyprint      Status output as human readable python dictionary
+      -J TT_CONFIG_FILE     Test target configuration in JSON format
+      -k                    Print HTTP response contents into separate files
+      -L, --log             Path to the logfile directory
+      -l, --list            List all the test flows as a JSON object
+      -m, --metadata        Return the SP metadata
+      -O, --operations      Operations module (generated from Repository as idp_saml2base.py)
+      -P, --configpath      Path to the configuration file for the SP
+      -t, --testpackage     Module describing tests (e.g. sp_testbase.py generated from repository)
+      -Y, --pysamllog       Print pySAML2 logs to stderr
+
+    Output on stdout is a JSON dicitionary containing the test summary (overwrite with -H).
+    Output to stderr is the log file
+
+Examples
+::::::::
+
+To see what tests are available::
+
+    $ idp_testdrv.py -l
+    [
+        {
+            "id": "basic-authn",
+            "descr": "AuthnRequest using HTTP-redirect",
+            "name": "Absolute basic SAML2 AuthnRequest"
+        }, {
+            "id": "basic-authn-post",
+            "descr": "AuthnRequest using HTTP-POST",
+            "name": "Basic SAML2 AuthnRequest using HTTP POST"
+        }, {
+            "id": "log-in-out",
+            "descr": "AuthnRequest using HTTP-redirect followed by a logout",
+            "name": "Absolute basic SAML2 log in and out"
+        }, {
+            "id": "authn-assertion_id_request",
+            "descr": "AuthnRequest followed by an AssertionIDRequest",
+            "name": "AuthnRequest and then an AssertionIDRequest"
+        }, {
+            "id": "authn-authn_query",
+            "descr": "AuthnRequest followed by an AuthnQuery",
+            "name": "AuthnRequest and then an AuthnQuery"
+        }
+    ]
+
+A typical command would then be (reformated to be more readable)::
+
+    $ idp_testdrv.py -J localhost.json 'log-in-out'
+    {
+        "status": 1,
+        "tests": [
+            {
+                "status": 1,
+                "id": "check-saml2int-metadata",
+                "name": "Checks that the Metadata follows the profile"
+            }, {
+                "status": 1,
+                "id": "check-http-response",
+                "name": "Checks that the HTTP response status is within the 200 or 300 range"
+            }, {
+                "status": 1,
+                "id": "check-http-response",
+                "name": "Checks that the HTTP response status is within the 200 or 300 range"
+            }, {
+                "status": 1,
+                "id": "check-http-response",
+                "name": "Checks that the HTTP response status is within the 200 or 300 range"
+            }, {
+                "status": 1,
+                "id": "check-saml2int-attributes",
+                "name": "Any <saml2:Attribute> elements exchanged via any SAML 2.0 messages, assertions, or metadata MUST contain a NameFormat of urn:oasis:names:tc:SAML:2.0:attrname-format:uri."
+            }, {
+                "status": 1,
+                "id": "verify-content",
+                "name": "Basic content verification class, does required and max/min checks"
+            }, {
+                "status": 1,
+                "id": "check-logout-support",
+                "name": ""
+            }, {
+                "status": 1,
+                "id": "verify-content",
+                "name": "Basic content verification class, does required and max/min checks"
+            }, {
+                "status": 1,
+                "id": "verify-logout",
+                "name": ""
+            }
+        ],
+        "id": "log-in-out"
+    }
+
+First you have the status for the whole test was '1', which is the same as OK,
+for this test run.
+The used status code are:
+
+0. INFORMATION
+1. OK
+2. WARNING  (the test target's behavior is according to the spec but may not be as expected )
+3. ERROR (the test target's behavior is not according to the spec)
+4. CRITICAL (the test driver threw an exception)
+5. INTERACTION (interaction needed but matching rule does not match - applies to final page in SP test as well)
+
+Then you get all the separate sub tests that has been run during the
+conversation.
+
+If things go wrong you will get a trace log dump to stderr.
+If all goes well but you still want to see all the interaction you can do::
+
+    $ idp_testdrv.py -J localhost.json -d 'basic-authn' 2> tracelog
+    < same output as above >
+    $ cat tracelog
+    0.017364 SAML Request: <?xml version='1.0' encoding='UTF-8'?>
+    <ns0:AuthnRequest xmlns:ns0="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:ns1="urn:oasis:names:tc:SAML:2.0:assertion" AssertionConsumerServiceURL="http://localhost:8087/acs/redirect" Destination="http://localhost:8088/sso/redirect" ID="id-8c9a57670d1bc374898297702285ba74" IssueInstant="2013-01-20T09:02:44Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" ProviderName="SAML2 test tool" Version="2.0"><ns1:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://localhost:8087/sp.xml</ns1:Issuer><ns0:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" /></ns0:AuthnRequest>
+    0.036136 <-- REDIRECT TO: http://localhost:8088/login?came_from=%2Fsso%2Fredirect&key=331035cf0e26cdefc15759582e34994ac8e54971
+    0.040084 <-- CONTENT:
+
+
+    <html>
+    <head><title>IDP test login</title>
+        <link rel="stylesheet" type="text/css" href="/css/main.css" media="screen">
+        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    </head>
+    <body>
+        <div class="header">
+            <h1><a href="/">Login</a></h1>
+        </div>
+
+
+    <h1>Please log in</h1>
+    <p class="description">
+        To register it's quite simple: enter a login and a password
+    </p>
+
+    <form action="/verify" method="post">
+        <input type="hidden" name="key" value="331035cf0e26cdefc15759582e34994ac8e54971"/>
+        <input type="hidden" name="came_from" value="/sso/redirect"/>
+
+        <div class="label">
+            <label for="login">Username</label>
+        </div>
+        <div>
+            <input type="text" name="login" value=""/><br/>
+        </div>
+
+        <div class="label">
+            <label for="password">Password</label>
+        </div>
+        <div>
+            <input type="password" name="password"
+                   value=""/>
+        </div>
+
+        <input class="submit" type="submit" name="form.submitted" value="Log In"/>
+    </form>
+
+    <div>
+            <div class="footer">
+                <p>&#169; Copyright 2011 Ume&#229; Universitet &nbsp;</p>
+            </div>
+        </div>
+    </body>
+    </html>
+
+    0.042697 >> login <<
+    0.042715 <-- FUNCTION: select_form
+    0.042744 <-- ARGS: {u'set': {u'login': u'roland', u'password': u'dianakra'}, u'type': u'form', 'location': 'http://localhost:8088/login?came_from=%2Fsso%2Fredirect&key=331035cf0e26cdefc15759582e34994ac8e54971', '_trace_': <idp_test.Trace object at 0x101e79750>, 'features': None}
+    0.055864 <-- REDIRECT TO: http://localhost:8088/sso/redirect?id=zLvrjojPLLgbnDyq&key=331035cf0e26cdefc15759582e34994ac8e54971
+
+    ... and so on ...
+
diff --git a/doc/index.rst b/doc/index.rst
index c4b69f36..475cb6ec 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,29 +1,24 @@
 .. _index:
 
-.. pysaml2 documentation master file, created by
-   sphinx-quickstart on Mon Aug 24 08:13:41 2009.
+.. SAML2test documentation master file, created by
+   sphinx-quickstart on Sat Jan 19 11:38:19 2013.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-pysaml2
-========================================
+Welcome to SAML2test's documentation!
+=====================================
 
 :Release: |release|
 :Date: |today|
 
-PySAML2 is a pure python implementation of SAML2. It contains all necessary pieces for building a SAML2 service
-provider or an identity provider. The distribution contains examples of both. Originally written to work in a WSGI
-environment, there are extensions that allow you to use it with other frameworks.
-
 Contents:
 
 .. toctree::
    :maxdepth: 1
 
+   howto
    install
-   howto/index
-   examples/index
-   contents
+   saml2test
 
 Indices and tables
 ==================
@@ -34,6 +29,6 @@ Indices and tables
 
 .. raw:: html
 
-    <a href="https://github.com/rohe/pysaml2" class="github" target="_blank">
-        <img style="position: absolute; top: 0; right: 0; border: 0;" src="_static/ViewmeonGitHub.png" alt="View me on GitHub"  class="github"/>
-    </a>
+    <a href="https://github.com/rohe/saml2test" class="github" target="_blank">
+        <img style="position: absolute; top: 0; right: 0; border: 0;" src="_static/ViewmeonGitHub.png" alt="Fork me on GitHub"  class="github"/>
+    </a>
\ No newline at end of file
diff --git a/doc/install.rst b/doc/install.rst
index 05e0751a..a19fd38f 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -3,36 +3,23 @@
 Quick install guide
 ===================
 
-Before you can use PySAML2, you'll need to get it installed. This guide 
+Before you can use SAML2test, you'll need to get it installed. This guide
 will guide you to a simple, minimal installation.
 
-Install PySAML2
----------------
+Install SAML2test
+-----------------
 
-For all this to work you need to have Python installed. 
-The development has been done using 2.7.
-There is now a 3.X version.
+For all this to work you need to have Python installed.
+The development has been done using 2.7.2.
+There is no 3.X version yet.
 
 Prerequisites
 ^^^^^^^^^^^^^
 
-You have to have ElementTree, which is either part of your Python distribution
-if it's recent enough, or if the Python is too old you have to install it,
-for instance by getting it from the Python Package Instance by using 
-easy_install.
+The big dependency is on pysaml2, which you for the time being must
+get from github::
 
-You also need xmlsec1 which you can download from http://www.aleksey.com/xmlsec/
-
-If you're on OS X you can get xmlsec1 installed from MacPorts or Fink.
-
-Depending on how you are going to use PySAML2 you might also need
-
-* Mako
-* pyASN1
-* repoze.who
-* python-memcache
-* memcached
-* bsddb3
+    $ git clone https://github.com/rohe/pysaml2.git
 
 Quick build instructions
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -43,54 +30,3 @@ Once you have installed all the necessary prerequisites a simple::
 
 will install the basic code.
 
-Note for rhel/centos 6: cffi depends on libffi-devel, and cryptography on openssl-devel to compile
-So you might want first to do:
-yum install libffi-devel openssl-devel
-
-After this you ought to be able to run the tests without an hitch.
-The tests are based on the pypy test environment, so::
-
-    cd tests
-    py.test 
-
-is what you should use. If you don't have py.test, get it it's part of pypy! 
-It's really good!
-
-Hints
------
-
-RHEL/CentOS installation issues
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A number of packages may not install from pypi. Instead, you may want to use packages supplied with the OS:
-
-    yum -y install swig openssl-devel m2crypto xmlsec1 pyOpenSSL libffi-devel
-
-OS X installation issues
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-A number of packages may not install from pypi. Instead, you may want to use macports:
-
-    sudo port install swig xmlsec py27-m2crypto py27-crypto db53
-
-Starting with XCode 5.1 there is an issue with unrecognised gcc command line options.
-A temporary fix is described in http://alyssafrazee.com/dangit-mavericks.html
-So to install cryptography and bsddb3 you might want to try:
-sudo ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install cryptography bsddb3
-
-If the message "ImportError: No module named _bsddb" pops up on starting idp.py, this fix should help:
-http://marc-abramowitz.com/archives/2007/11/28/hacking-os-xs-python-dbhash-and-bsddb-modules-to-work/
-
-
-Generate the HTML documentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-install Sphinx
-cd pysaml2/doc
-make html
-cd _build
-
-List implemented signature algorithms
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For a list of xmldsig algorithtms implemented for signature validation, run this program from the command line:
-saml2/sigver.py -s
diff --git a/doc/make.bat b/doc/make.bat
index 4a006237..34e7d66c 100644
--- a/doc/make.bat
+++ b/doc/make.bat
@@ -2,10 +2,15 @@
 
 REM Command file for Sphinx documentation
 
-set SPHINXBUILD=sphinx-build
-set ALLSPHINXOPTS=-d _build/doctrees %SPHINXOPTS% .
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 )
 
 if "%1" == "" goto help
@@ -13,99 +18,172 @@ if "%1" == "" goto help
 if "%1" == "help" (
 	:help
 	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html      to make standalone HTML files
-	echo.  dirhtml   to make HTML files named index.html in directories
-	echo.  pickle    to make pickle files
-	echo.  json      to make JSON files
-	echo.  htmlhelp  to make HTML files and a HTML help project
-	echo.  qthelp    to make HTML files and a qthelp project
-	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  changes   to make an overview over all changed/added/deprecated items
-	echo.  linkcheck to check all external links for integrity
-	echo.  doctest   to run all doctests embedded in the documentation if enabled
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
 	goto end
 )
 
 if "%1" == "clean" (
-	for /d %%i in (_build\*) do rmdir /q /s %%i
-	del /q /s _build\*
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
 	goto end
 )
 
 if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% _build/html
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
 	echo.
-	echo.Build finished. The HTML pages are in _build/html.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
 	goto end
 )
 
 if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% _build/dirhtml
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
 	echo.
-	echo.Build finished. The HTML pages are in _build/dirhtml.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
 	goto end
 )
 
 if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% _build/pickle
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can process the pickle files.
 	goto end
 )
 
 if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% _build/json
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can process the JSON files.
 	goto end
 )
 
 if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% _build/htmlhelp
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in _build/htmlhelp.
+.hhp project file in %BUILDDIR%/htmlhelp.
 	goto end
 )
 
 if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% _build/qthelp
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in _build/qthelp, like this:
-	echo.^> qcollectiongenerator _build\qthelp\pysaml2.qhcp
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\SAML2test.qhcp
 	echo.To view the help file:
-	echo.^> assistant -collectionFile _build\qthelp\pysaml2.ghc
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\SAML2test.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
 	goto end
 )
 
 if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% _build/latex
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
 	echo.
-	echo.Build finished; the LaTeX files are in _build/latex.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
 	goto end
 )
 
 if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% _build/changes
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
 	echo.
-	echo.The overview file is in _build/changes.
+	echo.The overview file is in %BUILDDIR%/changes.
 	goto end
 )
 
 if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% _build/linkcheck
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Link check complete; look for any errors in the above output ^
-or in _build/linkcheck/output.txt.
+or in %BUILDDIR%/linkcheck/output.txt.
 	goto end
 )
 
 if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% _build/doctest
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Testing of doctests in the sources finished, look at the ^
-results in _build/doctest/output.txt.
+results in %BUILDDIR%/doctest/output.txt.
 	goto end
 )
 
diff --git a/doc/make.sh b/doc/make.sh
index b9d96a42..8496e1df 100755
--- a/doc/make.sh
+++ b/doc/make.sh
@@ -1,5 +1,5 @@
 #!/bin/sh
-rm -f ./code/*
-sphinx-apidoc -F -o ../doc/code ../src
+rm -f saml2test*
+sphinx-apidoc -F -o ../doc/ ../src/saml2test
 make clean
-make html
+make html
\ No newline at end of file
diff --git a/doc/sp_test/internal.rst b/doc/sp_test/internal.rst
new file mode 100644
index 00000000..5875cdf1
--- /dev/null
+++ b/doc/sp_test/internal.rst
@@ -0,0 +1,149 @@
+How sp_test works internally
+============================
+
+:Release: |release|
+:Date: |today|
+
+This are a few hints how sp_test works internally. It halps to extend it with
+new test classes
+
+When you want to test a SAML2 entity with this tool you need following things:
+
+#. The Test Driver Configuration, an example can be found in tests/idp_test/config.py
+#. Attribute Maps mapping URNs, OIDs and friendly names
+#. Key files for the test tool
+#. A metadata file representing the tool
+#. The Test Target Configuration file describes how to interact with the entity to be tested.  The metadata for the entity is part of this file. An example can be found in tests/idp_test/test_target_config.py.
+
+These files should be stored outside the saml2test package to have a clean separation between the package and a particular test configuration. To create a directory for the configuration files copy the saml2test/tests including its contents.
+
+
+(1) Class and Object Structure
+::::::::::::::::::::::::::::::
+
+Client (sp_test/__init__.py)
+.........................
+Its life cycle is responsible for following activites:
+ - read config files and command line argumants (the test driver's config is "json_config")
+ - initialize the test driver IDP
+ - initialize a Conversation
+ - start the Conversion with .do_sequence_and_tests()
+ - post-process log messages
+
+Conversation (sp_test/base.py)
+..............................
+
+Operation (oper)
+................
+  - Comprises an id, name, sequence and tests
+  - Example: 'sp-00': {"name": 'Basic Login test', "sequence": [(Login, AuthnRequest, AuthnResponse, None)], "tests": {"pre": [], "post": []}
+
+OPERATIONS
+..........
+  - set of operations provided in sp_test
+  - can be listed with the -l command line option
+
+Sequence
+........
+  - A list of flows
+  - Example: see "sequence" item in operation dict
+
+Test (in the context of an operation)
+....
+  - class to be executed as part of an operation, either before ("pre") or after ("post") the sequence or inbetween a SAML request and response ("mid").
+    There are standard tests with the Request class (VerifyAuthnRequest) and operation-specific tests.
+  - Example for an operation-specific "mid" test: VerifyIfRequestIsSigned
+  - A test may be specified together with an argument as a tupel
+
+Flow
+....
+  * A tupel of classes that together implement an SAML request-response pair between IDP and SP (and possible other actors, such as a discovery service or IDP-proxy). A class can be derived from Request, Response (or other), Check or Operation.
+  * A flow for a solicited authentication consists of 4 classes:
+
+    * flow[0]: Operation (Handling a login flow such as discovery or WAYF - not implemented yet)
+    * flow[1]: Request (process the authentication request)
+    * flow[2]: Response (send the authentication response)
+    * flow[3]: Check (optional - can be None. E.g. check the response if a correct error status was raised when sending a broken response)
+
+Check (and subclasses)
+.....
+  - an optional class that is executed on receiving the SP's HTTP response(s) after the SAML response. If there are redirects it will be called for each response.
+  - writes a structured test report to conv.test_output
+  - It can check for expected errors, which do not cause an exception but in contrary are reported as success
+
+Interaction
+...........
+  - An interaction automates a human interaction. It searches a response from a test target for some constants, and if
+    there is a match, it will create a response suitable response.
+
+(2) Simplyfied Flow
+:::::::::::::::::::
+
+The following pseudocode is an extract showing an overview of what is executed
+for test sp-00::
+
+    do_sequence_and_test(self, oper, test):
+        self.test_sequence(tests["pre"])  # currently no tests defined for sp_test
+        for flow in oper:
+            self.do_flow(flow)
+
+    do_flow(flow):
+        if len(flow) >= 3:
+            self.wb_send_GET_startpage()  # send start page GET request
+            self.intermit(flow[0]._interaction)  # automate human user interface
+            self.parse_saml_message()    # read relay state and saml message
+        self.send_idp_response(flow[1], flow[2])  # construct, sign & send a nice Response from config, metadata and request
+        if len(flow) == 4:
+            self.handle_result(flow[3])  # pass optional check class
+        else:
+            self.handle_result()
+
+    send_idp_response(req_flow, resp_flow):
+        self.test_sequence(req_flow.tests["mid"])   # execute "mid"-tests (request has "VerifyContent"-test built in; others from config)
+        # this line stands for a part that is a bit more involved .. see source
+
+        args.update(resp._response_args)    # set userid, identity
+
+    test_sequence(sequence):
+        # execute tests in sequence (first invocation usually with check.VerifyContent)
+        for test in sequence:
+            self.do_check(test, **kwargs)
+
+    do_check(test, **kwargs):
+        # executes the test class using the __call__ construct
+
+    handle_result(response=None):
+        if response:
+            if isinstance(response(), VerifyEchopageContents):
+                if 300 < self.last_response.status_code <= 303:
+                    self._redirect(self.last_response)
+                self.do_check(response)
+            elif isinstance(response(), Check):
+                self.do_check(response)
+            else:
+                # A HTTP redirect or HTTP Post (not sure this is ever executed)
+                ...
+        else:
+            if 300 < self.last_response.status_code <= 303:
+                self._redirect(self.last_response)
+
+            _txt = self.last_response.content
+            if self.last_response.status_code >= 400:
+                raise FatalError("Did not expected error")
+
+(3) Status Reporting
+::::::::::::::::::::
+The proper reporting of results is at the core of saml2test. Several conditions
+must be considered:
+
+#. An operation that was successful because the test target reports OK (e.g. HTTP 200)
+#. An operation that was successful because the test target reports NOK as expected, e.g. because of an invalid signature - HTTP 500 could be the correct response
+#. An errror in SAML2Test
+#. An errror in configuration of SAML2Test
+
+Status values are defined in saml2test.check like this:
+INFORMATION = 0, OK = 1, WARNING = 2, ERROR = 3, CRITICAL = 4, INTERACTION = 5
+
+
+There are 2 targets to write output to:
+* Test_ouput is written to conv.test_ouput during the execution of the flows.
\ No newline at end of file