pmt-tools 0.1.0__tar.gz

pmt_tools-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.3
+Name: pmt-tools
+Version: 0.1.0
+Summary: Helpers for Pyodide-MkDocs-Theme selenium testing
+Author: Frédéric Zinelli
+Author-email: frederic.zinelli@gmail.com
+Requires-Python: >=3.9, <4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: selenium (>=4.36)
+Requires-Dist: selenium-query
+Description-Content-Type: text/markdown
+
+# Pmt Tools
+
+
+
+## Getting started
+
+To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+
+Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+
+## Add your files
+
+* [Create](https://docs.gitlab.com/user/project/repository/web_editor/#create-a-file) or [upload](https://docs.gitlab.com/user/project/repository/web_editor/#upload-a-file) files
+* [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
+
+```
+cd existing_repo
+git remote add origin https://gitlab.com/frederic-zinelli/pmt_tools.git
+git branch -M main
+git push -uf origin main
+```
+
+## Integrate with your tools
+
+* [Set up project integrations](https://gitlab.com/frederic-zinelli/pmt_tools/-/settings/integrations)
+
+## Collaborate with your team
+
+* [Invite team members and collaborators](https://docs.gitlab.com/user/project/members/)
+* [Create a new merge request](https://docs.gitlab.com/user/project/merge_requests/creating_merge_requests/)
+* [Automatically close issues from merge requests](https://docs.gitlab.com/user/project/issues/managing_issues/#closing-issues-automatically)
+* [Enable merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/)
+* [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
+
+## Test and Deploy
+
+Use the built-in continuous integration in GitLab.
+
+* [Get started with GitLab CI/CD](https://docs.gitlab.com/ci/quick_start/)
+* [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/user/application_security/sast/)
+* [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/topics/autodevops/requirements/)
+* [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/user/clusters/agent/)
+* [Set up protected environments](https://docs.gitlab.com/ci/environments/protected_environments/)
+
+***
+
+# Editing this README
+
+When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
+
+## Suggestions for a good README
+
+Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+
+## Name
+Choose a self-explaining name for your project.
+
+## Description
+Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+
+## Badges
+On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+
+## Visuals
+Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+
+## Installation
+Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+
+## Usage
+Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+
+## Support
+Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+
+## Roadmap
+If you have ideas for releases in the future, it is a good idea to list them in the README.
+
+## Contributing
+State if you are open to contributions and what your requirements are for accepting them.
+
+For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+
+You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+
+## Authors and acknowledgment
+Show your appreciation to those who have contributed to the project.
+
+## License
+For open source projects, say how it is licensed.
+
+## Project status
+If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+

pmt_tools-0.1.0/README.md

@@ -0,0 +1,93 @@
+# Pmt Tools
+
+
+
+## Getting started
+
+To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+
+Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+
+## Add your files
+
+* [Create](https://docs.gitlab.com/user/project/repository/web_editor/#create-a-file) or [upload](https://docs.gitlab.com/user/project/repository/web_editor/#upload-a-file) files
+* [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
+
+```
+cd existing_repo
+git remote add origin https://gitlab.com/frederic-zinelli/pmt_tools.git
+git branch -M main
+git push -uf origin main
+```
+
+## Integrate with your tools
+
+* [Set up project integrations](https://gitlab.com/frederic-zinelli/pmt_tools/-/settings/integrations)
+
+## Collaborate with your team
+
+* [Invite team members and collaborators](https://docs.gitlab.com/user/project/members/)
+* [Create a new merge request](https://docs.gitlab.com/user/project/merge_requests/creating_merge_requests/)
+* [Automatically close issues from merge requests](https://docs.gitlab.com/user/project/issues/managing_issues/#closing-issues-automatically)
+* [Enable merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/)
+* [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
+
+## Test and Deploy
+
+Use the built-in continuous integration in GitLab.
+
+* [Get started with GitLab CI/CD](https://docs.gitlab.com/ci/quick_start/)
+* [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/user/application_security/sast/)
+* [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/topics/autodevops/requirements/)
+* [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/user/clusters/agent/)
+* [Set up protected environments](https://docs.gitlab.com/ci/environments/protected_environments/)
+
+***
+
+# Editing this README
+
+When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
+
+## Suggestions for a good README
+
+Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+
+## Name
+Choose a self-explaining name for your project.
+
+## Description
+Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+
+## Badges
+On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+
+## Visuals
+Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+
+## Installation
+Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+
+## Usage
+Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+
+## Support
+Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+
+## Roadmap
+If you have ideas for releases in the future, it is a good idea to list them in the README.
+
+## Contributing
+State if you are open to contributions and what your requirements are for accepting them.
+
+For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+
+You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+
+## Authors and acknowledgment
+Show your appreciation to those who have contributed to the project.
+
+## License
+For open source projects, say how it is licensed.
+
+## Project status
+If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.

pmt_tools-0.1.0/pmt_tools/__init__.py

@@ -0,0 +1,14 @@
+
+from .runners import Runner, Button, ButtonHolder, PyBtn, AutoRun
+from .terminal import Terminal
+from .ide import Ide, IdeConfig, CheckBtnColor , CorrRemProfile
+from .qcm import Qcm, QcmStructure
+from .tabbed import TabbedContent
+
+
+
+def check(msg, actual, exp=None):
+    if exp is None:
+        exp = True
+    msg += f":\n{actual!r} should be {exp!r}"
+    assert actual == exp, msg

pmt_tools-0.1.0/pmt_tools/ide.py

@@ -0,0 +1,330 @@
+import json
+from math import inf
+from dataclasses import dataclass
+from typing import Literal, Union
+from contextlib import nullcontext
+
+from selenium.webdriver import Keys
+from selenium.webdriver.common.alert import Alert
+
+from .runners import ButtonHolder
+from .terminal import Terminal
+
+
+
+
+
+@dataclass
+class IdeConfig:
+    count: Union[float,int,None]
+    has_check_btn: bool
+    has_corr_and_reveal_btns: bool
+    revealed: bool = False
+
+    @property
+    def has_counter(self):
+        return self.count is not None
+
+
+
+
+
+
+
+class CorrRemProfile:
+    hidden:   'CorrRemProfile' = "hidden..."
+    none:     'CorrRemProfile' = "none..."
+    corr:     'CorrRemProfile' = "Solution"
+    rem:      'CorrRemProfile' = "Remarques"
+    corr_rem: 'CorrRemProfile' = "Solution & Remarques"
+
+
+class CheckBtnColor:
+    success: 'CheckBtnColor' = "green"
+    failure: 'CheckBtnColor' = "red"
+    default: 'CheckBtnColor' = ""
+
+
+
+
+
+
+@dataclass(repr=False)
+class BaseIde(Terminal):
+    """
+    WARNING : `.get.text` extracted from self.editor and self.terminal is "bare text", meaning
+    empty lines are actually ignored => DO NOT USE THIS.
+    """
+
+    def __post_init__(self):
+        super().__post_init__()
+        sol_div       = "#" + self.elt.get.id.replace('global', 'solution')
+        self.solution = self.elt.find(sol_div, in_page=True)
+        self.editor   = self.elt.find('.ace_editor textarea')
+        self.terminal = self.elt.find('.terminal-scroller')
+        self.counter  = self.elt.find('.compteur')
+        self.button   = ButtonHolder.build_buttons(
+            self,
+            '.stdout-ctrl',
+            '.stdout-wraps-btn',
+            'span.comment',
+            '.ide-split-screen',
+            '.ide-full-screen',
+            *(
+                f"button[btn_kind={ kind }]"
+                for kind in "play check download upload restart save zip corr_btn show".split()
+            )
+        )
+
+
+    def get_storage(self) -> dict:
+        storage = self.run_js(f"return localStorage.getItem('{ self._runner_id }')")
+        return storage and json.loads(storage) or {}
+
+
+    def reset(self):
+        """ Restart the IDE, NOT using the button, because it's a mess with the popup... """
+        self.run_js('{js_runner}.resetElement()')
+
+
+    def validate_and_check_btn_becomes(self, css_value:CheckBtnColor, validate=True):
+        if validate:
+            self.button.check.click()
+        self.check_validation_btn_color(css_value)
+
+
+    def check_validation_btn_color(self, css_value:CheckBtnColor):
+        self.button.check.elt.check.css({'--ide-btn-color': css_value})
+
+
+    def has_orange_box(self, expected=True, *, msg=""):
+        checker = self.button.check.elt.check(
+            f"The validation button should{ ' not'*(not expected) } have had the orange box."
+            f"\n\nOn: {msg or self.elt}"
+        )
+        if expected:
+            checker.has_class('dirty-validation')
+        else:
+            checker.not_.has_class('dirty-validation')
+
+
+    # def reset_global_N(self, n=0):
+    #     """
+    #     Set the global N value that is controlling the outcomes of some IDE (see py_libs) to
+    #     the given value (0 by default). This is done be going through a terminal command.
+    #     """
+    #     self.run_term_cmd(f"N={n}")
+
+    def check_has_src_hash_msg(self, has_it=True):
+        exp = """\
+Une version plus récente du code existe.
+Veuillez copier vos éventuelles modifications puis réinitialiser l'IDE.
+>>>
+""" if has_it else ">>> \n"
+        self.check_term_content(exp)
+
+
+    def zip_upload(self):
+        """
+        Triggers the zip upload logistic on the underlying IDE, bypassing the drag&drop thing.
+        The JS File object in window.seleniumUpload must already exist.
+        """
+        self.run_js("{js_runner}.dropArchiveFactory()()", async_=True)
+
+
+
+
+
+
+
+class IdeCodeEditor(BaseIde):
+
+    def set_python_global_N(self, n:int=0):
+        """ Override the N value for the `auto_N` logistic in PMT tests """
+        self.run_js(f"pyodide.runPython('N={n}')")
+
+    def clear_editor(self):
+        self.set_editor_code("")
+
+
+    def set_editor_code(self, code:str, do_save=False):
+        """ Replace the editor's content (save in the localeStorage if do_save is True). """
+        # code    = code.replace('"', '\\"')
+        do_save = json.dumps(do_save)
+        self.run_js(f"""{{js_runner}}.applyCodeToEditorAndSave(`{ code }`, {do_save})""")
+
+
+    def get_editor_code(self):
+        """ Extract the current content of the editor (no squashed empty lines!). """
+        return self.run_js("return {js_runner}.getCodeToTest()")
+
+
+    def check_code_editor(self, exp:str, msg:str="", use_repr=True, contains=False):
+        actual = self.get_editor_code()
+        s_act,s_exp = actual, exp
+        if use_repr:
+            s_act,s_exp = map(repr, (s_act,s_exp))
+
+        verb = 'CONTAIN' if contains else 'BE'
+        msg = (msg or "Wrong editor content:") + f'\ACTUAL:\n\n{s_act}\n\nSHOULD {verb}:\n\n{s_exp}'
+        ok = exp in actual if contains else actual == exp
+        assert ok, msg
+
+
+    def clean_then_type_in_editor(self, *content):
+        self.set_editor_code('')
+        self.send_keys(*content)
+
+
+    def send_keys(self, *content):
+        self.editor.scroll_to().send_keys(*content).go
+
+
+    def editor_shortcut(self, keys:str, *, exec=False, pause=None):
+        self._send_shortcut(keys, exec=exec, target=self.editor, pause=pause)
+
+
+
+
+
+
+class IdeCorrRemsCounter(BaseIde):
+    """
+    Regroup the counters + corr and REM logistic.
+    """
+
+
+    def check_count(self, exp: Union[int,float,None], msg=""):
+        """
+        Check that the counter (tries) has the expected value. Use `inf` to check for infinity.
+        """
+        if exp is None:
+            self.counter.check(msg).text("")
+        else:
+            assert self.counter.get.text, 'The compteur should hold some text'
+            tries = self.elt.find('.compteur > *')
+            tries.check.exists()
+            n_tries = tries[1].get.text
+            exp = "∞" if exp==inf else str(exp)
+            assert n_tries == exp, f"{ msg or 'Number of attempts left' }: { n_tries } should be { exp }"
+
+
+    def click_corr_rem(self):
+        """
+        Click on the corr & REM admonition to open/close it, then return the details's Getter.
+        """
+        details = self.solution.find('details').scroll_to()
+        self.solution.check.css(display='block')
+        details.click().go
+        return details
+
+
+    def check_corr_rem_config(self, profile:CorrRemProfile, finally_close=False):
+        """
+        Check that the corr/REMs have the desired contents/config:
+
+        WARNING: for positive profile values, the details element must be already revealed,
+        and it will be opened automatically during the test, if it is supposed to be visible.
+        If @finally_close is True, close the admonition at the end of the tests.
+
+        * -1: not revealed yet -> check hidden div
+        * 0: no corr or REM
+        * 1: corr but no rem -> check title + no fake h3 in the content
+        * 2: no corr but REM -> check title + no fake h3 in the content
+        * 3: corr + REM      -> check title + fake h3 present
+        """
+        if profile == CorrRemProfile.hidden:
+            self.solution.check.has_class('py_mk_hidden')
+            self.solution.check.css(display='none')
+
+        elif profile == CorrRemProfile.none:
+            self.solution.check("The div should be hidden...").css(display='block')
+            self.solution.check("...because the div should be empty").text('')
+
+        else:
+            self.solution.check('The solution div should be visible').css(display='block')
+            details = self.click_corr_rem()
+            details.find('summary').check.text(profile)
+
+            fake_h3 = details.find("span.rem_fake_h3")
+            if profile == CorrRemProfile.corr_rem:
+                fake_h3.check.exists()
+                fake_h3.check.text("Remarques :")
+            else:
+                fake_h3.check.exists(exp=False)
+
+        if finally_close:
+            details.click().go
+
+
+
+
+
+class IdeScreenModes(IdeCodeEditor):
+    """
+    Regroup the logistic for split and full screen modes.
+    """
+
+
+    def is_full_screen(self, enter:bool):
+        msg = f"{self.elt._full_css} should { ' not'*(not enter) } be in full screen mode."
+        assert self.run_js("return {js_runner}.isFullScreen") == enter, msg
+
+    def check_btn_full_screen(self, *, enter:bool):
+        self.button.full_screen.click(extra_delay=0.25)
+        self.is_full_screen(enter)
+
+    def check_shortcut_full_screen(self, *, enter:bool):
+        self.send_keys("x", Keys.BACKSPACE ,Keys.ESCAPE)
+        self.pause(0.25)
+        self.is_full_screen(enter)
+
+
+
+    def is_split_screen(self, enter:bool, alone=True):
+        msg = f"{self.elt._full_css} should { ' not'*(not enter) } be in two columns mode."
+        assert self.run_js("return {js_runner}.isInSplit") == enter, msg
+        self.elt.find('#pmt-top-div #'+self._runner_id, in_page=True).check.exists(enter or not alone)
+
+
+    def check_btn_split_screen(self, *, enter:bool):
+        self.button.two_cols.click()
+        self.is_split_screen(enter)
+
+    def check_shortcut_split_screen(self, *, enter:bool):
+        self.editor_shortcut("Alt+:")
+        self.is_split_screen(enter)
+
+
+
+    def check_placeholder_is_in_place(self):
+        self.elt.find(f'#pmt-ide-placeholder + #solution_{self._runner_id}', in_page=True).check(
+            "The placeholder element should be present just before the IDE solution div."
+        ).exists()
+
+    def check_is_back_in_place(self):
+        self.elt.find(f'#global_{self._runner_id} + #solution_{self._runner_id}', in_page=True).check(
+            "The IDE should be just before its solution div again."
+        ).exists()
+
+    def check_is_split_full_height(self):
+        body = self.elt.find('body', in_page=True)
+        H = body.get.rect['height']
+        header = body.find('header').get.rect['height']
+        top_H = body.find('#pmt-top-div').get.rect['height']
+        ide_H = self.elt.get.rect['height']
+
+        assert top_H == H-header, "the #pmt-top-div element should occupy the full viewport (except for the header)"
+        assert ide_H == top_H, "The IDE in split mode should have the height of the #pmt-top-div element"
+
+
+
+
+
+
+
+
+
+
+class Ide(IdeScreenModes, IdeCodeEditor, IdeCorrRemsCounter):
+    """ Global /common IDE class """

pmt_tools-0.1.0/pmt_tools/qcm.py

@@ -0,0 +1,182 @@
+from dataclasses import dataclass
+from typing import ClassVar, Dict, List, Tuple, Type, TYPE_CHECKING, Union
+
+from ..selenium_query import Getter
+
+if TYPE_CHECKING:
+    from..conftest import BaseSeleniumPage
+
+
+
+
+
+
+@dataclass
+class QcmStructure:
+
+    items_per_question: List[int]
+    """ Number of choices for each question. """
+
+    are_squares: List[bool]
+    """ Are the questions multi (square->True) or single choice (single->False)? """
+
+    correct: List[ Union[int, Tuple[int]] ]
+    """
+    Give the NUMBER (not the indices!) of the correct items for each question.
+    Use a tuple for "multi" questions.
+    """
+
+    shuffle_questions: bool
+    """ Are the questions shuffled? """
+
+    shuffled_items: List[bool]
+    """ Are the items of each question shuffled? """
+
+    mask: bool = False
+
+
+    def __post_init__(self):
+        assert len(self.shuffled_items) == len(self.are_squares) == len(self.items_per_question), (
+            "Wrong QcmStructure data: all lists should have the same length"
+        )
+
+
+
+
+
+
+
+
+
+
+
+
+
+@dataclass
+class Qcm:
+    """
+    Represent a PMT Qcm element.
+
+    WARNING: depending on the QCM having or not an admonition, the top level element may vary:
+    - `.qcm_no_admo.inner.py_mk_admonition_qcm` for QCMs WITHOUT admonitions
+    - `.admonition.py_mk_admonition_qcm` for QCMs with admonitions. This div will also hold a deeper
+    `.inner.py_mk_admonition_qcm` element...
+    """
+    elt: Getter
+
+    QUESTION_RULE: ClassVar[str] = "li.py_mk_question_qcm"
+    ITEM_RULE: ClassVar[str] = "li.py_mk_item_qcm"
+
+    def __post_init__(self):
+        self.no_admo   = self.elt.has_class('qcm_no_admo')
+        self.counter   = self.elt.find('.qcm-counter')
+        self.mask      = self.elt.find('.mask-svg')
+        self.check_btn = self.elt.find('.check-btn')
+        self.reset_btn = self.elt.find('.restart-btn')
+
+        self.inner_div = self.elt.find('.inner.py_mk_admonition_qcm')
+        self.shuffle_questions = self.inner_div.has_class('qcm_shuffle')
+
+
+    @classmethod
+    def from_page(cls, page: Type['BaseSeleniumPage'] ):
+        rule = ".qcm_no_admo.layout-qcm-wrapper, .admonition.py_mk_admonition_qcm, details.py_mk_admonition_qcm"
+        qcms = [ cls(qcm) for qcm in page.find(rule) ]
+        return qcms
+
+    def find(self, *a, **kw):
+        return self.elt.find(*a, **kw)
+
+    def get_questions(self):
+        return self.inner_div.find(self.QUESTION_RULE)
+
+    def get_items(self, question:Getter):
+        return question.find(self.ITEM_RULE)
+
+    def get_q_i_2D_array(self, target:str=""):
+        """
+        @target: final targeted element/Getter on each item. By default, the elements are `Getter<li>`.
+        Built at runtime, so can be used after shuffling.
+        """
+        out: List[List[Getter]] = []
+        for q in self.get_questions():
+            items = q.find(f"{ self.ITEM_RULE } { target }".rstrip())
+            out.append(items)
+        return out
+
+    def get_rems(self):
+        return self.elt.find('details.py_mk_comment_qcm')
+
+    def check_counter(self, expected:int):
+        self.counter.check.has_text(f"{expected}/")
+
+
+    def select(self, q_and_i:str):
+        """
+        Click on all the given (space separated) "question.items" (in this format `N.N`, as
+        NUMBERS, NOT INDICES).
+        To make sure the elements are clickable, they are handled in REVERSED order, the page
+        being scrolled at each new question to put the current item at the bottom of the page.
+        """
+        qis = self.get_q_i_2D_array('label')
+        last_q = None
+        lst = q_and_i.split()
+        for s in  lst:
+            q,i = map(int, s.split('.'))
+            q-=1 ; i-=1
+            if last_q != q:
+                qis[q][i].scroll_to()
+                last_q = q
+            qis[q][i].click().go
+
+
+    def check_selected(self, selected:str, svg_class: Union[str,Dict[str,str]]=None):
+        """
+        Check on all the given (space separated) "question.items" (in this format `N.N`, as
+        NUMBERS, NOT INDICES).
+        Test labels classes are verified, to be sure the svg will be properly formatted.
+        Anything that is not in the selected string must by `label.unchecked`.
+
+        @svg_class:
+        - If not given, use `checked` for items that should be ticked, and `unchecked` for others.
+        - If it is a string and the item is supposed to be ticked, the label's class must match svg_class
+        - If it is a dict, use the class in the corresponding value.
+        """
+        selected_ = { tuple(map(int, s.split('.'))) for s in  selected.split() }
+        wrongs = []
+
+        qis = self.get_q_i_2D_array('label')
+        wrongs.extend(
+            f'Question {i}, item {j}:  label.class (svg) should contain {target!r} but was {label.get.class_!r}.'
+            for i,items in enumerate(qis,1) for j,label in enumerate(items,1)
+            if not label.has_class(
+                    target:='unchecked' if (i,j) not in selected_ else
+                            'checked' if not svg_class else
+                            svg_class if isinstance(svg_class, str) else
+                            svg_class[f"{i}.{j}"]
+            )
+        )
+        assert not wrongs, f'By indices:\n' + '\n'.join(wrongs)
+
+
+    def validate(self):
+        self.check_btn.scroll_to()
+        self.check_btn.click().go
+
+    def validate_if_not_yet(self):
+        if not self.elt.find("label.missed, label.correct, label.incorrect").exists():
+            self.validate()
+
+    def reset(self):
+        self.reset_btn.scroll_to()
+        self.reset_btn.click().go
+
+
+    def snapshot(self):
+        """ Take a snapshot of the ids of the questions and their items (to test shuffling). """
+        elements = self.elt.find(self.QUESTION_RULE + ', ' + self.ITEM_RULE)
+        snap = '\n'.join(
+            '   '*elt.has_class("py_mk_item_qcm") + elt.get.id
+            for elt in elements
+        )
+        return snap

pmt_tools-0.1.0/pmt_tools/runners.py

@@ -0,0 +1,281 @@
+import re
+import datetime as dt
+from contextlib import contextmanager, nullcontext
+from dataclasses import dataclass, fields
+from typing import Callable, Generator, List, Optional, Type, TYPE_CHECKING, Union
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.common.alert import Alert
+from selenium.common.exceptions import UnexpectedAlertPresentException
+from selenium.webdriver.common.keys import Keys
+
+from ..selenium_query import Getter
+
+if TYPE_CHECKING:
+    from ..conftest import BaseSeleniumPage
+
+
+
+
+
+
+
+
+@dataclass
+class ButtonHolder:
+    cut_term:     'Button' = None
+    stdout_wraps: 'Button' = None
+
+    comment:      'Button' = None
+    two_cols:     'Button' = None
+    full_screen:  'Button' = None
+
+    play:         'Button' = None
+    check:        'Button' = None
+    download:     'Button' = None
+    upload:       'Button' = None
+    restart:      'Button' = None
+    save:         'Button' = None
+    zip:          'Button' = None
+
+    corr:         'Button' = None
+    reveal:       'Button' = None
+
+
+    def __post_init__(self):
+        # Setup delays strategies + archive the field name on the Button instance:
+        for f in fields(self.__class__):
+            btn: Optional[Button] = getattr(self, f.name)
+            if btn:
+                btn.name = f.name
+
+                if f.name in ('restart',):
+                    btn.delay = lambda d : d.switch_to.alert    # does not work properly è> to avoid
+
+                elif f.name in ('play','check','corr', 'save', 'zip'):
+                    btn.delay = None    # automatically wait for the execution flag
+
+    def __iter__(self) -> Generator['Button',None,None]:
+        return ( getattr(self, f.name) for f in fields(self.__class__))
+
+
+    @classmethod
+    def build_buttons(cls, runner:'Runner', *rules:str, expected=-1, in_page=False, **kw):
+        if kw and rules:
+            raise ValueError(
+                "Cannot create Buttons using both *rules and **kw arguments. Use one or the other."
+            )
+
+        if rules:
+            found = [runner.elt.find(rule, in_page=in_page) for rule in rules]
+            if expected<0:
+                expected = len(fields(cls))
+            if len(found)!=expected:
+                raise ValueError(
+                    f"Invalid ButtonHolder definition: found {len(found)} buttons but should be {expected}"
+                )
+            return cls(*map(Button, [runner]*len(found), found))
+
+        else:
+            return cls(**{name: Button(runner, runner.elt.find(rule, in_page=in_page)) for name,rule in kw.items() })
+
+
+
+
+
+@dataclass
+class Button:
+    runner: 'Runner'
+    elt: 'Getter'
+
+    delay: Union[int,None,Callable] = 0.1
+
+    name: str=None                  # Defined automatically from ButtonHolder
+
+    def click(self, extra_delay=None, *, prompt_before:str=None):
+        """
+        If the button is providing a prompt/alert, the selenium alert element is returned
+        """
+        ctx = self.runner.wait_executions_done(prompt_before=prompt_before) if self.delay is None else nullcontext()
+
+        with ctx:
+            self.elt.scroll_to().click().go
+
+        if callable(self.delay):
+            alert: Alert = self.elt.wait_until(self.delay)
+            return alert
+
+        elif self.delay:
+            self.elt.pause(self.delay).go
+
+        if extra_delay is not None:
+            self.elt.pause(extra_delay).go
+        return self
+
+
+    def check_tip_text(self, exp, contains=False, floating=False):
+        self.elt.scroll_to().move_to().go
+        elt = self.elt.find("#floating-tip", in_page=True) if floating else self.elt
+        if contains:
+            elt.check.has_text(exp)
+        else:
+            elt.check.text(exp)
+
+
+
+
+
+
+
+@dataclass(repr=False)
+class Runner:
+
+    elt: Getter
+
+    _js_runner: str = None
+    """
+    CONFIG.objs[self._js_runner] gives access to the current Runner in js (if exists).
+    """
+
+    def __post_init__(self):
+        # Works for both Ides and isolated terminals:
+        self._runner_id = self.elt.get.id.replace('global_','')
+        self._js_runner = f"CONFIG.objs.{ self._runner_id }"
+
+    def __repr__(self):
+        return f'{ self.__class__.__name__ }(class={self.elt.get.class_!r})'
+
+    @classmethod
+    def from_page(cls, page: Type['BaseSeleniumPage'] ):
+        from .terminal import Terminal
+        from .ide import Ide
+
+        # Suppress all the f... labels in jQuery.terminals
+        page.driver.execute_script("$('div.terminal-wrapper label, div.terminal-wrapper > svg').remove()")
+
+        runners: List[Runner] = []
+        for runner in page.find(".py_mk_ide, .term_solo, .py_mk_py_btn, .py_mk_auto_run"):
+            if runner.has_class('py_mk_ide'):
+                obj = Ide(runner)
+            elif runner.has_class('term_solo'):
+                obj = Terminal(runner)
+            elif runner.has_class('py_mk_py_btn'):
+                obj = PyBtn(runner)
+            elif runner.has_class('py_mk_auto_run'):
+                obj = AutoRun(runner)
+            else:
+                raise ValueError(f'Unknown runner class: { runner.get.class_ }')
+            runners.append(obj)
+        return runners
+
+
+    def run_js(self, code:str, *args, async_=False, with_promise=True):
+        """
+        Use driver.execute_script on the given code.
+        `@code` may be a string template where any `{js_runner}` will be replaced by the access
+        to the JS runner instance.
+
+        * `@args` are arguments that will be passed in the JS environment (available through the
+        `arguments` array).
+        * `@async_=False`: if True, JS script will run async?. An error is raised if `with_promise`
+        is False and `done` is not present in the code (a call to it is needed to resume execution).
+        * `@with_promise=True`: if True and the script is supposed to be run async, `code` is
+        expected to be a Promise (aka, no await in the source!) and `'.then(done, console.error)'`
+        is automatically added at the end of `code` to consume the promise and resume executions.
+        In that case, the `done` call is not needed in the source code.
+        """
+        # Escape all curly brackets for str.format...:
+        code = re.sub('([{}])', r'\1\1', code)
+        # But always restore '{{js_runner}}'!
+        code = code.replace('{{js_runner}}', '{js_runner}')
+
+        return self.elt.run_js(
+            code.format(js_runner=self._js_runner), *args, async_=async_, with_promise=with_promise,
+        )
+
+
+    @contextmanager
+    def wait_executions_done(self, timeout=3, *, prompt_before:str=None):
+        """
+        Generic logistic to wait for some JS Runner executions, with a default timeout at 3s.
+
+        1. Setup `js_runner.seleniumRunningFlag` to true value
+        2. Gives back control to the caller
+        3. Waits for `js_runner.seleniumRunningFlag` to become false again
+        4. Send back control to the caller.
+        """
+        start = dt.datetime.now()
+
+        # "Enforce" synchronization (rather, "make it less worse"):
+        # -> do not allow a test to start if the current runner is not done yet...
+        self._wait_until_runner_ready(start, timeout, 'setup')
+
+        self.run_js('{js_runner}.seleniumRunningFlag = true')
+        try:
+            yield None
+            # DOES NOT WORK:
+            # if prompt_before:
+            #     prompt: Alert = self.elt.wait_prompt_or_alert()
+            #     prompt.send_keys(prompt_before)
+            #     self.elt.pause(5)
+        except:
+            # Make sure the runner always ends up in a valid state (allow to continue the tests):
+            self.run_js('{js_runner}.seleniumRunningFlag = false')
+            raise
+
+        self._wait_until_runner_ready(start, timeout, 'end')
+
+
+    def _wait_until_runner_ready(self, start, timeout, step):
+        """
+        Automatically wait for the underlying JsRunner to be done with the current executions,
+        based on the `JsRunner.seleniumRunningFlag` flag.
+        """
+        self.elt.pause(0.05).go     # (seems to help with random failures...)
+
+        while self.run_js('return {js_runner}.seleniumRunningFlag'):
+            delta = (dt.datetime.now() - start).seconds
+            if delta > timeout:
+                assert False, f"Couldn't {step} test: { self._js_runner } stuck"
+            self.elt.pause(0.05).go
+
+        self.elt.pause(0.05).go     # (seems to help with random failures...)
+
+
+    def _send_shortcut(self, keys:str, *, exec=False, target:Getter=None, pause=None):
+        target = target or self.elt
+        ctx = exec and self.wait_executions_done()
+        target.send_shortcut(keys, waiting_context=ctx)
+        if pause:
+            self.elt.pause(pause).go
+
+
+    def pause(self, sec:float):
+        self.elt.pause(sec).go
+
+
+
+
+
+
+@dataclass(repr=False)
+class PyBtn(Runner):
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.button = ButtonHolder.build_buttons(self, play="button[btn_kind=py_btn]")
+
+    def check_alert_contains_on_click(self, msg:str):
+        try:
+            self.button.play.click()
+            assert False, "Should have raise UnexpectedAlertPresentException"
+        except UnexpectedAlertPresentException as e:
+            msg_err = str(e)
+            assert 'Unexpected alert dialog detected. Performed handler "dismiss"' in msg_err
+            assert msg in msg_err
+
+
+
+
+@dataclass(repr=False)
+class AutoRun(Runner):
+    pass

pmt_tools-0.1.0/pmt_tools/tabbed.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Type, Union
+
+from ..selenium_query import Getter
+
+if TYPE_CHECKING:
+    from ..conftest import BaseSeleniumPage
+
+
+
+
+
+
+
+
+@dataclass
+class TabbedContent:
+
+    elt: Getter
+
+    labels: Getter = None
+    contents: Getter = None
+
+    _label: Getter = None
+    _content: Getter = None
+
+    @classmethod
+    def from_page(cls, page: Type['BaseSeleniumPage'] ):
+        tabbed: List[TabbedContent] = [
+            TabbedContent(g) for g in page.find('div.tabbed-set')
+        ]
+        return tabbed
+
+    def __post_init__(self):
+        # Works for both Ides and isolated terminals:
+        self.labels   = self.elt.find('div.tabbed-labels > label')
+        self.contents = self.elt.find('div.tabbed-content > div.tabbed-block')
+        self._content = self.contents[0]
+
+    def click(self, idx:int):
+        self._label = self.labels[idx]
+        self._label.scroll_to().click().go
+        self._content = self.contents[idx]
+        self._content.check(
+            "Once the label is clicked, the corresponding content div should be visible."
+        ).css(display='block')
+        return self
+
+    def _refresh(self):
+        i = next(i for i,tab in enumerate(self.contents) if tab.css(display='block'))
+        self._content = self.contents[i]
+        self._label = self.labels[i]
+
+    def check_visible(self, i:int):
+        self.contents[i].check(
+            f"The content div at index {i} should now be visible."
+        ).css(display='block')
+
+    @property
+    def content(self):
+        """ Returns the current tab's content as Getter of the top level `div`. """
+        self._refresh()
+        return self._content
+
+    @property
+    def label(self):
+        """ Returns the current tab's label as Getter of the top level `div`. """
+        self._refresh()
+        return self._label
+
+

pmt_tools-0.1.0/pmt_tools/terminal.py

@@ -0,0 +1,237 @@
+from contextlib import contextmanager, nullcontext
+from dataclasses import dataclass
+import re
+from typing import ClassVar, Literal, Optional, Tuple, TypeVar, Union, overload
+
+from selenium.webdriver.common.keys import Keys
+
+from ..selenium_query import Getter, center_of
+from .runners import Runner, Button, ButtonHolder
+
+
+
+
+
+
+@dataclass(repr=False)
+class BaseTerminal(Runner):
+    """
+    The terminal `text` contains and extra trailing line: "\n Clipboard textarea for jQuery Terminal"
+    """
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.terminal = self.elt if self.elt.has_class("py_mk_terminal") else self.elt.find('.py_mk_terminal')
+
+        btns_rule = '.stdout-ctrl', '.stdout-wraps-btn'
+        kwargs = {'expected': 2}
+        if self.terminal.has_class('term_solo'):
+            # For isolated terminals, the btns are in the parent div... (Well done, Fred... :rolleyes:)
+            kwargs['in_page'] = True
+            btns_rule = (
+                f"#{ self.elt.get.id } + .term_btns_wrapper > { kls }" for kls in btns_rule
+            )
+        self.button = ButtonHolder.build_buttons(self, *btns_rule, **kwargs)
+
+
+    def check_current_cmd(self, expected:str, msg=""):
+        current = self.run_js('return {js_runner}.terminal.get_command()')
+        assert current == expected, f'{msg + ": "*bool(msg)}{current} should be {expected}'
+
+
+    def get_term_content(self) -> str :
+        """
+        The current terminal content, prompt included (>>>). WARNING : empty lines are ignored.
+        """
+        return self.run_js("""
+            const term = {js_runner}.termWrapper[0]
+            const rng = document.createRange()
+            rng.setStartBefore(term)
+            rng.setEndAfter(term)
+            const select = window.getSelection()
+            select.empty()
+            select.addRange(rng)
+            return {js_runner}.getTermSelectedText()
+        """)
+        # return self.terminal.find('.terminal-wrapper').get.text.rstrip()
+
+
+    def check_command(self, cmd:Optional[str], expected:str, *, clear=True, contains=False):
+        """
+        Clear the current terminal (unless @clear=False), then run the given command and check
+        that the expected string is the terminal content (or check that it is containing the expected
+        string, if @contains=True).
+
+        If @cmd is None, no command is run, and the terminal is not cleared (whatever the @clear value is).
+        """
+        if clear and cmd is not None:
+            self.clear_terminal()
+        if cmd is not None:
+            self.exec_term_cmd(cmd)
+        self.check_term_content(expected, contains=contains)
+        return self
+
+
+    def check_term_content(self, expected:str, *, contains=False):
+        """
+        Clear the current terminal (unless @clear=False), then run the given command and check
+        that the expected string is the terminal content (or check that it is containing the expected
+        string, if @contains=True).
+
+        If @cmd is None, no command is run, and the terminal is not cleared (whatever the @clear value is).
+        """
+        if contains:
+            self.terminal.check.has_text(expected)
+        else:
+            self._assert_term_content(expected)
+        return self
+
+
+    @staticmethod
+    def _prepare_content(content:str):
+        """
+        Remove any trailing whitespace in actual/expected strings (because the jQuery Terminal
+        is just messing around, like usual...)
+        """
+        return re.sub(r' +$', '', content.rstrip(), flags=re.M)
+
+    def _assert_term_content(self, expected:str):
+        actual = self._prepare_content(self.get_term_content())
+        expected = self._prepare_content(expected)
+        assert actual==expected, f"Wrong terminal content.\n{actual}\n  should be\n{expected}"
+
+
+    def exec_term_cmd(self, cmd:str):
+        """
+        Execute directly the given command (without going through UI interactions).
+        """
+        assert "\n" not in cmd, (
+            "Terminal commands in selenium should never be multiline (not possible to spot "
+            "the end of executions)"
+        )
+        cmd = cmd.replace('"', '\\"')
+        return self.run_js(f'{{js_runner}}.terminal.exec("{ cmd }")', async_=True)
+
+    def run_command(self, cmd:str):
+        """
+        Type the given command un the terminal and execute it by typing it in the terminal
+        (and pressing Enter at the end).
+        """
+        self.terminal.scroll_to().send_keys(cmd, Keys.RETURN).go
+        return self
+
+    def clear_terminal(self):
+        self.run_js("{js_runner}.terminal.clear() ; {js_runner}.terminal.set_command('')")
+
+
+    def terminal_shortcut(self, keys:str, *, exec=False):
+        self._send_shortcut(keys, exec=exec, target=self.terminal.find('textarea'))
+        raise NotImplementedError('verify if this works or not...')
+
+
+    def clean_then_type_in_terminal(self, cmd):
+        self.clear_terminal()
+        self.run_command(cmd)
+
+    def send_keys_terminal(self, *keys, execute=False):
+        self.terminal.scroll_to()
+        execute = execute or (Keys.RETURN in keys) or (Keys.ENTER in keys)
+        ctx = self.wait_executions_done() if execute else nullcontext()
+        with ctx:
+            self.terminal.send_keys(*keys).go
+
+
+
+
+
+MsLang = TypeVar('ML_Lang', bound=str)
+"""
+Mini script Language: dots separated instructions, used to accomplish various actions
+through TerminalSelector.chain.
+
+    prompt.>>
+    cmd.-1.abcde
+    output.5.sort of
+    cmd.abcde
+    output.-2."Use quotes for dots..."
+    output.-2.'Use quotes for dots...'
+
+    If no line index is given, assume it is 0.
+"""
+
+TERM_SECTIONS = "prompt","output","cmd"
+
+
+
+@dataclass(repr=False)
+class TerminalSelector(BaseTerminal):
+    """ Handle the logistic to use text selections through mouse actions in the terminal. """
+
+
+    def double_click_prompt(self):
+        """
+        Double click on the prompt (always present!), to highlight the window selection.
+        This won't move the cursor in the command line, if it is already set.
+        """
+        self.terminal.find("span.cmd-prompt").double_click().go
+
+
+    def set_cursor(self, location:Literal[0,1,-1]):
+        lines = self.terminal.find('.cmd-wrapper > div')
+        idx   = location if location!=1 else lines.count() // 2
+        line  = lines[idx]
+
+        # No need to distinguish the line currently holding the cursor from the others, even if its
+        # DOM layout is different: searching for `span[data-text]` will automatically linearize/simplify
+        # the reasoning:
+        chars = line.find('span[data-text]')
+        idx_c = location if location!=1 else chars.count() // 2
+        char  = chars[idx_c]
+        char.click().go
+
+
+    def select(self, start_cmd:MsLang, end_cmd:MsLang):
+        start, i_start, chars_start = self._sanitize_cmd(start_cmd)
+        end, i_end, chars_end = self._sanitize_cmd(end_cmd)
+
+        # Make sure the selection will be visible by double clicking something first...
+        self.terminal.find('span.cmd-prompt').double_click().go
+
+        self.run_js(f"""
+        new window.TerminalSelector(
+            "#{ self._runner_id }",
+            [{start!r}, {i_start}, {chars_start!r}],
+            [{end!r}, {i_end}, {chars_end!r}]
+        ).makeSelection()
+        """)
+
+
+    def _sanitize_cmd(self, cmd:str):
+        part, *segments = cmd.split('.')
+        if part not in TERM_SECTIONS:
+            raise ValueError(
+                f"Invalid section name: {part} should be a member of {TERM_SECTIONS}"
+            )
+
+        if len(segments)==1 or not re.fullmatch(r'-?\d+', segments[0]):
+            idx,chars = 0, '.'.join(segments)
+        else:
+            idx,chars = int(segments[0]), '.'.join(segments[1:])
+        chars = chars.strip("'\"")
+
+        return part, idx, chars
+
+
+    def get_term_selected_text(self):
+        return self.run_js("return {js_runner}.getTermSelectedText()")
+
+    def check_term_selected_text(self, expected, *, show=str):
+        actual = self.get_term_selected_text()
+        assert actual==expected, f"Invalid selected text:\n{show(actual)}\n  SHOULD BE:\n{show(expected)}"
+
+
+
+
+
+
+class Terminal(TerminalSelector): pass

pmt_tools-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "pmt-tools"
+version = "0.1.0"
+description = "Helpers for Pyodide-MkDocs-Theme selenium testing"
+authors = [
+    {name = "Frédéric Zinelli",email = "frederic.zinelli@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.9, <4.0"
+dependencies = [
+    "selenium-query",
+    "selenium (>=4.36)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"