qa-agent-kit 0.6.0__py3-none-any.whl

qakit/docs/getting-started.md

@@ -0,0 +1,100 @@
+# Getting started
+
+QAKit has three parts. Use the ones your project needs.
+
+| Part | Needs | Gives |
+|---|---|---|
+| `skills/qa-rigor` + `tools/mutate.py` | Python 3.11+, your test command | Test-strength measurement for any language with tests (Python and C-family syntax: Swift, JS/TS, Kotlin, Go, Java, C#) |
+| `skills/device-qa` + `tools/device_qa.py` + `tools/release_checks.py` | macOS, Xcode 27+, a USB-attached iPhone with Developer Mode | Real-device QA runs under variants, screenshots, crash reports, static App Store checks |
+| Swift package `QAKit` | Xcode 15+ (iOS 17+), a UI-test target | Evidence, accessibility audit, button sweeps, system alert handling inside XCUITest |
+
+## 1. Get the repo
+
+```bash
+git submodule add https://github.com/younatics/QAKit.git vendor/qakit    # or clone it anywhere
+python3 vendor/qakit/tools/device_qa.py --help
+```
+
+Pin a release tag (`git -C vendor/qakit checkout v0.1.0`) and update on purpose; `CHANGELOG.md` lists what each tag
+changes.
+
+## 2. Mutation testing (any project)
+
+Write a config next to your tests:
+
+```json
+{"name": "api", "root": ".", "sources": ["src/**/*.py"], "exclude": ["src/**/migrations/*"],
+ "test": "{orig}/.venv/bin/python -m pytest -x -q -p no:cacheprovider", "jobs": 3}
+```
+
+```bash
+python3 vendor/qakit/tools/mutate.py --config mutation.json --list                    # what would be mutated
+python3 vendor/qakit/tools/mutate.py --config mutation.json --changed-since origin/main
+```
+
+Exit 0 means every mutant died. Survivors are listed in `<out>/mutation.md` with the line and the change; each one gets a
+test or a `mutation-ok: <reason>` comment. `skills/qa-rigor/SKILL.md` has the full procedure and the pitfalls.
+
+## 3. Link QAKit into a UI-test target
+
+In Xcode: File > Add Package Dependencies > Add Local (the `vendor/qakit` folder) or the GitHub URL, then add the `QAKit`
+library to the **UI-test target only** (it imports XCTest). With a generated project, add the package as a local
+`XCLocalSwiftPackageReference` on that target, or compile `Sources/QAKit/QAKit.swift` into the UI-test target directly
+(the file has no other dependency).
+
+Then write the walkthrough:
+
+```swift
+import XCTest
+import QAKit
+
+final class MyAppQAWalkthroughTests: XCTestCase {
+    private var app: XCUIApplication!
+
+    override func setUpWithError() throws {
+        continueAfterFailure = true          // a QA walk records every problem instead of stopping at the first
+        app = XCUIApplication()
+        app.launchArguments = ["-ui-testing"] + QA.languageArguments
+        app.launch()
+        QA.settleAfterLaunch(app)          // the VoiceOver welcome or a permission prompt left over the app
+    }
+
+    func testWalkSettings() {
+        app.tabBars.buttons["Settings"].tap()
+        let screen = app.otherElements["settings.screen"]
+        XCTAssertTrue(screen.waitForExistence(timeout: 5))
+        QA.walk(app, "settings", in: self, deny: ["Delete", "Call"]) {
+            QA.settle(self.app, on: screen, in: self, closers: ["settings.done"]) {
+                self.app.terminate(); self.app.launch(); self.app.tabBars.buttons["Settings"].tap()
+            }
+        }
+    }
+}
+```
+
+`QA.walk` screenshots the screen, runs Apple's accessibility audit (every issue in one attached report), taps every visible
+button once (screenshot of what opened, a check that the app is still in front, then your `settle` closure), scrolls and
+repeats until the bottom. `QA.settle` closes whatever is on top and relaunches only as the last resort.
+
+## 4. Write the manifest and run on the phone
+
+```bash
+cp vendor/qakit/examples/device_qa.json MyApp/release/testing/device_qa.json   # edit paths, suites, variants
+python3 vendor/qakit/tools/device_qa.py doctor --manifest MyApp/release/testing/device_qa.json
+python3 vendor/qakit/tools/device_qa.py test --manifest MyApp/release/testing/device_qa.json --suite qa --variant dark --variant large-text
+```
+
+`docs/manifest.md` explains every key; `docs/report.md` explains the output folder. The phone needs Developer Mode on, no
+passcode, and (first run only) a tap on the UI automation prompt.
+
+## 5. Static submission checks
+
+```bash
+python3 vendor/qakit/tools/release_checks.py --manifest MyApp/release/testing/device_qa.json
+python3 vendor/qakit/tools/release_checks.py --manifest MyApp/release/testing/device_qa.json --ipa build/MyApp.ipa
+```
+
+## 6. Give the agent the procedure
+
+Link `skills/qa-rigor` and `skills/device-qa` into your agent's skills folder (`skills/README.md`) and point your
+AGENTS.md or CLAUDE.md at `docs/device-qa-protocol.md`. The protocol's exit criteria are the release verdict.